API Topics (v1)¶

REST API per l'integrazione programmatica di Hotline CRM con sistemi esterni.

Ottieni informazioni sui dialoghi e invia messaggi ai topic del gruppo backend.

Funzionalità a pagamento

L'utilizzo di Webhooks e REST API è disponibile solo per gli utenti premium di Hotline. Per acquistare la versione a pagamento del sistema, contattare il nostro servizio di supporto.

Capacità API¶

Ottieni informazioni topic — dati dialogo, stato, informazioni utente o chat
Invia messaggi ai topic — invia messaggi ai topic per operatori per user_id specificato

Endpoint¶

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

Requisiti:

	Descrizione
Metodo richiesta	`POST`
HTTP-Header	`X-API-KEY` con token di accesso proprietario connessioni (rilasciato dal servizio di supporto)
Body:	JSON con campi `instance` e `api_key` della connessione specifica (ottenuto nel bot di configurazione)

Metodo: Ottieni Informazioni Topic¶

Il metodo info_by_topic restituisce informazioni complete sul dialogo tramite identificatori topic.

Esempio richiesta POST

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

Estrazione ID dal link

Link topic: https://t.me/c/2101424779/5343
→ group_id: 2101424779
→ topic_id: 5343

Esempio risposta per topic utente

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

Esempio risposta per topic 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"
}

Più connessioni

Se più frontend sono collegati al sistema, puoi usare uno qualsiasi di essi per ottenere informazioni
La risposta indicherà a quale connessione appartiene il topic specifico

Metodo: Invia Messaggio al Topic¶

Il metodo incoming_in_topic crea un messaggio per gli operatori nel topic con il dialogo dell'utente specificato.

Esempio richiesta

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

Esempio risposta

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

Raccomandazioni¶

Conserva x-api-key e api_key in luogo sicuro (variabili d'ambiente, secrets)
Usa HTTPS per tutte le richieste API
Registra tutte le richieste API per auditing
Implementa retry logic con exponential backoff
Imposta timeout richiesta ad almeno 10 secondi
Considera rate limiting della frequenza quando fai operazioni di massa
Dimensione massima messaggio — 4096 caratteri (limitazione Telegram)

Ottenimento Accesso¶

Per ottenere il token x-api-key e connettere l'API Topics:

Scrivi al servizio di supporto
Descrivi brevemente il tuo scenario di utilizzo API
Ricevi il token di accesso x-api-key e consulenza tecnica