Introduction à l'API

L’API REST Flowella vous permet d’envoyer des messages WhatsApp, de gérer les contacts et les opt-outs, d’établir des listes et des modèles d’envoi en masse, et d’obtenir des analyses - de manière programmatique. Cette page couvre tout ce que vous devez savoir avant d’appeler un point de terminaison. La référence complète du point de terminaison se trouve dans la barre latérale Référence API (générée automatiquement à partir de la spécification OpenAPI).

URL de base

https://api.flowella.io/v1

Tous les points de terminaison v1 se trouvent sous cette base canonique — par exemple https://api.flowella.io/v1/messages.

L’API se trouvait auparavant sur l’hôte de l’application à https://app.flowella.io/api/v1/.... Les requêtes vers cet ancien chemin sont redirigées de manière permanente (308) vers https://api.flowella.io/v1/..., en préservant la méthode et le corps — les intégrations existantes continuent donc de fonctionner. Mettez à jour votre URL de base dès que possible pour éviter le saut supplémentaire.

Authentification

Chaque requête nécessite une clé API dans l’en-tête Authorization :

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

Les clés sont liées à l’organisation - elles agissent sur une seule organisation Flowella et héritent des permissions d’un administrateur de cette organisation.

Traitez les clés comme des mots de passe. Ne les livrez jamais au contrôle de source, ne les collez jamais dans le chat ou les documents partagés, et faites-en la rotation lorsque les coéquipiers quittent l’organisation. Voir Settings → API keys pour les étapes de rotation.

Création d’une clé

Vous devez avoir le rôle Owner ou Admin pour gérer les clés API.

Allez dans Réglages → Clés API dans l’application Flowella.
Cliquez sur Créer une clé et donnez-lui un nom mémorable.
Copiez la clé une fois - elle n’est affichée qu’au moment de la création.

Traitez les clés comme des mots de passe : ne les soumettez jamais au contrôle de source, ne les collez jamais dans le chat et faites-en la rotation lorsque les coéquipiers quittent l’organisation.

Vérification d’une clé

Appuyez sur le point de terminaison ping pour confirmer qu’une clé est valide :

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

Un 200 OK avec un { "ok": true, "organizationId": "…" } signifie que vous êtes authentifié.

Erreurs

Toutes les erreurs sont renvoyées dans une enveloppe cohérente :

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Statut HTTP	Quand vous le verrez
`400`	Validation failed, malformed body, or upstream Meta rejection	`400`	Validation failed, malformed body, or upstream Meta rejection
`401`	Clé API manquante ou invalide
`402`	Paiement requis - votre abonnement ne couvre pas l’action.
`403`	Interdit - par exemple, envoi à un contact exclu, ou Meta n’est pas connecté.
`404`	Le canal ou la ressource demandée n’existe pas.
`429` - Le canal ou la ressource demandée n’existe pas.

Le champ error.code est stable et peut être activé en toute sécurité par programmation. Le champ error.message est lisible par l’homme et peut changer.

Limites de débit

Les clés API sont limitées par organisation. Si vous dépassez la limite, vous recevrez un 429 avec le code RATE_LIMITED et le message Too many requests. Lorsqu’il est présent, l’en-tête de réponse Retry-After vous indique combien de secondes attendre. Revenez en arrière et réessayez avec un délai exponentiel. Si vous effectuez des envois massifs, préférez POST /v1/templates/send avec le paramètre throttlePerHour - Flowella applique la limitation côté serveur, de sorte que vous n’avez pas besoin de rythmer les demandes vous-même.

Clés d’idempotence

Les envois de modèles en masse sont asynchrones. POST /v1/templates/send valide la requête, la met en file d’attente de manière durable et renvoie immédiatement 202 Accepted :

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella livre le lot en arrière-plan et réessaie automatiquement les erreurs WhatsApp temporaires. Les destinataires sont traités individuellement, de sorte qu’un numéro invalide ne bloque pas le reste du lot. Suivez la progression de la livraison dans l’onglet Statistiques du modèle dans l’application. Comme la livraison a lieu après la réponse, les nouvelles tentatives doivent être sûres. Passez un en-tête Idempotency-Key (jusqu’à 200 caractères) qui identifie de manière unique chaque lot :

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Les répétitions de la même clé dans un délai de sept jours renvoient l’id du travail d’origine au lieu de créer un nouvel envoi. Vous pouvez réessayer une requête en toute sécurité après un délai d’expiration ou une erreur réseau sans envoyer deux fois de messages à qui que ce soit. Si vous omettez l’en-tête, Flowella dérive une clé du corps de la requête. Un lot identique soumis deux fois de suite n’est donc pas envoyé en double. Une clé explicite reste plus sûre, car toute modification du corps (même le réordonnancement des destinataires) produit une nouvelle clé dérivée.

Pagination

Les points de terminaison de la liste (/conversations, /contacts, /templates) utilisent la pagination du curseur :

Passez limit (1-100, par défaut 25) et un cursor optionnel.
La réponse contient items et, s’il y a plus de résultats, nextCursor.
Renvoyez nextCursor en tant que paramètre cursor pour récupérer la page suivante.
Lorsque nextCursor est manquant, vous avez atteint la fin.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

Date et heure

Tous les horodatages sont des chaînes ISO 8601 en UTC (par exemple 2025-01-15T14:30:00.000Z). Lorsque l’API accepte des dates, la date seule (2025-01-15) et la chaîne ISO 8601 complète sont forcées côté serveur.

Numéros de téléphone

Transmettez les numéros de téléphone sous la forme E.164 (+15551234567) dans la mesure du possible. Flowella normalisera les variations courantes côté serveur, mais E.164 est la forme la plus sûre.

Canaux

De nombreux points d’accès acceptent un whatsappChannelId. Si votre organisation n’a qu’un seul canal et que vous l’omettez, Flowella utilise votre canal par défaut. Si vous avez plusieurs canaux, passez l’ID explicitement pour éviter d’envoyer à partir du mauvais expéditeur. Pour le modèle d’URL complet et le changement de canal, voir Multicanal.

OpenAPI spec

La spécification lisible en machine se trouve à l’adresse suivante :

/api-reference/openapi.json

Déposez-la dans Postman, Insomnia, ou le générateur de code de votre choix.

Vous construisez une intégration ? Associez cette page à Webhooks pour réagir aux événements au lieu d’interroger l’état.

Premiers pas

Journal des modifications

Essentiels

Utiliser l'application

Paramètres

Configuration Meta et WhatsApp

Intégration HubSpot

Flows et campagnes

Compte et connexion

Sécurité et confidentialité

Référence API

Dépannage

Introduction à l'API

URL de base

Authentification

Création d’une clé

Vérification d’une clé

Erreurs

Limites de débit

Clés d’idempotence

Date et heure

Numéros de téléphone

Canaux

OpenAPI spec

​URL de base

​Authentification

​Création d’une clé

​Vérification d’une clé

​Erreurs

​Limites de débit

​Clés d’idempotence

​Pagination

​Date et heure

​Numéros de téléphone

​Canaux

​OpenAPI spec

URL de base

Authentification

Création d’une clé

Vérification d’une clé

Erreurs

Limites de débit

Clés d’idempotence

Pagination

Date et heure

Numéros de téléphone

Canaux

OpenAPI spec