Topics API (v1)¶

REST API for programmatic integration of Hotline CRM with external systems.

Get information about dialogs and send messages to backend group topics.

Paid feature

Webhooks and REST API usage are only available for Hotline premium users. To purchase paid version of system, contact our support service.

API Capabilities¶

Get topic information — dialog data, status, user or chat information
Send messages to topics — send messages to topics for operators by specified user_id

Endpoint¶

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

Requirements:

	Description
Request method	`POST`
HTTP-Header	`X-API-KEY` with connections owner access token (issued by support service)
Body:	JSON with `instance` and `api_key` fields of specific connection (obtained in setup bot)

Method: Get Topic Information¶

Method info_by_topic returns complete information about dialog by topic identifiers.

Example POST request

{
  "action": "info_by_topic",
  "group_id": "2101424779",
  "topic_id": 5343,
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Extracting ID from link

Topic link: https://t.me/c/2101424779/5343
→ group_id: 2101424779
→ topic_id: 5343

Example response for user topic

{
  "result": "topic_info",

  "group_id": "2101424779",
  "topic_id": 5343,

  "frontend_type": "private",
  "instance_name": "support_bot",
  "instance_frontend_user_id": 123456789,
  "instance_id": "132099468746812345",

  "chat_id": -1002101424779,
  "thread_id": 5602541568,

  "topic_last_date": "2025-10-09 00:24:55",
  "topic_status": "user_answered",
  "topic_title": "John Doe",

  "user_id": 987654321,
  "user_name": "John Doe",
  "user_first_name": "John",
  "user_last_name": "Doe",
  "user_username": "john1991",
  "user_lang": "en",
  "user_phone": "+12125550123"
}

Example response for chat topic

{
  "result": "topic_info",

  "group_id": "2101424779",
  "topic_id": 5344,

  "frontend_type": "group",
  "instance_name": "support_bot",
  "instance_frontend_user_id": 123456789,
  "instance_id": "132099468746812345",

  "frontend_chat_id": -1001234567890,

  "topic_last_date": "2025-10-09 00:30:00",
  "topic_status": "support_answered",
  "topic_title": "Somebiz Proposal Chat"
}

Multiple connections

If multiple frontends are linked to system, you can use any of them to get information
Response will indicate which connection the specific topic belongs to

Method: Send Message to Topic¶

Method incoming_in_topic creates message for operators in topic with specified user's dialog.

Example request

{
  "action": "incoming_in_topic",
  "user_id": 987654321,
  "message": "User status is changed: DEAL CONFIRMED",
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Example response

{
  "result": "message_sent",
  "topic_link": "https://t.me/c/2101424779/5343",
  "message": "User status is changed: DEAL CONFIRMED",
  "chat_id": "-1002101424779",
  "thread_id": 5602541568
}

Recommendations¶

Store x-api-key and api_key in secure place (environment variables, secrets)
Use HTTPS for all API requests
Log all API requests for auditing
Implement retry logic with exponential backoff
Set request timeout to at least 10 seconds
Consider rate limiting frequency when doing mass operations
Maximum message size — 4096 characters (Telegram limitation)

Getting Access¶

To get x-api-key token and connect Topics API:

Write to support service
Briefly describe your API usage scenario
Receive access token x-api-key and technical consultation