Intégrez WhatsApp à votre application avec KoraFlow

Avec l’API KoraFlow, votre application peut :

• envoyer des notifications WhatsApp : confirmation de commande, facture PDF, rappel de rendez-vous, code de vérification (OTP), avis d’expédition… ;
• répondre à vos clients depuis votre propre logiciel ou chatbot ;
• savoir si un message a été livré, lu ou a échoué ;
• recevoir par webhook chaque message entrant et chaque changement de statut ;
• synchroniser vos contacts avec KoraFlow.

Les messages partent du numéro WhatsApp Business connecté au compte KoraFlow (API Cloud officielle de Meta). Ils apparaissent dans la Boîte de réception KoraFlow : vos équipes voient tout ce que votre application envoie.

1. Créez un compte KoraFlow et connectez votre numéro WhatsApp Business (Réglages → WhatsApp).
2. Dans Réglages → Intégrations, cliquez sur Créer la clé. Copiez-la immédiatement : elle ne sera plus jamais affichée.
3. Vérifiez la clé :

curl https://api.kora-flow.com/api/v1/me \
  -H "Authorization: Bearer kfk_VOTRE_CLE"

Réponse :

{
  "tenant": { "id": "4f6c…", "name": "Boutique Awa", "isActive": true },
  "scopes": ["messages.send", "messages.read", "templates.read", "contacts.read"],
  "plan": "Pro (Croissance)",
  "rateLimitPerMinute": 120
}

4. Envoyez votre premier message. Pour un test, écrivez d’abord au numéro de l’entreprise depuis votre téléphone (cela ouvre la fenêtre de 24 h, voir plus bas), puis :

curl -X POST https://api.kora-flow.com/api/v1/messages \
  -H "Authorization: Bearer kfk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"to": "237699112233", "text": "Bonjour ! Ceci est un test KoraFlow 🎉"}'

Le message apparaît sur le téléphone et dans la Boîte de réception KoraFlow. Suivez ensuite sa livraison avec GET /messages/{id} ou un webhook.

Chaque requête doit contenir votre clé API dans l’en-tête Authorization :

Authorization: Bearer kfk_VOTRE_CLE

Les clés commencent par kfk_. KoraFlow ne stocke qu’une empreinte (hachage) de la clé : si vous la perdez, révoquez-la et créez-en une nouvelle. Seul le propriétaire du compte peut créer ou révoquer des clés.

Scopes (permissions)

Chaque clé ne peut faire que ce que ses scopes autorisent. Donnez à chaque application le strict nécessaire.

/me, /usage et /numbers sont accessibles avec n’importe quelle clé valide.

KoraFlow utilise l’API Cloud officielle de Meta. Trois règles de Meta déterminent ce que vous pouvez envoyer :

1. La fenêtre de 24 heures

Quand un client vous écrit, une fenêtre de 24 heures s’ouvre. Pendant cette fenêtre, vous pouvez lui envoyer des messages libres : texte, image, document, vidéo, audio. En dehors de cette fenêtre, seul un modèle approuvé peut être envoyé.

2. Les modèles (templates)

Un modèle est un message pré-écrit, validé par Meta, avec des variables {{1}}, {{2}}… que vous remplissez à l’envoi. Créez-les dans KoraFlow (menu Modèles) ; la validation par Meta prend de quelques minutes à 24 h. Meta classe les modèles en trois catégories :

3. Le consentement

N’écrivez qu’à des personnes qui ont accepté d’être contactées sur WhatsApp. Des signalements « spam » font baisser la note de qualité du numéro et peuvent entraîner des restrictions par Meta. La note de chaque numéro est visible via GET /numbers.

Facturation

Chaque message envoyé avec succès via l’API est décompté du quota de messages du forfait KoraFlow, comme un envoi depuis le tableau de bord (les envois échoués ne sont pas comptés). Les éventuels frais de Meta pour les modèles s’appliquent selon la grille tarifaire de Meta du compte WhatsApp Business connecté.

Un seul point d’entrée pour tous les types de messages. Le type est déduit des champs fournis, ou indiqué avec type.

Paramètres du corps

En-têtes optionnels

Exemple : texte libre (dans la fenêtre de 24 h)

{
  "to": "237699112233",
  "text": "Bonjour Awa, votre colis est arrivé à l'agence de Douala. Passez le récupérer avant 18 h."
}

Exemple : modèle avec variables (à tout moment)

Modèle confirmation_commande : « Bonjour, votre commande {{1}} d’un montant de {{2}} est confirmée. Livraison prévue le {{3}}. »

