L'API Messaging regroupe les endpoints qui envoient des messages WhatsApp, déclenchent des automatisations, renomment vos contacts et lisent les informations de votre compte. Elle nécessite un abonnement actif : sans cela, chaque appel retourne 403 Team has no active subscription.
Ces endpoints ne prennent pas de store_id : votre clé API est rattachée à un numéro WhatsApp, qui est le numéro d'envoi. Voir Authentification et clés API.
WhatsApp n'autorise les messages libres que dans une fenêtre de service ouverte de 24 heures, c'est-à-dire lorsque le contact vous a écrit dans les 24 dernières heures. Pour contacter quelqu'un en premier, vous devez obligatoirement passer par un template approuvé.
POST /api/v1/messages/sendLe format suit la logique de Meta : un champ type, puis un objet portant le nom de ce type.
to (requis) : le numéro du destinataire, indicatif pays inclus.
type (requis) : text, image, video, audio ou document.
text.body : requis pour le type texte.
<type>.link : requis pour tous les autres types (URL du média).
<type>.caption (optionnel) : légende, acceptée pour les images, les vidéos et les documents.
document.filename (optionnel) : nom du fichier affiché au destinataire.
curl -X POST https://api.getkanal.com/api/v1/messages/send \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{
"to": "33612345678",
"type": "text",
"text": { "body": "Bonjour depuis l API !" }
}'Réponse en cas de succès (200) :
{
"success": true,
"message": "Message sent successfully",
"message_id": 123456,
"contact_id": 7890,
"phone_number": "33612345678"
}Pour une image :
{
"to": "33612345678",
"type": "image",
"image": {
"link": "https://example.com/photo.jpg",
"caption": "Légende optionnelle"
}
}Pour un document :
{
"to": "33612345678",
"type": "document",
"document": {
"link": "https://example.com/facture.pdf",
"caption": "Votre facture",
"filename": "facture-10456.pdf"
}
}L'erreur la plus fréquente sur cet endpoint est Cannot send free-form message: no active conversation window. Elle signifie que la fenêtre de 24 heures est fermée : utilisez un template. Les autres cas sont un numéro invalide, un contact désinscrit, ou un type de message mal renseigné.
POST /api/v1/templatesC'est la seule façon de contacter un client en premier. Le média d'en-tête (image, vidéo ou document) vient toujours du template : il ne se passe pas dans la requête. Le détail des paramètres et du format des variables est dans Envoyer un template WhatsApp via l'API.
GET /api/v1/get_templatesRetourne un tableau de vos templates au statut APPROVED pour le numéro rattaché à la clé, y compris ceux créés dans une automatisation ou une campagne. Aucun paramètre, seul l'en-tête Authorization est nécessaire.
[
{
"id": 1234,
"phone_number_id": 56,
"name": "order_confirmation",
"wa_status": "APPROVED",
"structure": "{ ...JSON: header/body/buttons... }",
"created_at": "2026-01-10T12:00:00.000000Z"
}
]Le champ id est le template_id à utiliser pour l'envoi. Le champ structure est une chaîne JSON décrivant le header, le corps et les boutons : les noms de variables qu'elle contient sont exactement les clés à passer dans l'objet variables lors de l'envoi.
POST /api/v1/automations/{webhook_id}Lance une automatisation dont le déclencheur est un Webhook entrant. Le webhook_id est l'UUID de ce nœud. Dans l'éditeur d'automatisation, le nœud Webhook entrant affiche l'URL de destination complète et un bouton Copier en cURL. L'automatisation doit être active et appartenir au numéro WhatsApp de la clé.
Champs acceptés à la racine du JSON :
phone_number (requis) : le numéro du contact. Si aucun contact n'existe pour ce numéro, il est créé.
variables (optionnel) : un objet clé/valeur injecté dans les variables de session de l'automatisation.
name, first_name, last_name (optionnels) : l'identité du contact.
email (optionnel) : ajouté seulement si le contact n'a pas encore d'e-mail.
shopify_customer_id (optionnel) : doit être numérique, rattache le contact à un client Shopify.
curl -X POST https://api.getkanal.com/api/v1/automations/3f9c1a2b-4d5e-6789-abcd-ef0123456789 \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+33612345678",
"first_name": "Marie",
"email": "[email protected]",
"variables": { "discount_code": "WELCOME10" }
}'Code | Message | Signification |
|---|---|---|
|
| Le flux a démarré. |
|
| La règle de réentrée de l'automatisation bloque ce contact : aucun flux ne se lance. |
|
| L'automatisation est désactivée : activez-la. |
|
| Numéro absent ou invalide. |
|
| L'identifiant client Shopify n'est pas numérique. |
|
| L'automatisation appartient à un autre numéro WhatsApp que celui de la clé. |
|
| Le |
200 ne garantit pas que le flux a démarré : vérifiez le champ message. Cet endpoint utilise un format { "message": ... } et non { "error": ... }.Les anciennes URL de la forme https://api.getkanal.com/v1/automations/{webhook_id} (sans /api) restent acceptées pour les intégrations existantes. Utilisez /api/v1/ pour toute nouvelle intégration.
PATCH /api/v1/contacts/{phone}Disponible depuis le 08/10/2026. Cet endpoint modifie le nom d'un contact existant de votre numéro. Il ne crée jamais de contact : un numéro inconnu retourne 404 Contact not found.
{phone} : le numéro du contact, indicatif pays inclus, avec ou sans + (par exemple 33612345678).
name : le nom affiché dans l'Inbox. Il ne modifie ni first_name ni last_name.
first_name : le prénom, utilisé par les variables de personnalisation des templates et des automatisations. Si vous envoyez first_name sans name, le nom affiché dans l'Inbox est aussi modifié.
last_name : le nom de famille.
Envoyez au moins un de ces trois champs, sinon l'API retourne une erreur 422. Seuls les champs envoyés sont modifiés.
curl -X PATCH https://api.getkanal.com/api/v1/contacts/33612345678 \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{ "name": "140 - Jean Dupont" }'POST /api/v1/meRetourne le numéro WhatsApp Business rattaché à la clé. Aucun corps de requête. C'est l'appel le plus rapide pour vérifier qu'une clé fonctionne et confirmer depuis quel numéro elle envoie.
{
"display_phone_number": "+33 6 12 34 56 78",
"verified_name": "My Shop"
}Les endpoints /messages/send et /templates acceptent un en-tête optionnel Idempotency-Key. Rejouer une requête avec la même clé ne renvoie pas le message : l'API retourne un 201 avec le message Message already sent with this idempotency key. Utilisez une valeur unique, par exemple un UUID par message : une clé déjà connue de Kanal est traitée comme un doublon.
Idempotency-Key répond « déjà envoyé » sans rien envoyer. Générez une nouvelle Idempotency-Key pour chaque nouvel essai après une erreur.Seul POST /api/v1/templates est limité à 60 requêtes par minute par clé API. Au-delà, l'API retourne une erreur 429 avec retry_after: 60. Les autres endpoints de l'API Messaging ne sont soumis qu'à la limite globale de l'API : 3 000 requêtes par minute par adresse IP.