Webhook WhatsApp
Con i webhook è MyFlow ad avvisare il gestionale, senza che il gestionale debba chiedere. Quando un cliente scrive su WhatsApp, il nostro server manda subito un POST JSON firmato all’indirizzo del tuo gestionale, con il messaggio e chi l’ha scritto. Se vuoi, lo stesso succede per i messaggi inviati, per gli stati di consegna e per l’esito della revisione dei template. Gli avvisi si configurano dal pannello, non dall’API.Prima di cominciare
- Serve MyFlow attivo sull’account, come per tutte le rotte
/v1/whatsapp. - Gli indirizzi li aggiunge e li gestisce un amministratore di MyFlow.
- Si possono avere al massimo 2 indirizzi per account, per esempio il gestionale e un ambiente di prova.
- Il server che riceve deve essere raggiungibile da Internet in https: le regole sono in fondo a questa pagina.
Configurazione dal pannello
Dove si trova: MyFlow → Impostazioni → zona Collegamento col gestionale → card Avvisi al gestionale ·https://cloud.mycentralino.com/myflow/impostazioni
1
Premi Aggiungi indirizzo
Si apre la finestra Nuovo indirizzo del gestionale.
2
Scrivi l'indirizzo
In Indirizzo (https) metti l’URL del tuo server che riceve gli avvisi, per esempio
https://gestionale.example.com/webhook/whatsapp.3
Scegli gli avvisi
In Avvisi da ricevere, Messaggi in arrivo c’è sempre. In più puoi spuntare Messaggi inviati, Stati di consegna ed Esito dei template. Con Escludi le campagne non ricevi gli avvisi dei messaggi delle Campagne e dei loro stati: con molti destinatari sarebbero migliaia. Le risposte dei clienti alle campagne arrivano comunque.
4
Premi Aggiungi e copia il segreto
Compare il riquadro Il segreto per la firma, che inizia con
whsec_. Premi Copia e mettilo nel gestionale: serve a verificare che gli avvisi arrivino da noi. Si vede una volta sola.5
Premi Prova
Parte subito un avviso di prova firmato (evento
message.test). Il pannello dice com’è andata: «Consegnato: il gestionale ha risposto 200.» oppure «Non consegnato: …» con il motivo.- Ultimi avvisi: gli ultimi 20 avvisi mandati, ognuno con stato (Consegnato, In attesa, In corso, Non consegnato), numero di tentativi, codice di risposta del tuo server, ora del prossimo tentativo ed errore;
- Modifica, per cambiare indirizzo e avvisi. Nella stessa finestra ci sono Rigenera segreto, che crea un segreto nuovo mentre quello vecchio smette subito di firmare, ed Elimina;
- l’interruttore per spegnere e riaccendere gli avvisi.
Eventi
Non generano avvisi lo storico importato quando il numero è stato collegato né i messaggi tecnici, come modifiche, revoche e avvisi di sistema.
Payload
Ogni avviso haversion (oggi 1), event e occurred_at, cioè quando l’avviso è stato preparato, in ISO 8601 con offset. Il resto dipende dall’evento. Ignora i campi che non conosci: potremmo aggiungerne.
message.received e message.sent
In
message.sent, direction è out e author dice chi l’ha mandato: operator, phone_app, ai, automation, campaign, pbx, crm o other. Anche i messaggi mandati dal tuo gestionale con l’API tornano come message.sent, con author crm: se non ti servono, scartali.
message.status
Arriva un avviso per ogni stato di ogni messaggio inviato, e lo stesso stato dello stesso messaggio arriva una volta sola.
template.status
message.test
L’avviso di prova ha la forma di unmessage.received, con dati finti e un campo note in più. Il numero in number.phone è il primo dei tuoi numeri.
Header e firma
La firma si calcola sul corpo esattamente come arriva, byte per byte, prima di decodificare il JSON. Un corpo ricodificato non dà la stessa firma. Il timestamp va controllato: rifiuta gli avvisi più vecchi di 5 minuti, così un avviso intercettato non si può rimandare più tardi.
Verifica della firma
Cosa deve rispondere il gestionale
- Un codice 2xx entro 8 secondi. Il corpo della risposta non conta. La connessione deve aprirsi entro 3 secondi.
- Rispondi prima di elaborare. Salva l’avviso, rispondi 200, poi fai il lavoro lungo: aggiornare il CRM, chiamare altri servizi.
- Qualunque altra risposta è un errore e l’avviso si ritenta. Valgono come errore i codici 3xx (i redirect non si seguono), 4xx e 5xx, il timeout e la connessione rifiutata.
Ritentativi
Un avviso non consegnato si ritenta dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore: sei tentativi in tutto, in circa otto ore e mezza. Dopo l’ultimo l’avviso è Non consegnato e non riparte più. L’avviso di prova non si ritenta.La pausa
Dopo 5 tentativi falliti di fila, anche di avvisi diversi, l’indirizzo va in pausa. Nel pannello compare «In pausa: il tuo gestionale non risponde. Riproviamo ogni 5 minuti; «Prova» per controllare subito». In pausa:- gli avvisi nuovi non si perdono, restano In attesa;
- si prova una consegna alla volta, la più vecchia in attesa, mentre le altre aspettano senza consumare tentativi;
- alla prima consegna riuscita, anche quella di Prova, la pausa finisce e gli avvisi in attesa ripartono.
Spento e disattivato
- Con l’interruttore spento gli avvisi non partono e quelli in attesa si fermano. Gli eventi del periodo spento non vengono recuperati quando lo riaccendi: per ricostruirli usa lo storico.
- Se MyFlow non è più attivo non parte più nessun avviso, nemmeno quelli già in attesa.
Ordine, doppioni e ritardi
- L’ordine non è garantito. Gli avvisi partono in parallelo e un ritentativo può arrivare dopo avvisi più recenti. Per ordinarli usa
message.timestamp. - Possono arrivare doppioni. Lo stesso evento non genera due avvisi per lo stesso indirizzo. Se però il tuo server elabora l’avviso e risponde dopo gli 8 secondi, l’avviso risulta non consegnato e si ritenta. Tieni traccia di
X-MyCentralino-Deliverye scarta quelli già visti. Per i messaggi va bene anchemessage.id, insieme aevente, per gli stati, amessage.status. - Non è tempo reale al millisecondo. Gli avvisi dei messaggi partono di norma entro pochi secondi. Gli stati di consegna partono di proposito con circa mezzo minuto di ritardo, così arrivano dopo la risposta dell’invio che li riguarda.
- Se un avviso manca, lo storico di quel cliente ha tutti i messaggi.
Regole dell’indirizzo
L’indirizzo si controlla quando lo salvi e di nuovo a ogni consegna, sull’IP a cui risolve in quel momento.
I redirect non si seguono: l’indirizzo deve essere quello finale. Se un indirizzo diventa non ammesso dopo il salvataggio, per esempio perché il dominio ora punta a una rete privata, l’avviso è Non consegnato con il motivo.
