API esterne e webhook

Richiede il permesso "Impostazioni".

La pagina API esterne (menu CONFIGURAZIONE) serve a collegare Thelgo ad altri sistemi, ad esempio il tuo CRM o un modulo di contatto sul sito. Ha due schede:

• Chiavi API: le chiavi con cui un sistema esterno può leggere e scrivere dati in Thelgo (nominativi, campagne, esiti);
• Webhook: gli indirizzi a cui Thelgo invia una notifica quando succede qualcosa (un esito, un appuntamento, un nuovo nominativo).

Questa pagina è pensata anche per chi sviluppa l'integrazione: le sezioni tecniche sono indicate come tali.

Screenshot da inserire: amministratore-api-esterne-chiavi.png

Scheda Chiavi API con il riquadro del limite di richieste al secondo, la documentazione "Come usare le API pubbliche" chiusa, l'avviso verde con una chiave appena creata e il pulsante Copia, e due chiavi in elenco (una attiva, una "Revocata").

Chiavi API

Creare una chiave

1. Apri la scheda Chiavi API.
2. Nel campo Nome scrivi a cosa serve la chiave (es. "Integrazione CRM"): ti servirà per riconoscerla nell'elenco e nell'audit log.
3. Premi Crea chiave.
4. Compare l'avviso "Copia subito questa chiave: non sarà più mostrata." con la chiave completa: premi Copia e consegnala in modo sicuro a chi sviluppa l'integrazione.

La chiave si vede una sola volta

Thelgo conserva la chiave solo in forma cifrata: dopo aver lasciato o ricaricato la pagina non è più possibile rivederla. Se la perdi, crea una nuova chiave e revoca quella vecchia.

Crea una chiave diversa per ogni sistema esterno: potrai revocarne una senza fermare le altre, e nell'audit log vedrai quale sistema ha fatto cosa.

L'elenco delle chiavi

Per ogni chiave vedi il nome, le prime lettere della chiave (per riconoscerla), la data di creazione e l'ultimo utilizzo. Cliccando sul nome si apre l'elenco delle ultime 50 richieste ricevute con quella chiave (metodo, indirizzo, data e ora, codice di risposta: verde se riuscita, rosso se in errore). È il primo posto da guardare se un'integrazione "non funziona".

Revocare, riattivare ed eliminare

• L'interruttore a destra revoca la chiave (compare l'etichetta Revocata): da quel momento ogni richiesta con quella chiave viene rifiutata. Puoi riattivarla con lo stesso interruttore.
• Solo una chiave revocata mostra il pulsante Elimina, che la cancella definitivamente dopo una conferma.

Creazione, revoca, riattivazione ed eliminazione vengono registrate nell'Audit log.

Revoca subito una chiave compromessa

L'interruttore agisce immediatamente e senza conferma. Se una chiave è finita in mani sbagliate o il fornitore dell'integrazione è cambiato, revocala e creane una nuova.

Limite di richieste

In cima alla scheda trovi "Limite: … richieste al secondo": è il numero massimo di richieste al secondo che l'account può ricevere con le chiavi API, stabilito dal fornitore del servizio. Oltre il limite il sistema esterno riceve una risposta di errore 429 e deve riprovare poco dopo.

Cosa permettono le API pubbliche

Il riquadro Come usare le API pubbliche riassume gli endpoint; con Documentazione API (Swagger) si apre la documentazione completa e interattiva, da passare a chi sviluppa.

Con una chiave il sistema esterno può:

Area	Operazioni
Nominativi	Creare un nominativo e associarlo a una campagna; leggerlo; aggiornarne i dati anagrafici, i telefoni e i campi dinamici
Campagne	Elencare le campagne dell'account (sola lettura)
Esiti	Registrare l'esito di un contatto; leggere l'esito attuale e lo storico; modificare note e data di richiamo dell'ultimo esito; eliminare l'ultimo esito

Cose da sapere, anche per te come amministratore:

