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

# Envoyer modèles WhatsApp et Flows depuis Customer.io

> Envoyez des modèles WhatsApp approuvés et des Flows depuis vos campagnes Customer.io avec l'API Flowella, et synchronisez si besoin les messages entrants.

Flowella se connecte à Customer.io via les actions webhook de Customer.io et l'API REST de Flowella. Une campagne Customer.io appelle Flowella pour envoyer un modèle WhatsApp approuvé, y compris un modèle avec un bouton de WhatsApp Flow, à chaque personne qui atteint cette étape. Si vous voulez aussi les réponses WhatsApp dans Customer.io, Flowella peut envoyer chaque message entrant vers une automatisation Customer.io déclenchée par webhook, que vous contrôlez.

> [!NOTE]
>
> Il n'y a aucune application à installer dans Customer.io. Vous construisez les deux sens avec des actions Customer.io standard : vous décidez donc précisément quelles requêtes s'exécutent et quels attributs changent.

## Fonctionnement de l'intégration

| Sens | Ce qui s'exécute | Ce qui change |
| - | - | - |
| De Customer.io vers Flowella | Une action **Send and receive data** (webhook) de votre campagne appelle `POST /v1/templates/send` pour la personne concernée. | Flowella met en file un message de modèle WhatsApp. Rien n'est écrit dans Customer.io. |
| De Flowella vers Customer.io (facultatif) | Un webhook sortant Flowella envoie les événements `message.received` vers une automatisation Customer.io déclenchée par webhook. | Uniquement les attributs de personne que vous mappez dans votre propre action **Create or Update Person**. |

Flowella n'appelle jamais l'API Customer.io. Dans le sens entrant facultatif, Flowella se contente de publier des événements vers l'URL de webhook que vous lui donnez, et votre automatisation décide de ce qu'elle en fait.

```mermaid theme={null}
flowchart LR
    A["Customer.io : la personne atteint l'action webhook"] --> B["Flowella : POST /v1/templates/send"]
    B --> C["Meta : message WhatsApp livré"]
    C --> D["Le contact répond sur WhatsApp"]
    D --> E["Flowella : webhook message.received"]
    E --> F["Customer.io : automatisation déclenchée par webhook"]
    F --> G["Customer.io : Create or Update Person"]
```

## Avant de commencer

