Journal des développeurs : API, webhooks, OAuth et MCP

Cycle de vie des Flows

• GET /v1/flows/{id} renvoie le statut du Flow chez Meta (metaStatus), ses écrans, ses champs et son action de soumission.
• POST /v1/flows/{id}/publish?dry_run=true vérifie un Flow sans le publier.
• POST /v1/flows/{id}/deprecate retire un Flow chez Meta. Meta ne peut pas annuler cette opération. Flowella la bloque tant que des modèles utilisent le Flow, sauf si vous envoyez force.
• DELETE /v1/flows/{id} renvoie 409 HUBSPOT_FLOW_MANAGED pour un Flow créé à partir d’un formulaire HubSpot, et 409 FLOW_REFERENCED_BY_TEMPLATES tant qu’un brouillon de modèle utilise encore le Flow. Supprimer un Flow ne le supprime jamais chez Meta : dépréciez-le d’abord pour l’y retirer. Publier un Flow déprécié renvoie 409 FLOW_DEPRECATED.
• Lorsque vous créez un modèle, un bouton Flow peut pointer vers un Flow Flowella avec flowellaFlowId au lieu d’un ID de Flow Meta.
• Les Flows que vous créez via l’API sont publiés avec l’écran d’entrée MAIN_FORM. Les Flows publiés auparavant continuent de fonctionner. Republiez-les avant de les utiliser avec flowellaFlowId.

Webhooks

• Nouvel événement flow.status_updated lorsque le statut d’un Flow change chez Meta, par exemple lorsqu’il est déprécié. Abonnez-vous-y dans Settings → Webhooks. Types d’événements

Identifiants

• GET /v1/ping indique comment vous êtes authentifié, vos scopes et, pour les applications, le client ID. Vérifier vos identifiants
• Les réponses idempotentes rejouées incluent l’en-tête Idempotent-Replayed: true. Idempotence

Serveur MCP

• Les assistants IA peuvent se connecter au serveur MCP Flowella en s’authentifiant, sans clé API. L’utilisateur choisit une organisation et sélectionne Allow access sur l’écran de consentement Flowella. Les connexions des membres qui ne sont ni Owner ni Admin sont en lecture seule. Applications développeur
• Installed apps devient AI assistants, avec une colonne Last token. Examiner et révoquer les applications installées

• Serveur MCP Flowella. Les assistants IA compatibles avec le Model Context Protocol peuvent lire vos canaux, vos modèles et vos Flows. Le serveur est en lecture seule et utilise une clé API d’organisation. Clés API
• GET /v1/flows/{id} accepte l’ID de formulaire Flowella. Modifier le schéma d’un Flow créé à partir d’un formulaire HubSpot renvoie 409 : faites la modification dans HubSpot et synchronisez à nouveau. API REST Flowella
• Les Flows créés dans Flowella peuvent envoyer chaque soumission vers l’un de vos endpoints de webhook, défini dans l’onglet Settings du Flow. Webhooks
• L’enregistrement d’une application développeur avec une URI de redirection non valide renvoie une erreur en langage clair. Enregistrer une application

Changements incompatibles

• API-Version n’accepte que 2026-08-11. Toute autre valeur renvoie 400. Omettez l’en-tête ou envoyez 2026-08-11. Versionnage
• Les endpoints de webhook nécessitent une URL HTTPS publique. Les adresses privées, de bouclage et de métadonnées cloud ne sont pas acceptées. Vérifiez chaque endpoint avant la mise à niveau. Ajouter un endpoint de webhook
• Applications OAuth. Examinez ces exigences avant de mettre à niveau une application basée sur OAuth Flowella :
  • Les requêtes sans scope obtiennent un accès en lecture seule, et les scopes inconnus sont refusés.
  • Les endpoints token, introspect et revoke exigent l’authentification du client.
  • La requête d’autorisation exige state.
  • Les octrois client credentials ne renvoient pas de jeton d’actualisation.
  • Révoquer un jeton ne révoque que la famille de ce jeton.
  Applications développeur

API

• Les réponses d’erreur incluent un requestId dans error, que vous pouvez communiquer au support. Erreurs
• La création d’un contact renvoie 201 et sa mise à jour renvoie 200. Un externalId en double renvoie 409, et un contact supprimé renvoie 404.

Webhooks

• Nouveaux événements contact.created, contact.updated et contact.deleted. Types d’événements
• Donnez un nom à chaque endpoint avec Name (optional). Le nom apparaît au-dessus de l’URL dans la liste.
• Pendant les 24 heures qui suivent la rotation d’un secret de signature, Flowella signe aussi chaque envoi avec l’ancien secret et l’envoie dans X-Flowella-Signature-Previous, pour que vous puissiez changer de secret sans perdre d’événements. Renouveler un secret de signature
• Un événement renvoyé conserve son ID et son horodatage d’origine. Les enregistrements de livraison de l’API incluent l’ID de corrélation, les en-têtes de réponse et l’heure de la prochaine tentative. Dédupliquer les événements
• Les propriétaires de l’organisation reçoivent une seule notification lorsque Flowella met en pause un endpoint en échec. Nouvelles tentatives et délais

• Utilisez https://api.flowella.io. Les requêtes vers https://api.flowella.io/v1/... renvoient du JSON. Les anciennes URL https://app.flowella.io/api/v1/..., y compris le document OpenAPI, redirigent de façon permanente vers l’hôte de l’API. Mettez à jour votre URL de base pour ne pas dépendre de la redirection. URL de base
• Le premier serveur du document OpenAPI est https://api.flowella.io, donc les collections importées appellent la bonne URL de base. Spécification OpenAPI
• L’API refuse les composants de modèle non valides, ainsi que les modèles qui dépassent les limites de soumission de Meta, avant qu’ils n’atteignent Meta.
• Vous pouvez créer et envoyer des modèles carrousel via l’API. Si vous ne transmettez pas de média pour une carte, Flowella utilise l’échantillon approuvé de cette carte. Modèles carrousel
• Les valeurs de repli des variables de modèle s’appliquent aux envois via l’API. Valeurs de repli
• Le Developer hub comprend des guides complets et une collection Postman. Developer hub

• Les envois répétés d’un même modèle via l’API partent plus vite.
• Lorsque Meta limite un appel de gestion de modèles, Flowella le signale comme une limite de débit, pour que vos nouvelles tentatives s’espacent correctement. Limites de débit

• POST /v1/templates/send renvoie 202. Flowella accepte la requête, renvoie immédiatement un ID de tâche et délivre les messages en arrière-plan, en relançant les erreurs WhatsApp temporaires. Si votre intégration attend une réponse 200, mettez-la à jour pour attendre 202 avec "status": "accepted". Suivez la remise dans l’onglet Statistics du modèle. Envois groupés de modèles
• Idempotency-Key. Envoyez un en-tête Idempotency-Key avec POST /v1/templates/send et Flowella reconnaît les répétitions de la même requête pendant sept jours, en renvoyant l’ID de tâche d’origine au lieu d’envoyer à nouveau. Idempotence

• L’API REST v1 est documentée et servie sur l’hôte dédié de l’API, à l’adresse /v1/.... API REST Flowella