curl -X POST https://api.kora-flow.com/api/v1/messages \
  -H "Authorization: Bearer kfk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-A1234-confirmation" \
  -d '{
    "to": "237699112233",
    "templateName": "confirmation_commande",
    "variables": ["A1234", "45 000 FCFA", "lundi 6 octobre"]
  }'

Exemple : document PDF (facture, reçu, bulletin)

{
  "to": "237699112233",
  "type": "document",
  "mediaUrl": "https://exemple.com/factures/A1234.pdf",
  "filename": "Facture-A1234.pdf",
  "caption": "Votre facture A1234"
}

L’URL doit être publique (accessible sans connexion) au moment de l’envoi. Formats acceptés par WhatsApp : images JPEG/PNG (5 Mo max.), documents PDF, Word, Excel… (100 Mo max.), vidéos MP4 (16 Mo max.), audio MP3/OGG/AAC (16 Mo max.). Hors fenêtre de 24 h, utilisez un modèle à en-tête « Document » et passez le PDF dans mediaUrl avec templateName.

Réponse

{
  "ok": true,
  "id": "8b1e6c2a-3f0d-4c55-9a8e-2f1b7d9e4a10",
  "status": "SENT",
  "to": "237699112233",
  "metaMessageId": "wamid.HBgMMjM3Njk5MTEyMjMzFQIAERgSM0Q…"
}

{id} accepte l’id KoraFlow ou le metaMessageId.

curl https://api.kora-flow.com/api/v1/messages/8b1e6c2a-3f0d-4c55-9a8e-2f1b7d9e4a10 \
  -H "Authorization: Bearer kfk_VOTRE_CLE"

{
  "data": {
    "id": "8b1e6c2a-3f0d-4c55-9a8e-2f1b7d9e4a10",
    "to": "237699112233",
    "direction": "OUTBOUND",
    "status": "READ",
    "text": "Bonjour, votre commande A1234 d'un montant de 45 000 FCFA est confirmée…",
    "template": "confirmation_commande",
    "media": null,
    "error": null,
    "metaMessageId": "wamid.HBgMMjM3Njk5MTEyMjMzFQIAERgSM0Q…",
    "createdAt": "2026-10-03T14:05:12.000Z"
  }
}

Cycle de vie d’un message

Plutôt que d’interroger cette route en boucle, abonnez-vous au webhook message.status_updated : vous êtes prévenu à chaque changement.

curl "https://api.kora-flow.com/api/v1/messages?phone=237699112233&limit=20" \
  -H "Authorization: Bearer kfk_VOTRE_CLE"

Réponse : { "data": [ …messages au même format que GET /messages/{id}… ], "count": 20 }. Les messages reçus ont direction: "INBOUND".

Liste les modèles approuvés (paramètre status=ALL pour inclure ceux en attente ou refusés). variablesCount indique combien d’éléments mettre dans variables.

{
  "data": [
    {
      "id": "0c9d…",
      "name": "confirmation_commande",
      "language": "fr",
      "category": "UTILITY",
      "status": "APPROVED",
      "variablesCount": 3,
      "components": [
        { "type": "BODY", "text": "Bonjour, votre commande {{1}} d'un montant de {{2}} est confirmée. Livraison prévue le {{3}}." }
      ]
    }
  ]
}

Si le compte a plusieurs numéros WhatsApp (ex. une agence par ville), choisissez l’expéditeur avec le champ from de POST /messages.

{
  "data": [
    { "id": "a1f2…", "name": "Boutique Douala", "phoneNumber": "237699112233", "isDefault": true,  "status": "ACTIVE", "qualityRating": "GREEN" },
    { "id": "b7c3…", "name": "Agence Yaoundé", "phoneNumber": "237677445566", "isDefault": false, "status": "ACTIVE", "qualityRating": "GREEN" }
  ]
}

qualityRating : GREEN (bonne), YELLOW (à surveiller), RED (risque de restriction par Meta).

Paramètres : limit (1–200, défaut 50), phone (recherche par numéro).

Crée le contact (ou met à jour son nom s’il existe déjà) et lui ajoute des tags — pratique pour cibler ensuite des campagnes dans KoraFlow.

{
  "phoneNumber": "237699112233",
  "name": "Awa Mballa",
  "tags": ["client-vip", "douala"]
}

Chaque nouveau contact compte dans la limite de contacts du forfait (erreur 402 CONTACTS_LIMIT si elle est atteinte).

Les 50 dernières campagnes avec leurs compteurs (targetCount, deliveredCount, failedCount) et leur status. Les campagnes se créent depuis le tableau de bord KoraFlow.

