API REST Flowella : authentification, scopes, limites et erreurs

L’API REST Flowella vous permet d’envoyer des messages WhatsApp, de gérer les contacts et les désinscriptions, de travailler avec les modèles et les Flows, et de lire les données analytiques depuis votre propre code. Cette page présente ce que vous devez savoir avant d’appeler un endpoint. La section Endpoints de cette référence API documente chaque requête. Pour la liste complète et à jour, utilisez le document OpenAPI en ligne ou la documentation API interactive de l’application.

URL de base

https://api.flowella.io/v1

Chaque endpoint se trouve sous cette base, par exemple https://api.flowella.io/v1/messages. Utilisez-la même lorsque l’application affiche une adresse se terminant par /api/v1, comme API base URL dans le Developer hub.

Les requêtes adressées à l’hôte de l’application, https://app.flowella.io/api/v1/..., sont redirigées de façon permanente (308) vers https://api.flowella.io/v1/.... De nombreux clients HTTP suppriment l’en-tête Authorization lorsqu’ils suivent une redirection vers un autre hôte, de sorte que la requête redirigée peut échouer avec 401. Appelez directement https://api.flowella.io/v1.

Authentification

Envoyez un jeton bearer dans l’en-tête Authorization de chaque requête :

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Flowella accepte deux types de jeton. Tous deux n’agissent que sur une seule organisation.

Jeton	Commence par	Provenance	Scopes	Expiration
Clé API	`flo_`	Settings → API keys, créée par un Owner ou un Admin. Consultez Clés API.	Tous les scopes	Aucune. Fonctionne jusqu’à sa révocation.
Jeton d’accès OAuth	`fla_`	Une application OAuth enregistrée sous Settings → Developer apps. Consultez Enregistrer une application partenaire avec OAuth.	Uniquement les scopes accordés lors de l’autorisation de l’application	1 heure. Demandez un nouveau jeton à son expiration.

Utilisez une clé API pour vos propres scripts et intégrations. Utilisez une application OAuth lorsque d’autres organisations Flowella installent votre intégration.

Traitez les clés et les jetons comme des mots de passe. Ne les enregistrez jamais dans un système de gestion de code source et ne les collez jamais dans une messagerie ou des documents partagés. Révoquez une clé dont vous n’avez plus besoin dans Clés API.

Vérifier vos identifiants

Appelez l’endpoint ping pour confirmer qu’une clé ou un jeton fonctionne :

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

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

import os
import requests

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

Une réponse 200 OK signifie que vous êtes authentifié. organizationId est l’identifiant numérique de votre organisation :

{
  "ok": true,
  "organizationId": 4821
}

Une réponse 401 porte le code UNAUTHORIZED et l’un des messages suivants : Missing bearer token, Invalid or expired API key, Invalid or expired access token ou Unsupported bearer token.

Scopes

Chaque endpoint nécessite un scope. Les clés API créées dans l’application disposent de tous les scopes. Les jetons d’accès OAuth n’ont que les scopes accordés lors de l’autorisation.

Scope	Autorise
`messages:read`	La lecture des messages.
`messages:write`	L’envoi de messages avec `POST /v1/messages`.
`contacts:read`	La lecture des contacts et des désinscriptions.
`contacts:write`	La création, la mise à jour et la suppression de contacts, les upserts groupés et l’enregistrement des désinscriptions.
`conversations:read`	La lecture des conversations et des canaux WhatsApp.
`conversations:write`	La mise à jour, la fermeture et la réouverture des conversations.
`templates:read`	La lecture des modèles et de leur statut d’approbation.
`templates:write`	La création, la modification, la soumission et la suppression de modèles, les envois de test et les envois groupés avec `POST /v1/templates/send`.
`webhooks:manage`	La gestion des webhooks, des livraisons, des rejeux et des secrets de signature.
`analytics:read`	La lecture des données analytiques et de l’utilisation.
`account:read`	La lecture des capacités, du statut des intégrations et du détail des requêtes.
`flows:read`	La lecture des Flows et de leur statut de synchronisation.
`flows:write`	La création, la modification, la publication et la suppression de Flows, ainsi que la configuration des fournisseurs de formulaires.
`forms:ingest`	L’envoi et la lecture des soumissions de formulaires, y compris les webhooks de formulaires entrants.
`events:read`	La lecture du flux d’événements avec `GET /v1/events`.
`jobs:read`	La lecture des tâches en arrière-plan et de leurs résultats.
`jobs:write`	L’annulation des tâches en arrière-plan.
`sandbox:manage`	La lecture et la modification du paramètre sandbox, et l’utilisation des outils de test du sandbox.

