L’API publique WhatsApp d'Aircall permet aux développeurs et aux outils externes (HubSpot, Salesforce et scripts personnalisés) d’envoyer des messages WhatsApp par programmation au nom de votre entreprise, sans qu’un agent les envoie manuellement depuis Aircall Workspace. Cet article explique qui peut utiliser l’API, comment enregistrer une ligne et à quoi sert chaque endpoint.

Qui peut utiliser l’API publique WhatsApp

Les quatre conditions suivantes doivent toutes être remplies pour que l’API fonctionne pour votre entreprise :

  • Forfait Aircall Professional : les comptes Essentials ne sont pas éligibles et renverront une erreur 403.
  • Module complémentaire WhatsApp : au moins une licence active de module complémentaire WhatsApp sur le compte.
  • Disponibilité de la fonctionnalité : elle est activée automatiquement pour les clients éligibles et ne nécessite aucune action, sauf si elle a été désactivée. Si vous pensez qu’elle a été désactivée, contactez l’assistance Aircall.
  • Enregistrement de la ligne : la ligne WhatsApp doit être enregistrée pour une utilisation avec l’API publique via l’endpoint de configuration avant que tout envoi soit possible.
Important: Toutes les conditions doivent être remplies. S’il en manque une seule, l’API ne fonctionnera pas pour cette entreprise.

Les deux modes d’envoi

Lors de l’envoi d’un message WhatsApp via l’API, vous choisissez entre deux modes.

  • Envoi proxy : le message est envoyé au nom du développeur et n’apparaît pas dans la boîte de réception de l’agent. Les mises à jour de livraison et les réponses entrantes sont envoyées à l’callbackUrl que vous avez enregistrée.
  • Envoi natif : le message est envoyé et apparaît dans la conversation Workspace de l’agent. L’agent peut voir et poursuivre la conversation depuis Aircall.
Remarque: Les deux modes d’envoi s’excluent mutuellement. L’envoi proxy nécessite que la ligne soit enregistrée pour une utilisation avec l’API publique via l’endpoint de configuration. L’envoi natif nécessite qu’elle ne soit pas enregistrée.

Les quatre endpoints de l’API

Enregistrer une ligne pour une utilisation avec l’API publique

POST /v1/numbers/{id}/messages/configuration

Enregistrez une ligne WhatsApp et fournissez une callbackUrl : l’URL à laquelle Aircall enverra les mises à jour de livraison et les réponses entrantes. Cette étape doit être effectuée avant que tout envoi de message soit possible.

Important: Si l’API ne fonctionne pas, la première chose à vérifier est si la ligne a été enregistrée via cet endpoint. Sans enregistrement, toutes les tentatives d’envoi renverront une erreur.

Vérifier l’état de la ligne

GET /v1/numbers/{id}/whatsapp_status

Renvoie l’état actuel d’une ligne WhatsApp. Appelez cet endpoint avant l’envoi pour confirmer que la ligne est dans un état sain. La réponse comprend :

  • Statut : si la ligne est ONLINE, OFFLINE ou NOT_REGISTERED
  • canSendMessage : si la ligne peut actuellement envoyer (AVAILABLE, LIMITED ou BLOCKED)
  • qualityRating : le signal de Meta concernant l’engagement des destinataires (GREEN, YELLOW ou RED)
  • messagingLimitTier : le nombre maximal de conversations initiées par l’entreprise que la ligne peut démarrer par période de 24 heures (TIER_250, TIER_1K, TIER_10K ou TIER_100K)

Envoyer un message

POST /v1/messages/whatsapp/send

POST /v1/messages/send/whatsapp/native

Envoie un message WhatsApp par programmation. Deux types de messages sont pris en charge :

  • Modèles approuvés : peuvent être envoyés à tout moment, pendant ou en dehors de la fenêtre de conversation de 24 heures
  • Texte libre : ne peut être envoyé que pendant une fenêtre de conversation ouverte de 24 heures

Consultez « La fenêtre de conversation de 24 heures » ci-dessous pour plus de détails sur le moment où chaque type s’applique.

Lister les modèles disponibles

GET /v1/numbers/{id}/templates

Renvoie tous les modèles de messages WhatsApp pour une ligne, y compris leur statut d’approbation (APPROVED, PENDING, REJECTED, PAUSED ou DISABLED) et la structure des variables pour chaque modèle. Utilisez cet endpoint pour confirmer quels modèles sont disponibles avant l’envoi.

Configuration de l’API publique WhatsApp

Étapes :

  1. Confirmez que votre compte est sur le forfait Pro et dispose d’au moins une licence active de module complémentaire WhatsApp.
  2. Appelez POST /v1/numbers/{id}/messages/configuration avec l’ID de votre ligne WhatsApp et votre callbackUrl pour enregistrer la ligne.
  3. Appelez GET /v1/numbers/{id}/whatsapp_status pour confirmer que la ligne est ONLINE et que canSendMessage affiche AVAILABLE.
  4. Appelez GET /v1/numbers/{id}/templates pour récupérer vos modèles approuvés.
  5. Envoyez votre premier message à l’aide de POST /v1/messages/whatsapp/send.
Conseil: Vérifiez toujours l’état de la ligne avant l’envoi, en particulier dans les workflows automatisés. L’état d’une ligne peut changer en fonction du quality rating et des règles de Meta. Intégrer une vérification du statut avant l’envoi dans votre intégration évite les échecs d’envoi.

La fenêtre de conversation de 24 heures

La règle de fenêtre de conversation de Meta contrôle quand les messages texte libres peuvent être envoyés :

  • Lorsqu’un client envoie un message à votre numéro, ou répond à l’un de vos messages, une fenêtre de 24 heures s’ouvre.
  • Pendant cette fenêtre, vous pouvez envoyer des messages texte libres.
  • Une fois la fenêtre fermée (aucune réponse du client dans les 24 heures), seuls des modèles approuvés peuvent être envoyés pour reprendre contact.
Remarque: L’envoi de texte libre en dehors d’une fenêtre ouverte renvoie une réponse 200, mais votre Webhook enregistré recevra un callback contenant une erreur 63016. Utilisez un modèle approuvé pour rouvrir la conversation. Aircall ne peut pas contourner ni prolonger la fenêtre.

Référence API

Pour les schémas complets des requêtes et des réponses, les détails d’authentification et des exemples de code, consultez la documentation développeur d'Aircall.