Webhooks module
Receiving events from dialogs Hotline as POST-requests in the format JSON to an external script for further processing.
In the installation bot @hotlinetg_bot via connection parameter @WEBHOOKS@ You can set one or more addresses for processing outgoing POST-requests from the outside Hotline about events in dialogues.
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.
Outgoing requests from the side Hotline to the specified addresses with the specified event types contain all the basic information about the corresponding topic and/or user for subsequent processing, as well as the field api_key The corresponding connection for sender verification. If necessary, you can configure additional sender verification on your side using our proxy server's IP address.
Example JSON to configure the parameter @WEBHOOKS@:
{
"https://someapiserver.com/webhooks/test-hook1": [
"dialog_created",
"dialog_reopened",
"dialog_closed",
"message_received",
"message_sent",
"message_intercepted"
],
"https://someapiserver.com/webhooks/test-hook2": [
"/mark", "/info",
"/invoice", "/client"
]
}You can receive two types of requests from Hotline:
System events – about the opening, closing, or reopening of dialogs, the receipt of incoming or sending of outgoing messages by operators, or from parallel sessions. These events are convenient for analytics systems or for additional message storage in your database (including for AI assistants).
Custom commands – reports on the use of specified commands by operators that begin with the symbol / (slash). Can be monitored as standard system commands (for example /mark or /close), as well as any custom commands, for example /invoice (generate an invoice), /client (get information about the client by his user_id в Telegram). Events of the second type can return a response, which will be displayed in the topic with the corresponding dialog. These events are convenient for implementing custom commands that can significantly expand Hotline's functionality or speed up operator work.
System events – about the opening, closing, or reopening of dialogs, the receipt of incoming or sending of outgoing messages by operators, or from parallel sessions. These events are convenient for analytics systems or for additional message storage in your database (including for AI assistants).
Custom commands – reports on the use of specified commands by operators that begin with the symbol / (slash). Can be monitored as standard system commands (for example /mark or /close), as well as any custom commands, for example /invoice (generate an invoice), /client (get information about the client by his user_id в Telegram). Events of the second type can return a response, which will be displayed in the topic with the corresponding dialog. These events are convenient for implementing custom commands that can significantly expand Hotline's functionality or speed up operator work.
Webhooks are available only to paid users of the system.
To purchase a paid subscription or connect a trial for several days to test the function, please contact @hotlinetg_support
Type 1: System Events
System events are defined from a fixed set of values. System events are sent without returning any results to the corresponding dialog topic.
The following types of events are currently available: dialog_created, dialog_reopened, dialog_closed, message_received, message_sent, message_intercepted.
Examples of using system events in dialogs:
- sending additional messages to the user after the start of a dialogue (for example, after a timeout)
- additional monitoring of incoming and outgoing messages by keywords or the meaning of messages for violations by operators
- control of operator response times to incoming requests
- collecting data for analytics on dialogues and/or operators in an external system
- recording messages in an external system to train the AI module
Example of an outgoing request to reopen a dialog:
{
"event_type": "dialog_reopened",
"timestamp": "2025-10-09 00:24:55",
"instance_id": "13209946874612345",
"data": {
"chat_id": -1002146012345,
"thread_id": 5602541568,
"topic_id": 5343,
"topic_link": "https://t.me/c/2146012345/5343",
"user_id": 5339212345,
"frontend_chat_id": 5339212345,
"frontend_topic_id": null,
"frontend_topic_link": null,
"frontend_user_id": 6406751371,
"chat_type": "private",
"title": "Some User Name",
"department": "default"
},
"api_key": "pQTngMZLh0NmAh"
}Example of an outgoing request for a sent message:
{
"event_type": "message_sent",
"timestamp": "2025-10-09 00:21:57",
"instance_id": "132099468746812345",
"data": {
"backend_chat_id": -1002146012345,
"backend_thread_id": 5602541568,
"backend_message_id": 6171918336,
"sender_user_id": 5339212345,
"frontend_user_id": 640675123,
"frontend_message_id": 3260022784,
"text": "test message",
"content_type": "messageText",
"department": "default",
"backend_reply_message_id": 0
},
"api_key": "pQTngMZLh0NmAh"
}Type 2: Custom commands
Any command that starts with the symbol / (slash) can be specified as a value to receive events about it and information about the corresponding dialog.
You can specify both existing standard system commands (/info, /mark, /close etc.), as well as custom ones, for the logic of actions of which your script will be responsible and, if necessary, return the result to the topic in the form JSON or a text message (markup in the format is allowed) Markdown v2).
Examples of using webhooks with custom commands:
- extension of the standard command /info additional information about the user
- logging changes in dialog statuses by operators via a command /mark
- logging of events of closing requests by the command /close
- adding your own commands, for example /invoice, /client or any other that requires information about the topic in which the conversation is taking place and user or chat data.
Example of a command call request /mark deal operator:
{
"event_type": "/mark",
"timestamp": "2025-10-08 20:41:20",
"instance_id": "132099468746812345",
"data": {
"command_data": "deal",
"chat_id": -1002146012345,
"topic_id": 5,
"topic_link": "https://t.me/c/2146012345/5",
"message_id": 5850,
"reply_message_id": null,
"sender_user_id": 123456,
"user_id": 7890123,
"frontend_chat_id": 7890123,
"frontend_thread_id": null
},
"api_key": "pQTngMZLh0NmAh"
}To display the result of a command in a topic, your server's response must be either in plain text or in the form JSON, which has a node with the name message or error (other nodes will be ignored).
An example of a successful response from your server in the format JSON with a message that will be shown in the topic with the dialogue:
{
"message": "Deal created: http://internal.domain.com/crm/deals/76238",
"status": "ok"
}An example of your server's response with the error text in the format JSON, which will be shown in the topic with the dialogue:
{
"error": "User 12345678 not found in our database"
}For questions about webhooks, or to activate a paid subscription or trial, please contact support. @hotlinetg_support.