GET /v1/ping et GET /v1/rate-limits ne nécessitent aucun scope. GET /v1/capabilities (scope account:read) liste les scopes dont dispose votre jeton. Une requête sans le scope requis renvoie 403 avec le code INSUFFICIENT_SCOPE. details.required liste les scopes manquants :

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token is missing required scope(s)",
    "requestId": "req_5b1e0c2a-8f3d-4e6a-9c7b-2d4f6a8e0b1c",
    "details": { "required": ["webhooks:manage"] }
  }
}

Erreurs

Les erreurs utilisent toutes la même enveloppe. requestId identifie la requête lorsque vous contactez l’assistance, et details contient des informations supplémentaires, comme les problèmes de validation, le cas échéant :

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

Statut HTTP	`error.code`	Quand il apparaît
`400`	`BAD_REQUEST`	La requête n’a pas passé la validation, l’`API-Version` n’est pas prise en charge ou l’`Idempotency-Key` n’a pas la bonne longueur.
`400`	`META_ERROR`	Meta a rejeté la requête.
`400`	`INVALID_TEMPLATE_NAME`, `INVALID_TEMPLATE_COMPONENTS`	Le nom ou les composants du modèle ne sont pas valides.
`401`	`UNAUTHORIZED`	Le jeton bearer est absent, invalide, révoqué ou expiré.
`402`	`PAYMENT_REQUIRED`	Le paiement de votre abonnement est en retard.
`403`	`INSUFFICIENT_SCOPE`	Votre jeton ne dispose pas d’un scope requis par l’endpoint.
`403`	`FORBIDDEN`	L’action n’est pas autorisée, par exemple un envoi à un contact qui s’est désinscrit sur ce numéro, ou votre abonnement n’est pas actif.
`404`	`NOT_FOUND`	La ressource n’existe pas dans votre organisation.
`409`	`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`, `IDEMPOTENCY_KEY_IN_FLIGHT`	Une valeur en double, comme un `externalId`, ou un conflit de clé d’idempotence.
`429`	`RATE_LIMITED`	Vous avez envoyé trop de requêtes. Consultez Limites de débit.
`500`	`INTERNAL_ERROR`, `INTERNAL_SERVER_ERROR`	Un problème est survenu côté Flowella. Réessayez plus tard et communiquez le `requestId` à l’assistance.

La valeur error.code est stable, votre code peut donc s’y fier. Le texte error.message est destiné aux personnes et peut changer.

Limites de débit

Chaque clé API et chaque jeton d’accès OAuth dispose de sa propre limite de requêtes par minute. Flowella compte les requêtes dans des fenêtres fixes d’une minute qui commencent à la minute pile (UTC). Les réponses aux requêtes qui passent les vérifications d’authentification et de scope incluent ces en-têtes :

En-tête	Signification
`X-RateLimit-Limit`	Nombre de requêtes autorisées dans chaque fenêtre.
`X-RateLimit-Remaining`	Nombre de requêtes restantes dans la fenêtre en cours.
`X-RateLimit-Reset`	Fin de la fenêtre en cours, en secondes Unix.

Lorsque vous dépassez la limite, Flowella renvoie 429 avec le code RATE_LIMITED et un en-tête Retry-After indiquant le nombre de secondes à attendre. GET /v1/rate-limits renvoie vos valeurs limit, remaining et reset au format JSON. Pour les envois importants, utilisez POST /v1/templates/send, qui accepte jusqu’à 50 000 destinataires en une seule requête. La requête accepte aussi un champ facultatif throttlePerHour, un nombre entier de 1 à 100 000, mais il ne régule pas les envois pour le moment, ne vous y fiez donc pas. Pour étaler un envoi important dans le temps, divisez la liste des destinataires en lots plus petits et envoyez chaque lot séparément.

