Integrare il centralino con il CRM tramite webhook e API
Integrare il centralino con il CRM significa far parlare il telefono con il tuo gestionale: le chiamate aprono la scheda del cliente, gli esiti finiscono nello storico, i lead arrivano nelle campagne. In questa guida vedi come funzionano webhook e API, quali eventi scegliere, come proteggere i dati e come costruire un ricevitore che non perde nulla.
Perché integrare il centralino con il CRM
Un centralino che non comunica con il CRM costringe gli operatori a fare due lavori: parlare con il cliente e poi copiare a mano numero, motivo della chiamata ed esito nel gestionale. È lento, si sbaglia facilmente e i dati arrivano in ritardo o non arrivano affatto. Integrare il centralino con il CRM toglie questo passaggio: ciò che succede al telefono viene registrato da solo, nel momento in cui succede.
I vantaggi pratici sono concreti. L'operatore vede chi sta chiamando prima di rispondere. I responsabili trovano nel CRM lo storico completo dei contatti con ogni cliente, telefonate comprese. Le chiamate perse diventano attività di richiamata invece di numeri dimenticati in un registro. E i lead raccolti dal sito o dalle fiere entrano nelle campagne di chiamata senza esportare e importare file.
Gli strumenti per farlo sono due, e lavorano in direzioni opposte: i webhook portano gli eventi dal centralino al CRM, le API permettono al CRM di chiedere dati al centralino o di dargli ordini. Quasi tutte le integrazioni serie usano entrambi.
- Apertura automatica della scheda cliente quando squilla il telefono.
- Registrazione di chiamate, durate ed esiti nello storico del contatto.
- Creazione di attività per le chiamate perse o abbandonate in coda.
- Caricamento dei lead nelle liste delle campagne.
- Pulsante di chiamata (click-to-call) dentro il gestionale.
Webhook e API: le differenze in breve
Un webhook è una richiesta HTTP che il centralino invia a un indirizzo tuo quando succede un evento: entra una chiamata, un operatore risponde, viene salvato un esito. Il tuo sistema non deve chiedere nulla, riceve la notizia appena c'è. Per questo si parla di modello push.
Un'API è il contrario: è il tuo programma che chiama il centralino, quando vuole, per leggere o modificare qualcosa. Per esempio per aggiungere un lead a una lista, cercare un contatto in rubrica o far partire una chiamata. È il modello pull, o meglio richiesta e risposta.
Un errore comune è usare solo le API per sapere cosa succede, interrogando il centralino ogni pochi secondi (polling). Funziona, ma consuma risorse, si scontra con i limiti di richieste e comunque arriva in ritardo. Per gli eventi in tempo reale il webhook è lo strumento giusto; l'API serve per le azioni e per recuperare dati quando ti servono.
| Webhook | API | |
|---|---|---|
| Chi inizia | Il centralino | Il tuo sistema |
| Quando | Appena succede un evento | Quando lo decidi tu |
| Usi tipici | Notifiche di chiamate, code, esiti, presenze | Caricare lead, aggiornare la rubrica, click-to-call, leggere lo storico |
| Cosa serve dal tuo lato | Un indirizzo HTTPS pubblico che risponde | Una chiave API e un programma che fa le richieste |
| Rischio principale | Ricevitore lento o irraggiungibile | Superare i limiti di richieste |
Quali eventi del centralino inviare al CRM
Il primo istinto è attivare tutti gli eventi. Meglio di no: ogni evento in più è traffico da gestire e logica da scrivere. Parti dalle domande a cui il CRM deve rispondere e scegli solo gli eventi che servono.
Gli eventi di un centralino cloud si dividono di solito in famiglie: chiamate (in arrivo, chiusa, persa), code (entrata, risposta, abbandono, tempo scaduto, coda piena), operatori (login, pausa, squillo, risposta, chiamata in uscita, trasferimento, esito), menu IVR (entrata, tasto premuto, nessuna scelta), feedback e richieste di richiamata. Nei webhook e API di Robottino sono 27, divisi in sette gruppi, e puoi limitarli a certe code, operatori, numerazioni o menu IVR.
| Obiettivo nel CRM | Evento da usare | Dati utili |
|---|---|---|
| Aprire la scheda prima della risposta | Squilla una chiamata all'operatore | Numero chiamante, coda, interno dell'operatore |
| Storico delle telefonate | Chiamata chiusa | Durata, attesa, esito tecnico |
| Attività di richiamata | Chiamata persa, abbandonata in coda | Numero, coda, tempo di attesa |
| Esiti commerciali | Esito salvato o conversione | Nome dell'esito, nota, data di richiamo |
| Presenze degli operatori | Login, logout, pausa, disponibile | Operatore, durata della pausa |
| Analisi del menu vocale | Tasto premuto, nessuna scelta | Menu, tasto, destinazione |
Il contenuto del webhook: evento completo o campi personalizzati
Ogni webhook porta un corpo, quasi sempre in JSON. Ci sono due approcci. Il primo è ricevere l'evento completo: un identificativo, il tipo di evento, la data e un blocco di dati con gli oggetti coinvolti, per esempio la chiamata, il contatto, la coda e l'operatore. È la scelta giusta se scrivi tu il ricevitore, perché hai tutto e decidi in codice cosa usare.
Il secondo è comporre campi personalizzati: decidi tu i nomi dei campi e i valori, usando variabili come {{call.from}}, {{queue.name}}, {{operator.extension}} o {{outcome.name}}. È utile quando il sistema che riceve si aspetta un formato preciso, come l'endpoint di un CRM che vuole "phone" e "agent" e non accetta altro, oppure uno strumento di automazione in cui vuoi campi già puliti.
Un dettaglio che conta: quando un campo contiene solo una variabile, conviene che mantenga il suo tipo. Un numero deve arrivare come numero, un vero o falso come booleano, un dato mancante come null, non come testo vuoto. Così il CRM non deve convertire nulla e i filtri funzionano.
- Usa nomi di campo stabili: se li cambi, rompi l'integrazione dall'altra parte.
- Invia il numero di telefono in formato internazionale (per esempio +39...), così il CRM lo confronta con i contatti senza ambiguità.
- Includi sempre un identificativo dell'evento e uno della chiamata: servono per i duplicati e per collegare più eventi della stessa telefonata.
- Per collegare l'operatore all'utente del CRM, salva l'ID del CRM come campo personalizzato dell'operatore e invialo nel webhook.
Sicurezza dei webhook: HTTPS, firma e header segreti
L'indirizzo che riceve i webhook è pubblico per definizione: chiunque lo scopra può inviarci richieste. Per questo un ricevitore serio verifica sempre che la richiesta arrivi davvero dal centralino e che non sia stata modificata o ripetuta.
La base è HTTPS: senza cifratura, numeri di telefono e nomi viaggiano in chiaro. Il passo successivo è la firma. Il centralino calcola un HMAC-SHA256 del corpo della richiesta con un segreto che conosci solo tu, e lo mette in un header. Il tuo sistema ricalcola la firma con lo stesso segreto e la confronta: se non coincide, scarta la richiesta. In Robottino l'header si chiama Robottino-Signature e contiene t=timestamp e v1=firma, calcolata sul testo formato da timestamp, un punto e il corpo.
Il timestamp dentro la firma serve contro gli attacchi di replay, cioè qualcuno che intercetta una richiesta valida e la reinvia più tardi. Il ricevitore controlla che il timestamp sia recente, per esempio entro cinque minuti dall'ora del server, e rifiuta le richieste più vecchie. La tolleranza la scegli tu: abbastanza larga per piccoli scarti di orologio, abbastanza stretta da rendere inutile una richiesta copiata.
Leggi il corpo grezzo
Calcola la firma sul corpo esattamente come è arrivato, prima di decodificare il JSON: anche uno spazio diverso cambia il risultato.
Separa timestamp e firma
Dall'header prendi il valore dopo t= e quello dopo v1=.
Ricalcola l'HMAC
Con il segreto di firma calcola HMAC-SHA256 di timestamp, punto e corpo, in esadecimale.
Confronta in tempo costante
Usa la funzione di confronto sicuro del tuo linguaggio, non un semplice uguale, per non dare indizi a chi prova firme a caso.
Controlla il timestamp
Rifiuta le richieste fuori dalla tolleranza scelta.
Tentativi, duplicati e risposte veloci
Prima o poi il tuo server sarà irraggiungibile: un aggiornamento, un certificato scaduto, un picco di traffico. Un buon centralino non butta l'evento, lo ritenta. In Robottino, se il tuo sistema non risponde con un codice 2xx entro 10 secondi, l'invio viene ripetuto dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore. Se per più di tre giorni non riesce nessun invio, il webhook va in pausa e ricevi un'email.
La conseguenza è che il tuo ricevitore deve essere idempotente: ricevere due volte lo stesso evento non deve creare due attività o due righe di storico. Il modo semplice è usare l'identificativo dell'evento. Il centralino lo invia nel corpo e nell'header Robottino-Event-Id, e resta lo stesso nei nuovi tentativi e quando reinvii a mano un evento dal registro delle consegne. Il ricevitore salva gli ID già elaborati e, se ne arriva uno noto, risponde 200 senza fare altro.
L'altra regola è rispondere in fretta. Dieci secondi sembrano tanti, ma se dentro la richiesta chiami il CRM, aspetti un'altra API e scrivi su un database lento, ci arrivi presto. Lo schema robusto è: verifica la firma, salva l'evento in una coda o in una tabella, rispondi 200, e elabora dopo con un processo separato. Così un rallentamento del CRM non fa fallire le consegne.
- Rispondi 2xx solo quando l'evento è salvato in modo sicuro, non prima.
- Rispondi 4xx o 5xx se qualcosa è andato storto: l'invio verrà ritentato.
- Non contare sull'ordine di arrivo: con i tentativi, un evento può arrivare dopo uno successivo. Usa la data dell'evento per ordinarli.
- Tieni d'occhio il registro delle consegne nei primi giorni: richiesta e risposta di ogni tentativo mostrano subito dove sta il problema.
Le API del centralino: lead, rubrica e click-to-call
Nella direzione opposta, il CRM usa le API per far fare cose al centralino. L'autenticazione avviene con una chiave API, inviata nell'header Authorization come Bearer. Crea una chiave diversa per ogni programma che si collega: se una viene compromessa la revochi senza fermare le altre, e vedi quando ognuna è stata usata l'ultima volta.
Gli usi più frequenti sono tre. Il primo è caricare lead: il modulo del sito o il CRM aggiunge il contatto a una lista, e le campagne di chiamata lo lavorano subito. Il secondo è tenere allineata la rubrica: quando un cliente cambia numero nel CRM, lo aggiorni anche nel centralino, così chi chiama viene riconosciuto. Il terzo è il click-to-call: un pulsante Chiama nel gestionale fa squillare prima il telefono dell'operatore e, quando risponde, parte la chiamata verso il cliente.
Le API hanno limiti di richieste, per esempio 600 al minuto per ogni chiave, con elenchi a pagine fino a 1000 elementi. Per sincronizzazioni grandi, distribuisci le richieste nel tempo e gestisci le risposte di limite superato aspettando prima di riprovare, invece di ripetere subito.
Come impostare un'integrazione passo per passo
Che tu scriva il ricevitore o usi uno strumento di automazione come Zapier, Make o n8n, la sequenza è la stessa. Gli strumenti di automazione ti danno un indirizzo pronto (per esempio il Catch Hook di Zapier) e sono comodi per partire; un ricevitore tuo diventa preferibile quando i volumi crescono o la logica si complica.
Definisci gli obiettivi
Scrivi cosa deve succedere nel CRM e per quali eventi: per esempio, attività per ogni chiamata persa della coda assistenza.
Prepara il ricevitore
Un indirizzo HTTPS che verifica la firma, salva l'evento e risponde 200 in pochi istanti.
Crea il webhook
Inserisci URL, metodo ed eventuali header, scegli gli eventi e i filtri per code, operatori o numerazioni.
Scegli il contenuto
Evento completo se il ricevitore è tuo, campi personalizzati se il destinatario vuole un formato preciso.
Prova con dati di esempio
Invia una richiesta di prova e controlla la risposta del tuo sistema prima di attivare.
Attiva e controlla le consegne
Nei primi giorni guarda il registro: errori, tempi di risposta, tentativi.
Errori da evitare nell'integrazione centralino CRM
Molti problemi si ripetono da un'integrazione all'altra. Conoscerli prima ti fa risparmiare giorni di indagini.
- Fare tutto il lavoro dentro la richiesta del webhook, superando il tempo limite e generando tentativi a catena.
- Non gestire i duplicati, con attività o note doppie nel CRM.
- Saltare la verifica della firma "perché tanto l'URL non lo conosce nessuno".
- Rispondere 200 anche quando l'elaborazione è fallita: il centralino considera l'evento consegnato e non lo ritenta.
- Confrontare i numeri di telefono in formati diversi, così il cliente non viene trovato.
- Usare una sola chiave API condivisa tra più programmi.
- Non avere un responsabile per le email di errore e accorgersi dopo settimane che il webhook è in pausa.
Domande frequenti
Come si collega un centralino VoIP a un CRM?
Di solito con due strumenti: i webhook, con cui il centralino avvisa il CRM degli eventi come chiamate ed esiti, e le API, con cui il CRM carica lead, aggiorna la rubrica o fa partire chiamate. Alcuni CRM hanno connettori pronti; negli altri casi basta un piccolo ricevitore o uno strumento di automazione.
Che differenza c'è tra webhook e API?
Il webhook è il centralino che invia dati al tuo sistema quando succede qualcosa. L'API è il tuo sistema che chiede dati o dà ordini al centralino quando vuole. Per le notifiche in tempo reale usa i webhook, per le azioni usa le API.
Come verifico che un webhook sia autentico?
Ricalcola la firma HMAC-SHA256 del corpo con il segreto condiviso e confrontala con quella nell'header, poi controlla che il timestamp sia recente. Se la firma non coincide o la richiesta è troppo vecchia, scartala.
Cosa succede se il mio server è offline quando arriva un evento?
Il centralino ritenta l'invio a intervalli crescenti, per esempio dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore, e di solito dal registro delle consegne puoi reinviare un evento a mano. Per questo il ricevitore deve ignorare gli eventi già elaborati.
Posso integrare il centralino con Zapier, Make o n8n?
Sì. Crei un webhook verso l'indirizzo che ti dà lo strumento di automazione e scegli gli eventi. Con i campi personalizzati invii solo i dati che servono, già con i nomi giusti per i passaggi successivi.
Cos'è il click-to-call?
È un pulsante nel CRM o nel gestionale che avvia una chiamata tramite l'API del centralino. Squilla prima il telefono dell'operatore e, quando risponde, parte la chiamata verso il cliente, senza digitare il numero.