--- title: "API Messaging : envoyer des messages et déclencher des automatisations" description: "Envoyer des messages libres et des templates, lister vos templates, déclencher une automatisation, renommer un contact et lire les informations de votre compte via l'API." url: https://help.getkanal.com/fr-fr/articles/81-api-messaging-envoyer-des-messages-et-declencher-des-automatisations collection: "API" updated: 2026-10-21 language: fr-fr alternates: [en] --- # API Messaging : envoyer des messages et déclencher des automatisations Envoyer des messages libres et des templates, lister vos templates, déclencher une automatisation, renommer un contact et lire les informations de votre compte via l'API. 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](https://help.getkanal.com/fr-fr/articles/14-authentification-et-cles-api.md). ## Message libre ou template ? 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é. ## Envoyer un message libre ```text POST /api/v1/messages/send ``` Le 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. - `.link` : requis pour tous les autres types (URL du média). - `.caption` (optionnel) : légende, acceptée pour les images, les vidéos et les documents. - `document.filename` (optionnel) : nom du fichier affiché au destinataire. ```bash 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`) : ```json { "success": true, "message": "Message sent successfully", "message_id": 123456, "contact_id": 7890, "phone_number": "33612345678" } ``` Pour une image : ```json { "to": "33612345678", "type": "image", "image": { "link": "https://example.com/photo.jpg", "caption": "Légende optionnelle" } } ``` Pour un document : ```json { "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é. ## Envoyer un template ```text POST /api/v1/templates ``` C'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](https://help.getkanal.com/fr-fr/articles/15-envoyer-un-template-whatsapp-via-l-api.md). ## Lister vos templates approuvés ```text GET /api/v1/get_templates ``` Retourne 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. ```json [ { "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. ## Déclencher une automatisation ```text 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. ```bash 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": "marie@example.com", "variables": { "discount_code": "WELCOME10" } }' ```

Code	Message	Signification
`200`	`Incoming webhook triggered`	Le flux a démarré.
`200`	`Contact blocked by re-entry rule`	La règle de réentrée de l'automatisation bloque ce contact : aucun flux ne se lance.
`400`	`Automation is not active`	L'automatisation est désactivée : activez-la.
`400`	`phone_number is required` ou `Invalid phone_number format`	Numéro absent ou invalide.
`400`	`shopify_customer_id must be numeric`	L'identifiant client Shopify n'est pas numérique.
`401`	`Invalid API key`	L'automatisation appartient à un autre numéro WhatsApp que celui de la clé.
`404`	`Incoming webhook not found`	Le `webhook_id` est inconnu.

> **Info:** **À noter :** une réponse `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. ## Renommer un contact ```text 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. ```bash 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" }' ``` > **Info:** Vos intégrations peuvent réécrire ces noms après votre appel. Avec Shopify, chaque nouvelle commande du contact remet le nom affiché, le prénom et le nom à ceux du client Shopify. Avec l'API Commerce, chaque envoi de données remet à jour le prénom et le nom, mais conserve le nom affiché dans l'Inbox. ## Informations du compte ```text POST /api/v1/me ``` Retourne 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. ```json { "display_phone_number": "+33 6 12 34 56 78", "verified_name": "My Shop" } ``` ## Éviter les doublons d'envoi 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. > **Warning:** **Après une erreur, utilisez une nouvelle clé.** Si un premier envoi a échoué (erreur 4xx ou 5xx), un nouvel essai avec la même `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. ## Limites de débit 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.