hotline.tg

Hotline Topics API (v1)

Topics API designed for integration Hotline Telegram CRM with external systems. This document describes the main methods of the interface.

The main method allows you to obtain information about the source of the topic on the side of the backend group. There is also a method for sending an incoming message to a topic by user_id user.

Examples of expanding the functionality of the system Hotline using Topics API through your assistant bot are described in a separate article.

Attention: This page contains fragments with automatic translation. If you have difficulty understanding this information, try switching the language to English or Russian and use your trusted system for translating websites.

Interface address

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

Processes only POST requests
At the moment, to access the interface it is necessary to have a Header x-api-key, which indicates the token issued by Support Service
Each instance also has its own api_key, which is obtained from @hotlinetg_bot for each instance, and which is specified directly in the body of the JSON requests

Method 1: Available information on the topic

Request example:

{
    "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"
}

Example response for a user:

{
    "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"
}

Example response for groups:

{
    "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"
}

Features:

Topic_status has 3 values: 'closed', 'user_answered', 'support_answered' (shown in the topic title as a black, purple and yellow square respectively)
Types of frontend_type: private (regular user), bot, secret, group, supergroup, topic, channel
For now, complete information is provided only for the following topics: private, bot, secret
If several instances are bound to one backend group, then any of them can be used to get information about topics in the group (the instance of a specific topic will be shown in the corresponding response fields)

Method 2: Incoming message to topic by user_id

Request example:

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

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

Answer example:

{
    "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"
}

Gaining access to Topics API

To get x-api-key token to access the API, or calculate the cost of integration and support, you need to write to support @hotlinetg_support.