Webhooks¶

Receive events from Hotline dialogs as POST requests in JSON format for integration with your systems.

Capabilities¶

The Webhooks module allows:

• Track system events — dialog creation, closing and reopening, message receiving and sending.
• Process custom commands — both standard /mark, /info, and your own /invoice, /user and any others.
• Return responses to topics — command execution results can be shown directly in customer topics.

Configuration¶

Webhooks are configured through setup bot @hotlinetg_bot in the WEBHOOKS connection parameter.

Configuration format: JSON object where keys are URLs of your scripts and values are arrays of events to track:

Example JSON Configuration¶

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

!!! tip \"Multiple addresses\" You can specify multiple URLs for different event sets — for example, one for receiving events about messages and dialogs, and another for processing your commands.

System Events¶

Automatic notifications about dialog events. Sent without waiting for response from your server.

Available Dialog Events¶

Available Message Events¶

Usage Scenarios¶

• Sending automatic messages by timeout after dialog start
• Monitoring operator response time to requests
• Checking messages for company policy compliance
• Collecting data for external analytics
• Recording dialogs for AI model training
• Duplicating messages to corporate database

Example Request: Dialog Reopening¶

{
  \"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 Request: 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\"
}

Custom Commands¶

Events about operator command calls. Your server can log corresponding event and return response that will be shown in dialog topic.

• Specify standard system commands in JSON config: /info, /mark, /close
• Set your own commands: /invoice, /client, /order
• Return execution result as text or JSON if needed

Usage Scenarios¶

• Extending /info with additional customer information from another CRM
• Logging status changes via /mark for analytics
• Creating invoice with /invoice command with link return
• Getting customer data from database by /user
• Business process automation by command trigger

Example Request: Command /mark¶

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

Response Format¶

Your server can return result as plain text or JSON with message or error nodes.

Successful execution:

{
  \"message\": \"Deal created: http://internal.domain.com/crm/deals/76238\",
  \"status\": \"ok\"
}

Execution error:

{
  \"error\": \"User 12345678 not found in our database\"
}

Text response:

You can return just text with Markdown v2 support:

✅ Invoice №12345 created
Total: 1500
Link: https://intranet.example.com/invoice/12345

!!! failure \"Other JSON nodes are ignored\" In case of JSON response, Hotline only processes message and error nodes.

Security¶

All requests from Hotline contain api_key field of corresponding connection for sender verification.

• Verify api_key on your side
• Configure filtering by Hotline proxy server IP
• Use HTTPS for Webhooks URL

Practical Scenarios¶

Debugging Tips¶

1. Use services for testing Webhooks: postman.com, requestbin.com
2. Log all incoming requests on your server
3. Return correct HTTP response status (should be 200 OK)
4. Monitor timeout — response should come quickly (recommended up to 3 seconds)
5. Handle errors gracefully and return understandable messages

!!! example \"Use test connections\" For debugging, create test connection to make it easier to control incoming event flow and debug events with different properties.

Limitations¶

• Command response timeout — recommended no more than 3 seconds
• Response size — up to 4096 characters (Telegram limitation)
• Retry attempts — if your server is unavailable, request may be retried
• Rate limits — with large event flow consider your server capabilities

Support¶

For questions about webhook setup, paid subscription connection, contact support service @hotlinetg_support