Chaque entreprise a son propre assistant : ces routes lisent et modifient uniquement celui de l’entreprise de la clé. Les instructions décrivent l’activité, le ton et les règles de réponse ; elles s’appliquent à tous les canaux, sauf si un canal a ses propres consignes. Fonctionne avec la clé IA KoraFlow comme avec votre propre clé IA. La clé IA personnelle n’est jamais renvoyée.

{
  "data": {
    "enabled": true,
    "instructions": "Tu es l'assistant de la boutique Awa (pagnes, Douala)…",
    "welcomeMessage": "Bienvenue chez Awa !",
    "ai": { "keyMode": "OWN", "provider": "openai", "model": "gpt-5" },
    "channels": [
      { "channel": "WHATSAPP", "enabled": true, "instructions": null, "welcomeMessage": null },
      { "channel": "MESSENGER", "enabled": true, "instructions": null, "welcomeMessage": null },
      { "channel": "INSTAGRAM", "enabled": true, "instructions": "Tutoie le client.", "welcomeMessage": null }
    ]
  }
}

Modification partielle : seuls les champs envoyés changent. null efface un texte. Réponse : la configuration complète à jour.

curl -X PUT https://api.kora-flow.com/api/v1/assistant \
  -H "Authorization: Bearer kfk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Tu vends des pagnes et du wax. Livraison à Douala sous 24 h. Paiement Mobile Money.",
    "channels": [{ "channel": "WHATSAPP", "instructions": "Réponds en 2 phrases au maximum." }]
  }'

Chaque modification est inscrite au journal d’audit de l’entreprise (avec l’identifiant de la clé). Erreurs : 400 INVALID_REQUEST, 400 EMPTY_UPDATE, 403 si la clé n’a pas le scope.

{
  "plan": "Pro (Croissance)",
  "period": "month",
  "messages": { "used": 3820, "limit": 10000 },
  "contacts": { "used": 1240, "limit": 10000 },
  "thisKey": { "messagesThisMonth": 2950 }
}

period vaut month pour les forfaits payants (remise à zéro le 1er du mois) et total pour le forfait gratuit (quota cumulé). thisKey donne la consommation de la clé utilisée.

Compte, scopes de la clé, forfait et débit autorisé (voir Démarrage rapide).

Les webhooks vous préviennent en temps réel : KoraFlow envoie une requête POST en JSON vers votre URL à chaque événement. Configurez-les dans Réglages → Intégrations → Webhooks sortants : saisissez l’URL HTTPS, cochez les événements, conservez le secret affiché, puis cliquez sur Tester.

Événements

Format de la requête

Tous les événements partagent la même enveloppe ; le contenu propre à l’événement est dans data :

{
  "id": "9b1f…",
  "event": "message.received",
  "tenantId": "4f6c…",
  "timestamp": "2026-10-03T14:07:40.120Z",
  "data": {
    "messageId": "c41d…",
    "contactId": "5d2a…",
    "phoneNumber": "237699112233",
    "contactName": "Awa Mballa",
    "text": "Bonjour, je veux commander 2 sacs de riz",
    "metaMsgId": "wamid.HBgM…",
    "receivedAt": "2026-10-03T14:07:39.000Z"
  }
}

Vérifier la signature

Vérifiez toujours X-KoraFlow-Signature pour être sûr que la requête vient de KoraFlow. Calculez le HMAC-SHA256 du corps brut (avant tout décodage JSON) avec votre secret, puis comparez.

import crypto from "crypto";
import express from "express";

const app = express();

app.post("/webhooks/koraflow", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.KORAFLOW_WEBHOOK_SECRET)
    .update(req.body) // Buffer brut
    .digest("hex");
  const received = req.get("X-KoraFlow-Signature") || "";
  const valid = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200); // répondre vite, traiter ensuite
  if (event === "message.received") handleIncoming(data);
  if (event === "message.status_updated") updateDelivery(data.messageId, data.status);
});

Livraison et nouvelles tentatives

• Votre endpoint doit répondre un code 2xx en moins de 10 secondes. Répondez d’abord, traitez ensuite (file d’attente, tâche de fond).
• En cas d’échec (code non-2xx, délai dépassé, erreur réseau), KoraFlow réessaie 2 fois : après 2 s puis après 5 s.
• Un même événement peut exceptionnellement arriver deux fois : dédoublonnez avec data.messageId (ou data.metaMsgId).
• L’ordre d’arrivée n’est pas garanti (un READ peut arriver avant un DELIVERED) : ne faites jamais régresser un statut.
• L’historique des livraisons (code HTTP, réponse de votre serveur) est visible dans Réglages → Intégrations.

