hotline.tg

Hotline Topics API (v1)

Topics API предназначено для интеграции Hotline Telegram CRM с внешними системами. Данный документ описывает основные методы интерфейса.

Основной метод позволяет получить информацию об источнике топика на стороне бекенд-группы. Также есть метод для отправки входящего сообщения в топик по user_id пользователя.

Примеры расширения функционала системы Hotline с использованием Topics API через своего бота помощника описаны в отдельной статье.

Адрес интерфейса

https://n8n.hotline.tg/webhook/topic_action

Обрабатывает только POST запросы
На данный момент для обращения к интерфейсу обязательно иметь Header x-api-key, в котором указывается токен выданный службой поддержки
У каждого instance также есть свой api_key, который получается в @hotlinetg_bot для каждого инстанса, и который указывается непосредственно в теле JSON запросов

Метод 1: Доступная информация по топику

Пример запроса:

{
    "action": "info_by_topic",
    "group_id": "2101424779", # as it appers in topic public link (without -100)
    "topic_id": "$TOPIC_ID",  # as it appers in topic public link

    "instance": "$INSTANCE",
    "api_key": "$KEY"
}

Пример ответа для пользователя:

{
    "result": "topic_info",
    "group_id": $GROUP_ID,
    "topic_id": $TOPIC_ID,

    "frontend_type": "private",
    "instance_name": "$INSTANCE_NAME",
    "instance_frontend_user_id": $INSTANCE_FRONTEND_USER_ID,
    "instance_id": $INSTANCE_ID,

    "chat_id": $CHAT_ID,
    "thread_id": $THREAD_ID,

    "topic_last_date": "$LAST_DATE",
    "topic_status": "$STATUS",
    "topic_title": "$TITLE",

    "user_id": $USER_ID,
    "user_name": "$NAME",
    "user_first_name": "$FNAME",
    "user_last_name": "$LNAME",
    "user_username": "$USERNAME",
    "user_lang": "None",
    "user_phone": "None"
}

Пример ответа для групп:

{
    "result":"topic_info",

    "group_id": $GROUP_ID,
    "topic_id": $TOPIC_ID,

    "frontend_type": "group",
    "instance_name": "$INSTANCE_NAME",
    "instance_frontend_user_id": $INSTANCE_FRONTEND_USER_ID,
    "instance_id": $INSTANCE_ID,

    "frontend_chat_id": $CHAT_ID,

    "topic_last_date": "$LAST_DATE",
    "topic_status": "$STATUS",
    "topic_title": "$TITLE"
}

Особенности:

Topic_status имеет 3 значения: 'closed','user_answered','support_answered' (показываются в названии топика черным, фиолетовым и желтым квадратом соответственно)
Виды frontend_type: private (обычный пользователь), bot, secret, group, supergroup, topic, channel
Полная информация пока выдается только по топикам: private, bot, secret
Если к одной бекенд-группе привязано несколько инстансов, то можно использовать любой из них для получения информации о топиках в группе (инстанс конкретного топика будет показан в соответствующих полях ответа)

Метод 2: Входящее сообщение в топик по user_id

Пример запроса:

{
    "action": "incoming_in_topic",
    "user_id": $USER_ID1,
    "message": "/ `test` *incoming* _message_ \n\n [@hotlinetg_support]",

    "instance": "$INSTANCE",
    "api_key": "$KEY"
}

Пример ответа:

{
    "result": "message_sent",
    "topic_link": "https://t.me/c/2101424779/1591",
    "message": "/ `test` *incoming* _message_ \n\n [@hotlinetg_support]",
    "chat_id": $CHAT_ID,
    "thread_id": "$THREAD_ID"
}

Получение доступа к Topics API

Для получения x-api-key токена для доступа к API, либо расчета стоимости интеграции и поддержки, необходимо написать в службу поддержки @hotlinetg_support.