Topics API (v1)¶

REST API para integración programática de Hotline CRM con sistemas externos.

Obtener información sobre diálogos y enviar mensajes a temas de grupo backend.

Función de pago

Los webhooks y el uso de REST API solo están disponibles para usuarios premium de Hotline. Para comprar la versión pagada del sistema, contacta con nuestro servicio de soporte.

Capacidades de API¶

Obtener información de tema — datos de diálogo, estado, información de usuario o chat
Enviar mensajes a temas — enviar mensajes a temas para operadores por user_id especificado

Endpoint¶

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

Requisitos:

	Descripción
Método de solicitud	`POST`
HTTP-Header	`X-API-KEY` con token de acceso del propietario de conexiones (emitido por servicio de soporte)
Body:	JSON con campos `instance` y `api_key` de conexión específica (obtenidos en bot de configuración)

Método: Obtener Información de Tema¶

El método info_by_topic devuelve información completa sobre diálogo por identificadores de tema.

Ejemplo de solicitud POST

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

Extracción de ID del enlace

Enlace de tema: https://t.me/c/2101424779/5343
→ group_id: 2101424779
→ topic_id: 5343

Ejemplo de respuesta para tema de usuario

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

Ejemplo de respuesta para tema de chat

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

Múltiples conexiones

Si múltiples frontends están vinculados al sistema, puedes usar cualquiera de ellos para obtener información
La respuesta indicará a qué conexión pertenece el tema específico

Método: Enviar Mensaje a Tema¶

El método incoming_in_topic crea mensaje para operadores en tema con diálogo de usuario especificado.

Ejemplo de solicitud

{
  "action": "incoming_in_topic",
  "user_id": 987654321,
  "message": "El estado del usuario ha cambiado: OFERTA CONFIRMADA",
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Ejemplo de respuesta

{
  "result": "message_sent",
  "topic_link": "https://t.me/c/2101424779/5343",
  "message": "El estado del usuario ha cambiado: OFERTA CONFIRMADA",
  "chat_id": "-1002101424779",
  "thread_id": 5602541568
}

Recomendaciones¶

Almacena x-api-key y api_key en lugar seguro (variables de entorno, secretos)
Usa HTTPS para todas las solicitudes de API
Registra todas las solicitudes de API para auditoría
Implementa lógica de reintento con retroceso exponencial
Establece tiempo de espera de solicitud a al menos 10 segundos
Considera limitación de tasa de frecuencia al hacer operaciones masivas
Tamaño máximo de mensaje — 4096 caracteres (limitación de Telegram)

Obtener Acceso¶

Para obtener token x-api-key y conectar Topics API:

Escribe al servicio de soporte
Describe brevemente tu escenario de uso de API
Recibe token de acceso x-api-key y consulta técnica