Identifiants de requête

Les réponses incluent un en-tête X-Request-Id, et les corps d’erreur le reprennent sous error.requestId. POST /v1/templates/send fait exception : consultez Envois groupés de modèles. Pour utiliser votre propre identifiant, envoyez un en-tête X-Request-Id de 128 caractères au maximum et Flowella le réutilise. Communiquez l’identifiant de requête lorsque vous contactez l’assistance. Pour consulter une requête vous-même, appelez GET /v1/requests/{requestId} (scope account:read) : il renvoie la requête journalisée avec les événements, tâches et livraisons de webhooks qui y sont liés. Le Developer hub liste vos requêtes récentes et leurs identifiants.

Idempotence

Les clés d’idempotence vous permettent de relancer une requête d’écriture après un délai dépassé ou une erreur réseau sans effectuer le travail deux fois. POST /v1/templates/send suit ses propres règles, décrites ci-dessous.

La plupart des requêtes d’écriture

Les requêtes POST, PATCH, PUT et DELETE acceptent un en-tête facultatif Idempotency-Key :

La clé doit comporter de 8 à 255 caractères. Les autres longueurs renvoient 400.
Flowella mémorise chaque clé pour votre organisation pendant 24 heures.
Une répétition avec la même clé, la même méthode, le même chemin et le même corps renvoie la réponse enregistrée sans exécuter à nouveau la requête.
Une répétition avec la même clé mais une méthode, un chemin ou un corps différent renvoie 409 IDEMPOTENCY_KEY_CONFLICT.
Une répétition envoyée alors que la première requête est encore en cours renvoie 409 IDEMPOTENCY_KEY_IN_FLIGHT. Patientez puis réessayez.
Les réponses renvoient la clé dans un en-tête Idempotency-Key.

Les requêtes sans cet en-tête s’exécutent normalement, sans protection contre les doublons.

Envois groupés de modèles

Les envois groupés de modèles 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 envoie le lot en arrière-plan et relance 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 Statistics du modèle dans l’application. Transmettez un en-tête Idempotency-Key qui identifie chaque lot :

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

Cet endpoint gère les clés différemment des autres requêtes d’écriture :

La clé peut comporter jusqu’à 200 caractères. Une clé plus longue renvoie 400.
Une répétition avec la même clé dans un délai de 7 jours renvoie l’id d’origine et n’envoie rien, même si le corps a changé.
Sans l’en-tête, Flowella utilise un hachage du corps de la requête comme clé. Si vous renvoyez un corps identique octet pour octet dans un délai de 7 jours, vous récupérez l’id d’origine et rien n’est envoyé. Utilisez une nouvelle clé pour chaque lot que vous souhaitez envoyer.

D’autres comportements diffèrent aussi pour cet endpoint :

Appelez-le avec une clé API. Les jetons d’accès OAuth sont refusés avec 401.
Ses réponses n’incluent pas les en-têtes X-Request-Id, API-Version ni X-RateLimit-*. Ses requêtes sont tout de même décomptées de la limite de débit de la clé.

Versionnage

Vous pouvez fixer la version de l’API avec l’en-tête API-Version :

API-Version: 2026-08-11

2026-08-11 est la seule version prise en charge et la version par défaut si vous omettez l’en-tête. Toute autre valeur, ou une valeur qui n’est pas une date YYYY-MM-DD, renvoie 400 avec le message Unsupported API-Version. Les réponses renvoient la version dans les en-têtes API-Version et X-Flowella-Api-Version.

Sandbox

Le sandbox vous permet de tester une intégration sans rien envoyer à WhatsApp. Il fonctionne sur votre organisation réelle : il n’existe pas de compte de test distinct. Vous pouvez l’utiliser de deux façons :