• Le operazioni fatte via API compaiono in Thelgo come eseguite dall'utente Sistema (API pubbliche), e nell'audit log riportano il nome della chiave usata.
• Un esito inserito via API segue le stesse regole dell'interfaccia operatore ("L'inserimento segue le stesse regole di validazione dell'interfaccia operatore (es. data richiamo obbligatoria per l'esito "Richiamare")."): conta per i richiami automatici, il blocco del Non autorizza e i report, esattamente come un esito dato da un operatore. Nelle campagne in cui il Positivo richiede un appuntamento obbligatorio, un Positivo via API viene rifiutato perché le API non fissano appuntamenti.
• "La modifica è limitata a note e data richiamo": per cambiare il risultato di un contatto il sistema esterno deve registrare un nuovo esito.
• Eliminare un esito via API riporta l'esito attuale del nominativo a quello precedente, ma non ricalcola i contatori dei tentativi né la data del prossimo richiamo.
• Un nominativo creato via API deve avere almeno un numero di telefono; i campi dinamici si indicano con il loro nome come definito nello schema del database (vedi Campi dinamici).

Dettagli tecnici per lo sviluppatore

Autenticazione: ogni richiesta deve contenere l'header

Authorization: Bearer thelgo_live_...

"Header su ogni richiesta. Nessun login, nessun cookie di sessione." Una chiave revocata o errata riceve 401.

URL di base: https://<dominio del tuo account>/api/public/v1 (l'indirizzo esatto è mostrato nella pagina).

Metodo	Percorso	Descrizione
POST	/nominativi	Crea un nominativo e lo associa a una campagna (campagnaId obbligatorio, fino a 9 telefoni, campiDinamici per nome)
GET	/nominativi/{id}	Legge un nominativo
PUT	/nominativi/{id}	Aggiorna i dati anagrafici di un nominativo
GET	/campagne	Elenca le campagne dell'account (id, nome, tipo, stato, date, numero di nominativi)
POST	/esiti	Registra l'esito di un contatto (nominativoId, campagnaId, esitoCodice, note, dataRichiamo, richiamataPubblica, dataOraChiamata opzionale)
GET	/esiti?nominativoId=&campagnaId=	Esito attuale e storico degli esiti precedenti di un nominativo in una campagna
PUT	/esiti	Aggiorna note/data richiamo dell'esito più recente (nominativoId, campagnaId, note, dataRichiamo)
DELETE	/esiti?nominativoId=&campagnaId=	Elimina l'esito più recente di un nominativo in una campagna

Codici esito accettati in esitoCodice:

Codice	Esito
POSITIVO	Positivo
NEGATIVO	Negativo
OCCUPATO_NON_RISPONDE	Occupato / Non risponde
RICHIAMARE	Richiamare (richiede dataRichiamo)
NON_AUTORIZZA	Non autorizza
DINAMICO_1, DINAMICO_2	Esiti personalizzati, se attivi (vedi Impostazioni generali)

Idempotenza: "Sulle creazioni (POST) puoi inviare l'header "Idempotency-Key" con un valore univoco: se la stessa richiesta viene reinviata con la stessa chiave (es. dopo un timeout), ricevi la risposta già prodotta invece di un doppione." La risposta viene ricordata per 24 ore e solo se la richiesta originale è andata a buon fine.

Errori: 400 con un campo message che spiega il problema (validazione), 404 se nominativo o campagna non esistono, 429 oltre il limite di richieste.

Webhook

Un webhook è un indirizzo web del tuo sistema esterno a cui Thelgo invia automaticamente una notifica quando accade un evento. Così il CRM, ad esempio, viene aggiornato in tempo reale senza dover interrogare Thelgo di continuo.

Screenshot da inserire: amministratore-api-esterne-webhook.png

Scheda Webhook con il modulo di creazione (URL di destinazione e i tre eventi), l'avviso con il secret appena generato e un webhook in elenco espanso sulle ultime consegne, alcune "Consegnato" e una "Fallito".