En cas d’erreur, la réponse contient un message lisible et, le plus souvent, un code stable à utiliser dans votre programme :

{
  "error": "Limite de 10000 messages mensuels atteinte sur le forfait Pro (Croissance). Passez au forfait supérieur dans « Abonnement » ou attendez le mois prochain.",
  "code": "MESSAGES_LIMIT"
}

Erreurs Meta courantes

Elles apparaissent dans details (réponse 502) ou dans error d’un message FAILED.

Débit

Le nombre de requêtes par minute est limité par clé, selon le forfait. Valeurs standard ci-dessous ; la valeur exacte de votre compte est renvoyée par GET /me (rateLimitPerMinute).

Chaque réponse indique où vous en êtes :

Pour des envois en masse (plusieurs centaines de destinataires), préférez les campagnes du tableau de bord : elles gèrent le rythme d’envoi pour vous.

Idempotence

Un réseau instable peut vous faire perdre une réponse alors que le message est parti. Pour réessayer sans risque de doublon, ajoutez Idempotency-Key à POST /messages :

• même clé + même compte API dans les 24 h → la réponse d’origine est renvoyée, avec l’en-tête Idempotent-Replayed: true, et rien n’est renvoyé à WhatsApp ;
• les réponses 429 et 5xx ne sont pas mémorisées : vous pouvez réessayer avec la même clé ;
• construisez la clé à partir de votre donnée métier : otp-{userId}-{timestamp}, commande-{ref}-expedition…

Envoyer un code de vérification (OTP)

Créez un modèle de catégorie AUTHENTICATION (ex. code_verification : « Votre code est {{1}} »), puis :

const code = String(Math.floor(100000 + Math.random() * 900000));
await saveOtp(user.id, code, { expiresInMinutes: 10 }); // dans VOTRE base

await fetch("https://api.kora-flow.com/api/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KORAFLOW_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `otp-${user.id}-${Date.now()}`,
  },
  body: JSON.stringify({ to: user.phone, templateName: "code_verification", variables: [code] }),
});

Confirmation de commande + facture PDF

1. Créez un modèle UTILITY avec un en-tête Document : « Merci {{1}} ! Voici la facture de votre commande {{2}} ».
2. Générez le PDF sur une URL publique (lien signé valable quelques heures, par exemple).
3. Envoyez le modèle en passant le PDF dans mediaUrl :

{
  "to": "237699112233",
  "templateName": "facture_commande",
  "variables": ["Awa", "A1234"],
  "mediaUrl": "https://exemple.com/factures/A1234.pdf?signature=…"
}

Brancher votre propre chatbot ou CRM

1. Abonnez un webhook à message.received.
2. À chaque message, votre serveur calcule la réponse.
3. Il répond avec un text libre : le client vient d’écrire, la fenêtre de 24 h est ouverte.

async function handleIncoming(data) {
  const answer = await monBot.repondre(data.phoneNumber, data.text);
  await fetch("https://api.kora-flow.com/api/v1/messages", {
    method: "POST",
    headers: { "Authorization": `Bearer ${process.env.KORAFLOW_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ to: data.phoneNumber, text: answer }),
  });
}

Make, Zapier, n8n (sans code)

Dans votre scénario, ajoutez un module HTTP → Make a request (Make), Webhooks by Zapier → Custom Request (Zapier) ou HTTP Request (n8n) :

Remplacez les valeurs entre chevrons par les champs de l’étape précédente (ligne Google Sheets, commande WooCommerce, formulaire…).

• Une clé par application et par environnement (« ERP – production », « Site – test ») avec le minimum de scopes. En cas de fuite, révoquez une seule clé.
• Modèles pour le premier contact, texte libre seulement pour répondre dans les 24 h.
• Toujours une Idempotency-Key sur les envois déclenchés par un événement métier (commande, paiement, OTP).
• Webhooks plutôt que interrogation en boucle pour suivre les statuts et les réponses.
• Gérez le 402 : prévenez l’administrateur du compte quand le quota est atteint au lieu de réessayer en boucle.
• Numéros propres : stockez-les au format international dès la saisie (237…, 225…, 221…).
• Respectez le consentement et proposez toujours un moyen de se désabonner pour les messages marketing.

L’API est versionnée dans l’URL (/api/v1). Dans une même version, nous pouvons ajouter des champs, des routes ou des événements sans préavis : ignorez les champs que vous ne connaissez pas. Tout changement incompatible fera l’objet d’une nouvelle version (/api/v2).