Webhooks¶

Ricevi eventi dai dialoghi Hotline come richieste POST in formato JSON per l'integrazione con i tuoi sistemi.

Capacità¶

Il modulo Webhooks consente di:

• Tracciare eventi di sistema — creazione, chiusura e riapertura dialoghi, ricezione e invio messaggi.
• Elaborare comandi personalizzati — sia standard /mark, /info, che propri /invoice, /user e qualsiasi altro.
• Restituire risposte ai topic — i risultati dell'esecuzione dei comandi possono essere mostrati direttamente nei topic dei clienti.

Configurazione¶

I Webhooks vengono configurati tramite il bot di configurazione @hotlinetg_bot nel parametro di connessione WEBHOOKS.

Formato di configurazione: oggetto JSON dove le chiavi sono gli URL dei tuoi script e i valori sono array di eventi da tracciare:

Esempio di Configurazione JSON¶

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

Eventi di Sistema¶

Notifiche automatiche sugli eventi dei dialoghi. Inviate senza attendere risposta dal tuo server.

Eventi di Dialogo Disponibili¶

Eventi di Messaggio Disponibili¶

Scenari di Utilizzo¶

• Invio messaggi automatici per timeout dopo inizio dialogo
• Monitoraggio tempo di risposta operatore alle richieste
• Verifica messaggi per conformità alle politiche aziendali
• Raccolta dati per analisi esterne
• Registrazione dialoghi per training modelli AI
• Duplicazione messaggi nel database aziendale

Esempio Richiesta: Riapertura Dialogo¶

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

Esempio Richiesta: Messaggio Inviato¶

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

Comandi Personalizzati¶

Eventi sulle chiamate di comandi operatore. Il tuo server può registrare l'evento corrispondente e restituire una risposta che verrà mostrata nel topic del dialogo.

• Specifica comandi di sistema standard nella configurazione JSON: /info, /mark, /close
• Imposta i tuoi comandi: /invoice, /client, /order
• Restituisci il risultato dell'esecuzione come testo o JSON se necessario

Scenari di Utilizzo¶

• Estensione /info con informazioni aggiuntive sul cliente da altro CRM
• Registrazione cambiamenti di stato tramite /mark per analisi
• Creazione fattura con comando /invoice con ritorno link
• Ottenimento dati cliente dal database tramite /user
• Automazione processi aziendali per trigger comando

Esempio Richiesta: Comando /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"
}

Formato Risposta¶

Il tuo server può restituire il risultato come testo semplice o JSON con nodi message o error.

Esecuzione riuscita:

{
  "message": "Trattativa creata: http://internal.domain.com/crm/deals/76238",
  "status": "ok"
}

Errore di esecuzione:

{
  "error": "Utente 12345678 non trovato nel nostro database"
}

Risposta testuale:

Puoi restituire solo testo con supporto Markdown v2:

✅ Fattura №12345 creata
Totale: 1500
Link: https://intranet.example.com/invoice/12345

Sicurezza¶

Tutte le richieste da Hotline contengono il campo api_key della connessione corrispondente per la verifica del mittente.

• Verifica api_key dal tuo lato
• Configura filtraggio per IP del server proxy Hotline
• Usa HTTPS per l'URL dei Webhooks

Scenari Pratici¶

Suggerimenti per il Debug¶

1. Usa servizi per testare Webhooks: postman.com, requestbin.com
2. Registra tutte le richieste in arrivo sul tuo server
3. Restituisci stato di risposta HTTP corretto (dovrebbe essere 200 OK)
4. Monitora il timeout — la risposta dovrebbe arrivare rapidamente (consigliato fino a 3 secondi)
5. Gestisci gli errori con grazia e restituisci messaggi comprensibili

Limitazioni¶

• Timeout risposta comando — consigliato non più di 3 secondi
• Dimensione risposta — fino a 4096 caratteri (limitazione Telegram)
• Tentativi di ripetizione — se il tuo server non è disponibile, la richiesta può essere ripetuta
• Limiti di frequenza — con grande flusso di eventi considera le capacità del tuo server

Supporto¶

Per domande sulla configurazione webhook, connessione abbonamento a pagamento, contattare il servizio di supporto @hotlinetg_support