Eventi disponibili

Evento	Codice	Quando parte
Esito assegnato a un nominativo	esito.assegnato	Quando un operatore (anche in una campagna Predictive) o una chiamata API registra un esito, compresi gli esiti del Quality Check
Nuovo appuntamento fissato	appuntamento.fissato	Quando viene fissato un nuovo appuntamento
Nuovo nominativo creato	nominativo.creato	Quando viene creato un nuovo nominativo e associato a una o più campagne (inserimento manuale da amministratore o operatore, oppure via API)

Importazioni

I nominativi caricati con un'importazione non generano l'evento nominativo.creato.

Creare un webhook

1. Apri la scheda Webhook.
2. In URL di destinazione scrivi l'indirizzo fornito da chi sviluppa l'integrazione (deve iniziare con https:// o http://; usa sempre https://).
3. In Eventi spunta almeno un evento.
4. Premi Crea webhook.
5. Compare "Copia subito questo secret: non sarà più mostrato. Usalo per verificare la firma delle richieste in arrivo.": premi Copia e consegnalo allo sviluppatore insieme all'URL.

Per ricevere eventi diversi su indirizzi diversi, crea più webhook.

Controllare le consegne

Clicca sull'URL di un webhook per vedere le ultime 50 consegne: evento, data e ora, Consegnato oppure Fallito con il numero di tentativi e l'ultimo errore (es. "HTTP 500"). Se un sistema esterno dice di non ricevere nulla, guarda qui.

Revocare ed eliminare

Funziona come per le chiavi: l'interruttore revoca (o riattiva) il webhook; un webhook revocato mostra Elimina per cancellarlo definitivamente. Mentre è revocato Thelgo non invia più nulla, nemmeno i tentativi ancora in sospeso.

Dettagli tecnici per lo sviluppatore

Il pulsante Documentazione webhook apre una pagina dedicata, con un esempio di contenuto per ogni evento, che puoi condividere con chi sviluppa.

Formato: ogni evento arriva come richiesta POST all'URL configurato, con corpo JSON e questi header:

POST <url configurato>
Content-Type: application/json
X-Thelgo-Event: esito.assegnato
X-Thelgo-Signature: a3f1c9...

Verifica della firma: calcola l'HMAC-SHA256 del corpo della richiesta (la stringa grezza ricevuta, non riserializzata) usando il secret mostrato alla creazione, e confronta il risultato, in esadecimale minuscolo, con l'header X-Thelgo-Signature. Se non corrispondono, scarta la richiesta: non proviene da Thelgo.

Conferma e nuovi tentativi: il sistema esterno deve rispondere con un codice 2xx entro 15 secondi. In caso di errore o timeout Thelgo ritenta automaticamente fino a 8 volte, con un intervallo crescente tra un tentativo e l'altro.

Contenuto degli eventi (date in UTC):

esito.assegnato

{
  "nominativoId": 1234,
  "campagnaId": 56,
  "livello": "PrimoLivello",
  "esitoCodice": "RICHIAMARE",
  "note": "Richiamare dopo le 15",
  "dataRichiamo": "2026-10-14T13:00:00Z",
  "dataOraChiamata": "2026-10-13T09:12:30Z"
}

livello vale PrimoLivello per gli esiti normali e QualityCheck per quelli del Quality Check (codici QC_CONFERMATO, QC_ANNULLATO, QC_RICHIAMARE, QC_OCCUPATO_NON_RISPONDE).

appuntamento.fissato

{
  "appuntamentoId": 789,
  "nominativoId": 1234,
  "campagnaId": 56,
  "agenteId": 12,
  "dataOraAppuntamentoInizio": "2026-10-20T10:00:00Z",
  "dataOraAppuntamentoFine": "2026-10-20T10:30:00Z"
}

nominativo.creato

{
  "nominativoId": 1234,
  "campagnaIds": [56]
}