Une fois l'authentification maîtrisée, vous pouvez commencer à intégrer les fonctionnalités de Kanal directement dans vos propres applications ou flux de travail. L'API Kanal est structurée autour des principes REST, utilisant des requêtes HTTP standard et renvoyant des réponses au format JSON.
Tous les points de terminaison (endpoints) de l'API sont accessibles via l'URL racine suivante :
https://api.getkanal.com/v1
Il est impératif d'utiliser cette URL pour toutes vos requêtes. Comme précisé dans le guide d'authentification, seul le protocole HTTPS est accepté.
L'API Kanal communique exclusivement en JSON. Pour chaque requête envoyée (notamment les méthodes POST ou PATCH), vous devez inclure les en-têtes suivants :
Authorization : Bearer <VOTRE_CLE_API>
Content-Type : application/json
L'API permet de piloter les deux piliers de Kanal : la communication (messages) et la base de données (contacts).
C'est l'usage le plus fréquent. Pour envoyer un message à un client en dehors de la fenêtre de 24 heures, vous devez utiliser un template préalablement validé par Meta.
Point de terminaison : POST /messages
Données requises (Body) :
Le numéro de téléphone du destinataire (format international).
Le nom du template.
Le code de la langue (ex : fr, en).
Les variables de personnalisation si le template en contient.
Exemple de structure JSON pour un message avec variable :
{
"to": "33612345678",
"template_name": "confirmation_commande",
"language": "fr",
"variables": ["Jean"]
}
Vous pouvez utiliser l'API pour synchroniser des contacts provenant d'une source externe vers votre base Kanal.
Point de terminaison : POST /contacts
Cette ressource permet d'ajouter un nouveau contact ou de mettre à jour les informations d'un contact existant. C'est l'endroit idéal pour gérer l'état de l'Opt-in de manière programmatique.
Données courantes :
phone : Le numéro de téléphone (identifiant unique).
first_name : Le prénom.
last_name : Le nom de famille.
opt_in : Un booléen (true/false) pour définir le consentement marketing.
L'API permet également d'ajouter des tags à vos contacts pour déclencher des automatisations basées sur des conditions spécifiques.
Point de terminaison : POST /contacts/tags
Cela est particulièrement utile pour marquer un client suite à une action effectuée sur une application tierce, ce qui permettra ensuite à Kanal de l'inclure dans un segment dynamique ou une campagne spécifique.
Afin de garantir la stabilité de la plateforme et de respecter les politiques de Meta concernant WhatsApp, l'API Kanal applique des limites de débit.
Si vous dépassez le nombre de requêtes autorisées par minute, le serveur renverra un code d'erreur HTTP 429 (Too Many Requests). Nous vous recommandons d'implémenter une logique de "retry" avec un délai exponentiel (exponential backoff) dans votre code pour gérer ces situations de manière fluide.
L'API Kanal utilise les codes d'état HTTP standards pour indiquer le succès ou l'échec d'une requête :
200 OK : La requête a réussi.
201 Created : La ressource (contact ou message) a été créée avec succès.
400 Bad Request : La requête est mal formée (paramètres manquants ou invalides).
401 Unauthorized : Problème d'authentification (clé API absente ou invalide).
404 Not Found : La ressource demandée n'existe pas.
500 Internal Server Error : Un problème est survenu sur nos serveurs.
L'API est conçue pour être prévisible et robuste. Pour chaque erreur rencontrée, le corps de la réponse JSON contiendra généralement un message explicatif vous permettant d'identifier la cause du problème.
Si vous développez une intégration complexe et que vous avez des questions spécifiques sur un point de terminaison, n'hésitez pas à solliciter notre support technique via votre canal de communication habituel.