Une clé sandbox, qui n’affecte que les requêtes effectuées avec cette clé. Consultez Clés sandbox.
Le API sandbox à l’échelle de l’organisation dans le Developer hub, qu’un Owner ou un Admin peut activer. Consultez API sandbox.

Lorsque le sandbox s’applique, POST /v1/messages enregistre le message et renvoie "sandbox": true sans contacter Meta, et la soumission de modèles renvoie une décision simulée instantanée. Les outils de test du sandbox sous /v1/test/ et /v1/sandbox nécessitent le scope sandbox:manage.

Pagination

Les endpoints de liste, comme /v1/conversations, /v1/contacts et /v1/templates, utilisent une pagination par curseur :

Transmettez limit (de 1 à 100, 25 par défaut) et un cursor facultatif.
La réponse contient items et, lorsqu’il reste des résultats, un nextCursor.
Renvoyez nextCursor comme paramètre cursor pour récupérer la page suivante.
Lorsque nextCursor est absent ou vaut null, vous avez atteint la fin.

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

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, les valeurs date seule (2025-01-15) et ISO 8601 complètes fonctionnent toutes deux.

Numéros de téléphone

Transmettez les numéros de téléphone au format E.164 (+15551234567) dans la mesure du possible. Flowella normalise les variantes courantes, mais E.164 reste le plus sûr.

Canaux

De nombreux endpoints 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, transmettez l’identifiant explicitement pour ne pas envoyer depuis le mauvais numéro. Pour le modèle d’URL complet et le changement de canal, consultez Multi-canal.

Spécification OpenAPI

La spécification en ligne, lisible par machine, est publique :

https://api.flowella.io/v1/openapi.json

Importez-la dans Postman, Insomnia ou un générateur de code. Elle décrit l’authentification par clé API et par OAuth.

Ressources pour les développeurs

L’application propose d’autres ressources pour les développeurs. Ces pages sont publiques, vous pouvez donc les ouvrir sans vous connecter :

Ressource	Adresse
Documentation API interactive, avec requêtes d’essai	`https://app.flowella.io/docs`
Collection Postman (télécharge un fichier `.json`)	`https://app.flowella.io/docs/postman`
Guide du sandbox	`https://app.flowella.io/docs/sandbox`
Guides de démarrage rapide en Markdown pour Salesforce, Zoho CRM, SurveyMonkey, Typeform et n8n	`https://app.flowella.io/docs/quickstarts/salesforce`, avec `zoho`, `surveymonkey`, `typeform` ou `n8n` à la place de `salesforce`

Le Developer hub dans Settings regroupe ces liens avec vos requêtes API récentes et le commutateur du API sandbox.

Associez cette page à la référence des webhooks pour réagir aux événements au lieu d’interroger régulièrement l’API.

Premiers pas

Essentiels

Utiliser l'application

Paramètres

Configuration Meta et WhatsApp

Intégration HubSpot

Flows et campagnes

Référence API

Dépannage

Journal des modifications

API REST Flowella : authentification, scopes, limites et erreurs

URL de base

Authentification

Vérifier vos identifiants

Scopes

Erreurs

Limites de débit

Identifiants de requête

Idempotence

La plupart des requêtes d’écriture

Envois groupés de modèles

Versionnage

Sandbox

Date et heure

Numéros de téléphone

Canaux

Spécification OpenAPI

Ressources pour les développeurs

​URL de base

​Authentification

​Vérifier vos identifiants

​Scopes

​Erreurs

​Limites de débit

​Identifiants de requête

​Idempotence

​La plupart des requêtes d’écriture

​Envois groupés de modèles

​Versionnage

​Sandbox

​Pagination

​Date et heure

​Numéros de téléphone

​Canaux

​Spécification OpenAPI

​Ressources pour les développeurs

URL de base

Authentification

Vérifier vos identifiants

Scopes

Erreurs

Limites de débit

Identifiants de requête

Idempotence

La plupart des requêtes d’écriture

Envois groupés de modèles

Versionnage

Sandbox

Pagination

Date et heure

Numéros de téléphone

Canaux

Spécification OpenAPI

Ressources pour les développeurs