> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inviare template e Flows WhatsApp da Customer.io

> Inviate template e Flows WhatsApp approvati dalle campagne Customer.io con la Flowella API e, se volete, riportate in Customer.io i messaggi in arrivo.

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.

> [!NOTE]
>
> 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

| Direzione | Cosa viene eseguito | Cosa cambia |
| - | - | - |
| Da Customer.io a Flowella | Un'azione **Send and receive data** (webhook) nella vostra campagna chiama `POST /v1/templates/send` per la persona nella campagna. | Flowella mette in coda un messaggio template WhatsApp. Nulla viene scritto in Customer.io. |
| Da Flowella a Customer.io (facoltativo) | Un webhook in uscita di Flowella invia gli eventi `message.received` a un'automazione di Customer.io attivata da webhook. | Solo gli attributi della persona che mappate nella vostra azione **Create or Update Person**. |

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.

```mermaid theme={null}
flowchart LR
    A["Customer.io: la persona raggiunge l'azione webhook"] --> B["Flowella: POST /v1/templates/send"]
    B --> C["Meta: messaggio WhatsApp consegnato"]
    C --> D["Il contatto risponde su WhatsApp"]
    D --> E["Flowella: webhook message.received"]
    E --> F["Customer.io: automazione attivata da webhook"]
    F --> G["Customer.io: Create or Update Person"]
```

## Prima di iniziare

* Un'organizzazione Flowella con un numero WhatsApp collegato. Consultate [Sequenza di configurazione](https://knowledge.flowella.io/it/whatsapp/accounts/setup-sequence.md).
* Un template WhatsApp approvato in Flowella. Consultate [Template](https://knowledge.flowella.io/it/app/templates.md).
* Il ruolo **Owner** o **Admin** in Flowella, per creare una chiave API e, per la sincronizzazione in entrata, un webhook. Consultate [Team e ruoli](https://knowledge.flowella.io/it/settings/team.md).
* 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](https://knowledge.flowella.io/it/hubspot/phone-number-format.md).
* 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-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](https://knowledge.flowella.io/it/settings/api-keys.md).

**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](https://knowledge.flowella.io/it/essentials/multi-channel.md) se avete più numeri.

```bash theme={null}
curl "https://api.flowella.io/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"
```

**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](https://docs.customer.io/webhooks-action).

**4. Impostate la richiesta**

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

| Intestazione | Valore |
| - | - |
| `Authorization` | `Bearer ` seguito dalla vostra chiave API Flowella |
| `Content-Type` | `application/json` |

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

```json theme={null}
{
  "templateId": "1234567890123456",
  "templateWabaId": "102290129340398",
  "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "recipients": [
    {
      "phone": "{{customer.phone}}",
      "bodyParameters": ["{{customer.first_name}}"]
    }
  ]
}
```

`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](#repeat-sends-and-idempotency).

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](https://knowledge.flowella.io/it/api-reference/introduction.md) e il [documento OpenAPI](https://api.flowella.io/v1/openapi.json) descrivono la richiesta completa.

| Campo | A cosa serve |
| - | - |
| `phone` | Il numero WhatsApp della persona. Obbligatorio. |
| `bodyParameters` | I valori delle variabili del corpo, nell'ordine. Fino a 20. |
| `buttonParameters` | I valori per le variabili dei pulsanti URL (`subType` `url`), dei pulsanti Flow (`subType` `flow`) o dei pulsanti di copia del codice (`subType` `copy_code`). |

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.

> [!WARNING]
>
> 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](https://knowledge.flowella.io/it/whatsapp/limits/messaging-limits.md).
* **Il limite di frequenza della vostra chiave API.** Le richieste oltre il limite restituiscono `429` con un'intestazione `Retry-After`. Consultate [Limiti di frequenza](https://knowledge.flowella.io/it/api-reference/introduction.md#rate-limits).

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](https://knowledge.flowella.io/it/app/opt-outs.md).

## 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](https://docs.customer.io/journeys/webhook-triggered-campaigns/).

**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](https://knowledge.flowella.io/it/settings/webhooks.md).

**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:

```json theme={null}
{
  "id": "evt_3f2b8c1d9a7e4f60b5c2d8e1a4f7b9c3",
  "type": "message.received",
  "created_at": "2026-10-21T09:30:00.000Z",
  "payload_version": "1",
  "data": {
    "messageId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "conversationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "contactId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "INBOUND",
    "type": "TEXT",
    "metaMessageId": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY"
  }
}
```

**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](https://docs.customer.io/journeys/create-update-person/).

> [!WARNING]
>
> 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](https://knowledge.flowella.io/it/api-reference/webhooks.md#verify-signatures) 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](https://knowledge.flowella.io/it/app/opt-outs.md).

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

| Sintomo | Causa | Soluzione |
| - | - | - |
| `401` con `Invalid or expired API key` | La chiave è stata revocata o sostituita, oppure è stata incollata in modo errato. | Create una nuova chiave e aggiornate l'intestazione `Authorization`. Consultate [Chiavi API](https://knowledge.flowella.io/it/settings/api-keys.md). |
| **Could not load API keys** in Flowella | Solo Owner e Admin possono gestire le chiavi API. | Chiedete a un Owner o a un Admin di creare la chiave. |
| `401` con `Missing bearer token` | La richiesta è andata a `https://app.flowella.io/api/v1`, che reindirizza, e l'intestazione è stata persa. | Usate `https://api.flowella.io/v1`. |
| Un test restituisce `202` ma non arriva nulla | Il corpo o la `Idempotency-Key` corrispondeva a un invio precedente entro 7 giorni, oppure lo stesso template è andato allo stesso numero entro 15 secondi. | Usate un nuovo valore di `Idempotency-Key` per ogni test. |
| Solo la prima persona di una campagna ha ricevuto il messaggio | Sull'azione è rimasto un valore fisso di `Idempotency-Key`. | Rimuovete l'intestazione, oppure rendete il suo valore unico per ogni persona. |
| L'invio mostra un errore nella scheda **Statistics** | Meta non è riuscito a consegnare il messaggio, ad esempio perché il numero non è su WhatsApp. | Leggete il motivo nella colonna **Details**. Consultate [Codici di errore di Meta](https://knowledge.flowella.io/it/whatsapp/errors/error-codes.md). |
| **Invalid phone number.** nella scheda **Statistics** | L'attributo del telefono è vuoto o non è in formato internazionale. | Salvate i numeri con il prefisso internazionale, ad esempio `+447700900123`. |
| Customer.io non riceve eventi in entrata | Il webhook di Flowella non è attivo oppure `message.received` non è spuntato. | Controllate il **Delivery log** del webhook in Flowella. Consultate [Webhook](https://knowledge.flowella.io/it/settings/webhooks.md#delivery-log). |

## Correlati

> [card] [Introduzione all'API](https://knowledge.flowella.io/it/api-reference/introduction.md)
>
> Autenticazione, idempotenza, limiti di frequenza ed errori.

> [card] [Riferimento dei webhook](https://knowledge.flowella.io/it/api-reference/webhooks.md)
>
> Tipi di evento, corpi delle richieste e firme.

> [card] [Variabili dei template](https://knowledge.flowella.io/it/app/template-variables.md)
>
> Variabili, esempi e valori di riserva.

> [card] [Bulk send](https://knowledge.flowella.io/it/app/bulk-send.md)
>
> Inviate invece un template a un elenco dall'app Flowella.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.