Come funziona l’integrazione
Prima di iniziare
- Un’organizzazione Flowella con un numero WhatsApp collegato. Consultate Sequenza di configurazione.
- Un template WhatsApp approvato in Flowella. Consultate Template.
- Il ruolo Owner o Admin in Flowella, per creare una chiave API e, per la sincronizzazione in entrata, un webhook. Consultate Team e ruoli.
- Un workspace Customer.io in cui potete creare campagne o automazioni con azioni webhook.
- Il numero WhatsApp di ogni persona salvato nel suo profilo Customer.io in formato internazionale, ad esempio
+447700900123. Consultate Formato del numero di telefono. - Il consenso di ogni persona a ricevere messaggi WhatsApp da voi. Meta richiede l’opt-in prima di scrivere a chiunque. Consultate le indicazioni di Meta sull’opt-in.
Inviare un template WhatsApp da Customer.io
Create una chiave API Flowella
Customer.io production. Copiatela subito: Flowella la mostra una sola volta. Consultate Chiavi API.Trovate gli ID del template e del canale
GET /v1/templates?status=APPROVED con la vostra chiave. Annotate l’id e il wabaId del template e il whatsappChannelId del numero da cui volete inviare. Consultate Più canali se avete più numeri.Aggiungete un'azione webhook alla campagna
Impostate la richiesta
POST e l’URL su https://api.flowella.io/v1/templates/send. Aggiungete queste intestazioni:Scrivete il corpo della richiesta
customer.phone con l’attributo che contiene il numero WhatsApp della persona.bodyParameters compila le variabili del corpo del template nell’ordine: il primo valore va in {{1}}, il secondo in {{2}} e così via. Lasciatelo come elenco vuoto, [], se il template non ha variabili nel corpo.Testate l'azione
Idempotency-Key con un valore che non avete mai usato, come test-2026-11-11-01, e cambiatelo a ogni test. Consultate Invii ripetuti e idempotenza.Una risposta 202 con "status": "accepted" significa che Flowella ha messo in coda l’invio. Non conferma la consegna: controllate il risultato nella scheda Statistics del template in Flowella.Rimuovete l'intestazione di test e avviate la campagna
Idempotency-Key usata per i test, oppure sostituitela con un valore diverso per ogni persona. Poi avviate la campagna.Opzioni del template impostabili per persona
Il corpo della richiesta accetta questi campi per ogni destinatario. L’introduzione all’API e il documento OpenAPI descrivono la richiesta completa.headerMedia.url al livello principale del corpo.
Invii ripetuti e idempotenza
POST /v1/templates/send vi protegge dall’invio dello stesso messaggio due volte, il che è importante perché Customer.io ripete un’azione webhook quando non riceve una risposta 2xx:
- Senza un’intestazione
Idempotency-Key, Flowella usa un hash del corpo della richiesta come chiave. Un corpo identico byte per byte entro 7 giorni restituisce l’idoriginale e non invia nulla. Poiché il corpo di ogni persona contiene il suo numero, una normale campagna invia a ciascuno una sola volta. - Con un’intestazione
Idempotency-Key, qualsiasi richiesta con la stessa chiave entro 7 giorni restituisce l’idoriginale e non invia nulla, anche se il corpo è cambiato. - Inoltre, Flowella salta un secondo invio dello stesso template allo stesso numero entro 15 secondi.
Idempotency-Key.
Inviare a un segmento ampio
Ogni richiesta da Customer.io mette in coda un invio, e Flowella lo consegna in background, riprovando in caso di errori temporanei di WhatsApp. Alle campagne di grandi dimensioni si applicano due limiti:- Il limite di messaggistica di Meta. Meta limita il numero di persone a cui potete scrivere fuori dalla finestra di 24 ore in un periodo mobile di 24 ore. Consultate Limiti di messaggistica.
- Il limite di frequenza della vostra chiave API. Le richieste oltre il limite restituiscono
429con un’intestazioneRetry-After. Consultate Limiti di frequenza.
Sincronizzare i messaggi WhatsApp in arrivo con Customer.io (facoltativo)
Questa parte invia a Customer.io ogni messaggio WhatsApp che un contatto vi manda, così potete aggiornare la persona o avviare altre campagne a partire da esso.Create un'automazione attivata da webhook in Customer.io
Aggiungete un webhook in uscita in Flowella
message.received in Events. Consultate Webhook.Inviate dati di esempio
message.received su cui costruire il workflow. Ogni evento ha questo aspetto:webhook.test, che non ha alcun contatto, quindi filtratelo nel passaggio successivo.Mantenete solo i messaggi in arrivo reali
type del trigger è message.received.Cercate il contatto in Flowella
GET, l’URL https://api.flowella.io/v1/contacts/{{trigger.data.contactId}} e la stessa intestazione Authorization di prima. La risposta contiene id, phone, waId, name, email, externalId, isOptedOut, createdAt e updatedAt del contatto.Per salvare il messaggio stesso, aggiungete un’altra richiesta a GET /v1/messages/{{trigger.data.messageId}}. Il suo campo body contiene il testo del messaggio e può essere vuoto.Aggiornate la persona
Sicurezza del webhook in entrata
Flowella firma ogni richiesta con l’intestazioneX-Flowella-Signature. Un’automazione di Customer.io attivata da webhook non può verificare quella firma, quindi chiunque abbia l’URL webhook di Customer.io può inviarvi dati. Mantenete l’URL privato e non usate la sincronizzazione in entrata per modificare attributi relativi al consenso o alla fatturazione. Consultate Verificare le firme se prima fate passare gli eventi da un vostro endpoint.
Opt-out
Quando un contatto inviaSTOP o un’altra parola chiave di opt-out, Flowella registra l’opt-out su quel numero WhatsApp e blocca da quel numero ogni invio successivo al contatto, compresi gli invii da Customer.io. Consultate Opt-out.
Per copiare gli opt-out in Customer.io, non affidatevi all’evento optout.created: al momento non si attiva per il primo opt-out di un contatto su un numero. Elencate invece gli opt-out con GET /v1/opt-outs, che accetta i filtri createdAfter e phone.

