Vai al contenuto principale
Flowella si collega a Customer.io tramite le azioni webhook di Customer.io e la Flowella REST API. Una campagna Customer.io chiama Flowella per inviare un template WhatsApp approvato, compresi i template con un pulsante WhatsApp Flow, a ogni persona che raggiunge quel passaggio. Se volete anche le risposte WhatsApp in Customer.io, Flowella può inviare ogni messaggio in arrivo a un’automazione di Customer.io attivata da webhook che controllate voi.
Non c’è nessuna app da installare in Customer.io. Create entrambe le direzioni con le azioni standard di Customer.io, quindi decidete esattamente quali richieste vengono eseguite e quali attributi cambiano.

Come funziona l’integrazione

Flowella non chiama mai la Customer.io API. Nella direzione in entrata facoltativa, Flowella pubblica gli eventi solo sull’URL webhook che le fornite, e la vostra automazione decide cosa farne.

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

1

Create una chiave API Flowella

In Flowella, andate su Settings, poi API keys, e create una chiave live con un nome come Customer.io production. Copiatela subito: Flowella la mostra una sola volta. Consultate Chiavi API.
2

Trovate gli ID del template e del canale

Chiamate 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.
3

Aggiungete un'azione webhook alla campagna

Nel workflow della vostra campagna Customer.io, aggiungete un’azione Send and receive data nel punto in cui deve partire il messaggio WhatsApp. Consultate la guida di Customer.io alle azioni webhook.
4

Impostate la richiesta

Impostate il metodo su POST e l’URL su https://api.flowella.io/v1/templates/send. Aggiungete queste intestazioni:
5

Scrivete il corpo della richiesta

Incollate questo corpo e sostituite gli ID con i vostri. Cambiate 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.
6

Testate l'azione

Scegliete una persona di test con il vostro numero WhatsApp e selezionate Test response in Customer.io. Aggiungete un’intestazione 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.
7

Rimuovete l'intestazione di test e avviate la campagna

Eliminate l’intestazione 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. Per un template con un’intestazione immagine, video o documento, potete impostare un link pubblico al file in 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’id originale 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’id originale e non invia nulla, anche se il corpo è cambiato.
  • Inoltre, Flowella salta un secondo invio dello stesso template allo stesso numero entro 15 secondi.
Non lasciate mai un valore fisso di Idempotency-Key sull’azione di una campagna attiva. Solo la prima persona riceve il messaggio: ogni richiesta successiva riusa la chiave, quindi Flowella restituisce il primo id e non invia nulla. Rimuovete l’intestazione prima di avviare la campagna, oppure create un valore diverso per ogni persona, ad esempio il nome della campagna seguito da {{customer.id}}.
Le stesse regole spiegano la maggior parte dei test non riusciti. Inviare di nuovo lo stesso template alla stessa persona di test produce lo stesso corpo, quindi Flowella non invia nulla a meno che non cambiate ogni volta il valore di 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 429 con un’intestazione Retry-After. Consultate Limiti di frequenza.
Distribuite gli invii di grandi dimensioni con i controlli di invio di Customer.io e seguite l’avanzamento nella scheda Statistics del template. Flowella salta chiunque abbia effettuato l’opt-out sul numero da cui inviate. Consultate Opt-out.

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.
1

Create un'automazione attivata da webhook in Customer.io

Create una campagna o un’automazione attivata da webhook e copiate l’URL webhook generato da Customer.io. Consultate la guida di Customer.io alle campagne webhook.
2

Aggiungete un webhook in uscita in Flowella

In Flowella, andate su Settings, poi Webhooks, e selezionate Add webhook. Incollate l’URL di Customer.io in Endpoint URL, inserite un secret di firma e spuntate solo message.received in Events. Consultate Webhook.
3

Inviate dati di esempio

Inviatevi un template WhatsApp da Flowella e rispondete, così Customer.io riceve un vero evento message.received su cui costruire il workflow. Ogni evento ha questo aspetto:
Send test event in Flowella invia un evento webhook.test, che non ha alcun contatto, quindi filtratelo nel passaggio successivo.
4

Mantenete solo i messaggi in arrivo reali

Aggiungete un True/False Branch che prosegue solo quando il type del trigger è message.received.
5

Cercate il contatto in Flowella

L’evento contiene ID, non il numero di telefono. Aggiungete un’azione Send and receive data con il metodo 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.
6

Aggiornate la persona

Aggiungete un’azione Create or Update Person. Scegliete l’identificatore che il vostro workspace usa per le persone e impostate solo gli attributi che vi servono, come l’orario dell’ultima risposta WhatsApp. Consultate la guida di Customer.io a Create or update person.
In un’automazione attivata da webhook, Create or Update Person crea una nuova persona quando nessuno corrisponde all’identificatore. Per evitare di creare persone indesiderate, aggiungete una condizione all’azione in modo che il passaggio venga eseguito solo quando il valore dell’identificatore è presente, e fate i test con un numero che non è nel vostro workspace.

Sicurezza del webhook in entrata

Flowella firma ogni richiesta con l’intestazione X-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 invia STOP 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.

Risoluzione dei problemi

Introduzione all'API

Autenticazione, idempotenza, limiti di frequenza ed errori.

Riferimento dei webhook

Tipi di evento, corpi delle richieste e firme.

Variabili dei template

Variabili, esempi e valori di riserva.

Bulk send

Inviate invece un template a un elenco dall’app Flowella.
Ultima modifica il 21 novembre 2026