* Une organisation Flowella avec un numéro WhatsApp connecté. Voir [Étapes de configuration](https://knowledge.flowella.io/fr/whatsapp/accounts/setup-sequence.md).
* Un modèle WhatsApp approuvé dans Flowella. Voir [Modèles](https://knowledge.flowella.io/fr/app/templates.md).
* Le rôle **Owner** ou **Admin** dans Flowella, pour créer une clé API et, pour la synchronisation entrante, un webhook. Voir [Équipe et rôles](https://knowledge.flowella.io/fr/settings/team.md).
* Un espace de travail Customer.io dans lequel vous pouvez créer des campagnes ou des automatisations avec des actions webhook.
* Le numéro WhatsApp de chaque personne enregistré sur son profil Customer.io au format international, par exemple `+447700900123`. Voir [Format des numéros de téléphone](https://knowledge.flowella.io/fr/hubspot/phone-number-format.md).
* L'accord de chaque personne pour recevoir vos messages WhatsApp. Meta exige un opt-in avant tout message. Voir les [recommandations de Meta sur l'opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in).

## Envoyer un modèle WhatsApp depuis Customer.io

**1. Créez une clé API Flowella**

Dans Flowella, allez dans **Settings**, puis **API keys**, et créez une clé live avec un nom comme `Customer.io production`. Copiez-la immédiatement : Flowella ne l'affiche qu'une fois. Voir [Clés API](https://knowledge.flowella.io/fr/settings/api-keys.md).

**2. Trouvez les identifiants du modèle et du canal**

Appelez `GET /v1/templates?status=APPROVED` avec votre clé. Notez l'`id` et le `wabaId` du modèle, ainsi que le `whatsappChannelId` du numéro d'envoi. Voir [Multi-canal](https://knowledge.flowella.io/fr/essentials/multi-channel.md) si vous avez plusieurs numéros.

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

**3. Ajoutez une action webhook à votre campagne**

Dans le workflow de votre campagne Customer.io, ajoutez une action **Send and receive data** à l'endroit où le message WhatsApp doit partir. Voir le guide Customer.io sur les [actions webhook](https://docs.customer.io/webhooks-action).

**4. Paramétrez la requête**

Choisissez la méthode `POST` et l'URL `https://api.flowella.io/v1/templates/send`. Ajoutez ces en-têtes :

| En-tête | Valeur |
| - | - |
| `Authorization` | `Bearer ` suivi de votre clé API Flowella |
| `Content-Type` | `application/json` |

**5. Rédigez le corps de la requête**

Collez ce corps et remplacez les identifiants par les vôtres. Remplacez `customer.phone` par l'attribut qui contient le numéro WhatsApp de la personne.

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

`bodyParameters` remplit les variables du corps du modèle dans l'ordre : la première valeur va dans `{{1}}`, la deuxième dans `{{2}}`, et ainsi de suite. Laissez une liste vide, `[]`, si le modèle n'a pas de variable dans le corps.

**6. Testez l'action**

Choisissez une personne de test avec votre propre numéro WhatsApp et sélectionnez **Test response** dans Customer.io. Ajoutez un en-tête `Idempotency-Key` avec une valeur jamais utilisée, par exemple `test-2026-11-11-01`, et changez-la à chaque test. Voir [Envois répétés et idempotence](#repeat-sends-and-idempotency).

Une réponse `202` avec `"status": "accepted"` signifie que Flowella a mis l'envoi en file. Elle ne confirme pas la livraison : consultez l'onglet **Statistics** du modèle dans Flowella pour le résultat.

**7. Retirez l'en-tête de test et lancez la campagne**

Supprimez l'en-tête `Idempotency-Key` utilisé pour les tests, ou remplacez-le par une valeur différente pour chaque personne. Lancez ensuite la campagne.

### Options de modèle par personne

Le corps de la requête accepte ces champs pour chaque destinataire. L'[introduction à l'API](https://knowledge.flowella.io/fr/api-reference/introduction.md) et le [document OpenAPI](https://api.flowella.io/v1/openapi.json) décrivent la requête complète.

| Champ | Utilisation |
| - | - |
| `phone` | Le numéro WhatsApp de la personne. Obligatoire. |
| `bodyParameters` | Les valeurs des variables du corps, dans l'ordre. Jusqu'à 20. |
| `buttonParameters` | Les valeurs des variables de bouton URL (`subType` `url`), des boutons de Flow (`subType` `flow`) ou des boutons de copie de code (`subType` `copy_code`). |

Pour un modèle avec un en-tête image, vidéo ou document, vous pouvez indiquer un lien public vers le fichier dans `headerMedia.url`, au premier niveau du corps.

### Envois répétés et idempotence

`POST /v1/templates/send` vous évite d'envoyer deux fois le même message, ce qui compte car Customer.io relance une action webhook lorsqu'il ne reçoit pas de réponse `2xx` :

* Sans en-tête `Idempotency-Key`, Flowella utilise une empreinte du corps de la requête comme clé. Un corps identique à l'octet près dans les 7 jours renvoie l'`id` d'origine et n'envoie rien. Comme le corps de chaque personne contient son propre numéro, une campagne normale envoie une fois à chacun.
* Avec un en-tête `Idempotency-Key`, toute requête portant la même clé dans les 7 jours renvoie l'`id` d'origine et n'envoie rien, même si le corps a changé.
* Par ailleurs, Flowella ignore un second envoi du même modèle au même numéro dans les 15 secondes.

> [!WARNING]
>
> Ne laissez jamais une valeur `Idempotency-Key` fixe sur une action de campagne en production. Seule la première personne reçoit le message : chaque requête suivante réutilise la clé, donc Flowella renvoie le premier `id` et n'envoie rien. Retirez l'en-tête avant de lancer la campagne, ou construisez une valeur propre à chaque personne, par exemple un nom de campagne suivi de `{{customer.id}}`.

Ces mêmes règles expliquent la plupart des tests qui échouent. Renvoyer le même modèle à la même personne de test produit le même corps : Flowella n'envoie donc rien si vous ne changez pas la valeur `Idempotency-Key` à chaque fois.

### Envoyer à un grand segment

Chaque requête de Customer.io met un envoi en file, que Flowella livre en arrière-plan en relançant les erreurs WhatsApp temporaires. Deux limites s'appliquent aux grandes campagnes :

* **La limite de messagerie de Meta.** Meta plafonne le nombre de personnes que vous pouvez contacter hors fenêtre de 24 heures sur 24 heures glissantes. Voir [Limites de messagerie](https://knowledge.flowella.io/fr/whatsapp/limits/messaging-limits.md).
* **La limite de débit de votre clé API.** Les requêtes au-delà de la limite renvoient `429` avec un en-tête `Retry-After`. Voir [Limites de débit](https://knowledge.flowella.io/fr/api-reference/introduction.md#rate-limits).

Étalez les gros envois avec les contrôles d'envoi de Customer.io et suivez l'avancement dans l'onglet **Statistics** du modèle. Flowella ignore toute personne désinscrite du numéro d'envoi. Voir [Désinscriptions](https://knowledge.flowella.io/fr/app/opt-outs.md).

## Synchroniser les messages WhatsApp entrants vers Customer.io (facultatif)

Cette partie envoie vers Customer.io chaque message WhatsApp qu'un contact vous adresse, pour mettre à jour la personne ou lancer d'autres campagnes.

**1. Créez une automatisation déclenchée par webhook dans Customer.io**

Créez une campagne ou une automatisation déclenchée par webhook et copiez l'URL de webhook générée par Customer.io. Voir le guide Customer.io sur les [campagnes webhook](https://docs.customer.io/journeys/webhook-triggered-campaigns/).

**2. Ajoutez un webhook sortant dans Flowella**

Dans Flowella, allez dans **Settings**, puis **Webhooks**, et sélectionnez **Add webhook**. Collez l'URL Customer.io dans **Endpoint URL**, saisissez un secret de signature et cochez uniquement `message.received` sous **Events**. Voir [Webhooks](https://knowledge.flowella.io/fr/settings/webhooks.md).

**3. Envoyez des données d'exemple**

Envoyez-vous un modèle WhatsApp depuis Flowella et répondez-y, afin que Customer.io reçoive un véritable événement `message.received` à partir duquel construire le workflow. Chaque événement ressemble à ceci :

```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** dans Flowella envoie un événement `webhook.test`, sans contact : filtrez-le à l'étape suivante.

**4. Ne gardez que les vrais messages entrants**

Ajoutez une **True/False Branch** qui ne continue que si le `type` du déclencheur vaut `message.received`.

**5. Recherchez le contact dans Flowella**

L'événement contient des identifiants, pas le numéro de téléphone. Ajoutez une action **Send and receive data** avec la méthode `GET`, l'URL `https://api.flowella.io/v1/contacts/{{trigger.data.contactId}}` et le même en-tête `Authorization` que précédemment. La réponse contient les champs `id`, `phone`, `waId`, `name`, `email`, `externalId`, `isOptedOut`, `createdAt` et `updatedAt` du contact.

Pour enregistrer le message lui-même, ajoutez une autre requête vers `GET /v1/messages/{{trigger.data.messageId}}`. Son champ `body` contient le texte du message et peut être vide.

**6. Mettez à jour la personne**

Ajoutez une action **Create or Update Person**. Choisissez l'identifiant que votre espace de travail utilise pour les personnes, et définissez uniquement les attributs nécessaires, comme l'heure de la dernière réponse WhatsApp. Voir le guide Customer.io [Create or update person](https://docs.customer.io/journeys/create-update-person/).

> [!WARNING]
>
> Dans une automatisation déclenchée par webhook, **Create or Update Person** crée une nouvelle personne lorsqu'aucune ne correspond à l'identifiant. Pour éviter de créer des personnes non souhaitées, ajoutez une condition d'action pour que l'étape ne s'exécute que si la valeur de l'identifiant est présente, et testez avec un numéro absent de votre espace de travail.

### Sécurité du webhook entrant

Flowella signe chaque requête avec l'en-tête `X-Flowella-Signature`. Une automatisation Customer.io déclenchée par webhook ne peut pas vérifier cette signature : toute personne disposant de l'URL de webhook Customer.io peut y publier des données. Gardez l'URL privée, et n'utilisez pas la synchronisation entrante pour modifier des attributs de consentement ou de facturation. Voir [Vérifier les signatures](https://knowledge.flowella.io/fr/api-reference/webhooks.md#verify-signatures) si vous faites d'abord transiter les événements par votre propre endpoint.

### Désinscriptions

Lorsqu'un contact envoie `STOP` ou un autre mot-clé de désinscription, Flowella enregistre la désinscription sur ce numéro WhatsApp et bloque tout envoi ultérieur depuis ce numéro, y compris depuis Customer.io. Voir [Désinscriptions](https://knowledge.flowella.io/fr/app/opt-outs.md).

Pour copier les désinscriptions dans Customer.io, ne vous fiez pas à l'événement `optout.created` : il ne se déclenche pas actuellement pour la première désinscription d'un contact sur un numéro. Listez plutôt les désinscriptions avec `GET /v1/opt-outs`, qui accepte les filtres `createdAfter` et `phone`.

## Dépannage

| Symptôme | Cause | Solution |
| - | - | - |
| `401` avec `Invalid or expired API key` | La clé a été révoquée ou remplacée, ou mal collée. | Créez une nouvelle clé et mettez à jour l'en-tête `Authorization`. Voir [Clés API](https://knowledge.flowella.io/fr/settings/api-keys.md). |
| **Could not load API keys** dans Flowella | Seuls les Owners et les Admins peuvent gérer les clés API. | Demandez à un Owner ou un Admin de créer la clé. |
| `401` avec `Missing bearer token` | La requête est partie vers `https://app.flowella.io/api/v1`, qui redirige, et l'en-tête a été perdu. | Utilisez `https://api.flowella.io/v1`. |
| Un test renvoie `202` mais rien n'arrive | Le corps ou la `Idempotency-Key` correspondait à un envoi des 7 derniers jours, ou le même modèle est parti vers le même numéro dans les 15 secondes. | Utilisez une nouvelle valeur `Idempotency-Key` à chaque test. |
| Seule la première personne de la campagne a reçu le message | Une valeur `Idempotency-Key` fixe est restée sur l'action. | Retirez l'en-tête, ou rendez sa valeur unique pour chaque personne. |
| L'envoi affiche un échec dans l'onglet **Statistics** | Meta n'a pas pu livrer le message, par exemple parce que le numéro n'est pas sur WhatsApp. | Lisez la raison dans la colonne **Details**. Voir [Codes d'erreur Meta](https://knowledge.flowella.io/fr/whatsapp/errors/error-codes.md). |
| **Invalid phone number.** dans l'onglet **Statistics** | L'attribut de téléphone est vide ou n'est pas au format international. | Enregistrez les numéros avec l'indicatif du pays, par exemple `+447700900123`. |
| Customer.io ne reçoit aucun événement entrant | Le webhook Flowella est inactif ou `message.received` n'est pas coché. | Consultez le **Delivery log** du webhook dans Flowella. Voir [Webhooks](https://knowledge.flowella.io/fr/settings/webhooks.md#delivery-log). |

## Pages associées

> [card] [Introduction à l'API](https://knowledge.flowella.io/fr/api-reference/introduction.md)
>
> Authentification, idempotence, limites de débit et erreurs.

> [card] [Référence des webhooks](https://knowledge.flowella.io/fr/api-reference/webhooks.md)
>
> Types d'événements, corps des requêtes et signatures.

> [card] [Variables de modèle](https://knowledge.flowella.io/fr/app/template-variables.md)
>
> Variables, exemples et valeurs de repli.

> [card] [Envoi groupé](https://knowledge.flowella.io/fr/app/bulk-send.md)
>
> Envoyez plutôt un modèle à une liste depuis l'application Flowella.


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