Skip to main content

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.
Sulla riga dell’indirizzo ci sono anche:
  • 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.
Ogni indirizzo aggiunto resta nel Log attività dell’account, e di norma il titolare riceve un’email di avviso: chi riceve gli avvisi legge i messaggi dei tuoi clienti.

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 ha version (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 un message.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.
Per riconoscerci usa la firma, non l’indirizzo IP di provenienza: gli IP dei nostri server possono cambiare senza preavviso.

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.
Così un gestionale fermo per qualche ora riceve, quando torna, gli avvisi del periodo in cui era giù. Restano esclusi quelli che hanno finito i sei tentativi.

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-Delivery e scarta quelli già visti. Per i messaggi va bene anche message.id, insieme a event e, per gli stati, a message.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.