API Cloud

Plateforme WhatsApp Business > API Cloud

Présentation

L’API Cloud, hébergée par Meta, permet aux moyennes et grandes entreprises de communiquer avec leur clientèle à grande échelle. Au moyen de cette API, les entreprises créent des systèmes qui connectent des milliers de personnes à des agents ou des bots, permettant ainsi une communication aussi bien manuelle qu’automatique. En outre, les entreprises peuvent intégrer l’API à de nombreux systèmes back-end, comme les plateformes CRM et marketing.

Protocole HTTP

L’API Cloud étant basée sur l’API Graph, les requêtes sont exprimées à l’aide du protocole HTTP et de combinaisons de paramètres d’URL, d’en-têtes et de corps de requêtes. Voici un exemple d’appel couramment envoyé à l’API Cloud à partir d’une ligne de commande sous UNIX :

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Si vous ne maîtrisez pas l’API Graph, consultez notre documentation de l’API Graph pour en apprendre les bases. Les principales différences entre l’API Graph et l’API Cloud sont les types de tokens d’accès que vous utiliserez couramment, les autorisations des ressources, la syntaxe des requêtes et la syntaxe des webhooks. Ces différences sont décrites dans les sections correspondantes de la documentation de l’API Cloud.

Ressources

Voici les principales ressources avec lesquelles vous allez interagir en utilisant l’API.

Portefeuille business

Pour utiliser l’API, vous devez avoir un portefeuille business. Si vous n’avez pas de portefeuille, vous serez invité·e à en créer un au cours de notre processus de démarrage. Les portefeuilles business servent de conteneur pour votre compte WhatsApp Business et vos numéros de téléphone professionnels.

Pour en savoir plus sur les portefeuilles business, consultez notre article À propos des portefeuilles business dans Meta Business Suite des pages d’aide.

Comptes WhatsApp Business

Un compte WhatsApp Business représente une entreprise sur la plateforme WhatsApp Business et comprend principalement des métadonnées sur une entreprise spécifique. La plupart des autres ressources de WhatsApp, telles que les numéros de téléphone professionnels WhatsApp et les modèles de messages WhatsApp, sont associées à un compte WhatsApp Business.

Pour créer un compte WhatsApp Business, suivez les étapes de notre document Premiers pas. Pour en savoir plus sur les comptes WhatsApp Business et leurs limitations, consultez la page Comptes WhatsApp Business.

Numéros de téléphone WhatsApp Business

Un numéro de téléphone WhatsApp Business (numéro de téléphone professionnel) représente un numéro de téléphone réel, qui, une fois enregistré pour fonctionner avec l’API Cloud, peut être utilisé pour échanger des messages avec des utilisateurs et utilisatrices de WhatsApp via l’API.

Les numéros de téléphone professionnels sont principalement composés de métadonnées concernant le numéro en question et votre entreprise. Ces métadonnées peuvent être affichées dans le client WhatsApp lorsque les utilisateurs et utilisatrices interagissent avec votre numéro de téléphone professionnel.

Pour créer un numéro de téléphone professionnel, suivez les étapes de notre document Premiers pas. Notez que les numéros de téléphone professionnels font l’objet de limites et restrictions, qui sont décrites en détail dans notre document Numéros de téléphone professionnels.

Modèles de messages WhatsApp

Les modèles de messages WhatsApp sont des modèles personnalisables que vous pouvez créer via l’API en utilisant divers composants dédiés. Après leur création, ils sont automatiquement examinés, et s’ils sont ensuite approuvés, ils peuvent être utilisés dans des messages basés sur des modèles.

L’API permet d’envoyer deux grands types de messages : les messages libres et les messages basés sur des modèles. Ces derniers sont les plus restreints, car ils nécessitent l’approbation des modèles de messages WhatsApp. Toutefois, comme les modèles doivent être examinés et approuvés avant d’être utilisés, les messages basés sur des modèles suscitent généralement moins de commentaires négatifs de leurs destinataires, lesquels pourraient compromettre votre capacité à envoyer des messages à votre clientèle.

Pour en savoir plus sur les modèles, consultez notre document Modèles.

Webhooks

Les webhooks sont simplement des charges utiles JSON envoyées à l’aide du protocole HTTP vers un point de terminaison public sur votre serveur. L’API Cloud dépend fortement des webhooks, car c’est sous cette forme que seront envoyés le contenu des messages des utilisateurs et utilisatrices de WhatsApp adressés à votre numéro de téléphone professionnel, ainsi que toutes les mises à jour du statut de distribution des messages sortants.

Notez que vous pouvez tester cette fonctionnalité en clonant notre exemple d’application webhook sur Glitch. L’application transfère simplement les charges utiles des webhooks vers une console pour que vous puissiez les consulter. À terme, vous devrez créer votre propre point de terminaison sur votre propre serveur, afin d’intégrer les webhooks à votre logique commerciale.

Pour en savoir plus sur les webhooks et leur gestion, consultez la page Webhooks Meta et notre document Webhooks pour les comptes WhatsApp Business.

Ressources de test

Lorsque vous aurez terminé les étapes de notre document Premiers pas, vous recevrez automatiquement un compte WhatsApp Business et un numéro de téléphone professionnel de test.

Grâce à ces ressources de test, vous pourrez contourner la plupart des limitations de messagerie et n’aurez pas besoin de renseigner un moyen de paiement pour envoyer des messages basés sur des modèles.

Vous pouvez supprimer votre portefeuille business et ses ressources de test dans les cas suivants :

  • Vous êtes admin du portefeuille business associé à l’application.
  • Aucune autre application n’est associée au portefeuille business.
  • Le portefeuille business n’est associé à aucun autre compte WhatsApp Business.
  • Le compte WhatsApp Business n’est associé à aucun autre numéro de téléphone professionnel.

Pour supprimer votre portefeuille business et ses ressources de test :

  1. Dans Espace App, cliquez sur WhatsApp > panneau Configuration.
  2. Repérez la section Compte de test.
  3. Cliquez sur le bouton Supprimer.

Authentification et autorisation

Tokens d’accès

L’API prend en charge trois types de tokens :

  • Tokens d’accès utilisateur·ice système
  • Tokens d’accès utilisateur·ice du système d’intégration professionnelle
  • Tokens d’accès utilisateur·ice

Consultez la page Tokens d’accès pour déterminer quel type de token vous devez utiliser. Notez que les tokens doivent être intégrés aux en-têtes de requête, et non dans les paramètres des chaînes de requête.

Autorisations

L’API repose sur les autorisations suivantes de l’API Graph. La combinaison exacte d’autorisations nécessaires pour votre application dépend des points de terminaison auxquels votre application devra accéder.

  • business_management : requise en cas d’interaction avec un portefeuille business.
  • whatsapp_business_management : requise en cas d’interaction avec un compte WhatsApp Business et ses fonctionnalités d’analyse, ou ses modèles ou numéros de téléphone professionnels.
  • whatsapp_business_messaging : requise en cas d’échange de messages avec des utilisateurs et utilisatrices de WhatsApp.

Ces autorisations sont généralement accordées lors de la génération de tokens d’accès dans Meta Business Suite. Consultez les sections sur la génération de tokens dans notre document Tokens d’accès.

Gestion des versions

La gestion des versions utilise le protocole de gestion des versions de l’API Graph. Cela signifie que toutes les requêtes de points de terminaison peuvent inclure un numéro de version, et chaque version sera disponible pendant environ 2 ans avant d’être retirée et ne pourra plus être appelée.

Débit

Pour chaque numéro de téléphone professionnel enregistré, l’API Cloud prend en charge jusqu’à 80 messages par seconde (mps) par défaut, et jusqu’à 1 000 mps par mise à niveau automatique.

Le débit inclut les messages entrants et sortants, ainsi que tous les types de messages. Notez que les numéros de téléphone professionnels, tous débits confondus, restent soumis au plafond de débit des cas d’utilisation en entreprise et aux limites d’envoi de messages basés sur un modèle associés à leur compte WhatsApp Business.

Si vous tentez d’envoyer des messages au-delà de votre plafond actuel, l’API renvoie le code d’erreur 130429 tant que vous n’avez pas atteint le niveau autorisé. De plus, les niveaux de débit sont destinés aux campagnes de messagerie impliquant différents numéros de téléphone de personnes utilisant WhatsApp. Si vous tentez d’envoyer un trop grand nombre de messages au même numéro d’utilisateur·ice WhatsApp, vous rencontrerez une erreur de plafond par paire.

Débit accru

Si vous remplissez nos conditions d’éligibilité, nous mettrons automatiquement à niveau votre numéro de téléphone professionnel vers 1 000 mps, et ce gratuitement. Le débit accru n’engendre pas de frais supplémentaires et n’a pas d’incidence sur les tarifs.

Le processus de mise à niveau peut prendre jusqu’à 1 minute. Pendant ce temps, le numéro n’est pas utilisable sur notre plateforme. S’il est utilisé dans une requête d’API, l’API renvoie le code d’erreur 131057. Une fois qu’un numéro de téléphone professionnel a été mis à niveau, il bénéficie automatiquement des augmentations de débit ultérieures sans temps d’inactivité.

Conditions d’éligibilité

Webhooks

Vos serveurs de webhooks doivent être en mesure de traiter trois fois le trafic de messages sortants et une fois le trafic attendu de messages entrants. Par exemple, si vous envoyez 1 000 mps avec un taux de réponse attendu de 30 %, vos serveurs doivent pouvoir traiter jusqu’à 3 000 webhooks de statut de message, plus 300 webhooks de message entrant supplémentaires.

Nous tentons de livrer les webhooks simultanément, nous vous recommandons de configurer votre serveur de webhooks et de charger des tests sur celui-ci pour traiter les requêtes simultanées selon les normes de latence suivantes :

  • La latence médiane ne doit pas dépasser 250 ms.
  • La part des latences supérieures à 1 s ne doit pas dépasser 1 %.

Si la livraison d’un webhook échoue, nous essayons de le redistribuer pendant une durée maximale de 7 jours, avec un délai d’attente exponentiel.

Messages multimédias

Pour tirer pleinement parti de ce débit accru, nous vous recommandons d’importer vos éléments de contenu multimédia sur nos serveurs et d’utiliser les ID de contenu multimédia renvoyés correspondant dans les messages multimédias, plutôt que d’héberger ces éléments sur vos propres serveurs et d’utiliser les URL associées. Si vous préférez (ou devez) héberger ces éléments sur vos propres serveurs, nous vous recommandons d’utiliser la mise en cache du contenu multimédia.

Déterminer le débit

Utilisez le point de terminaison numéro de téléphone WhatsApp Business afin de déterminer le débit actuel pour un numéro de téléphone spécifique :

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migration

Si vous migrez un numéro de téléphone professionnel multiconnecté à deux partitions ou plus de l’API On-Premises vers l’API Cloud, il passera automatiquement à un débit plus élevé.

Plafonds

Consultez les plafonds de l’API WhatsApp Business Management.

Hormis ces plafonds, des limites plus spécifiques s’appliquent aux ressources individuelles, comme les messages basés sur des modèles et les numéros de téléphone professionnels de test :

Indicateurs disponibles

En tant qu’utilisateur·ice de l’API Cloud, vous pouvez voir le nombre de messages envoyés et distribués, ainsi que d’autres indicateurs. Pour en savoir plus, consultez la page Obtenir des indicateurs sur un compte.

Évolution

Au sein de l’infrastructure de Meta, l’API Cloud évolue et s’adapte automatiquement à votre charge de travail, dans les limites fixées (volume de messagerie et nombre de comptes WhatsApp Business).

Confidentialité des données et sécurité

Pour plus d’informations, consultez la section Présentation des règles de confidentialité et de sécurité.

Chiffrement

Avec l’API Cloud, tous les messages WhatsApp continuent d’être protégés par le protocole de chiffrement Signal, qui permet de sécuriser les messages avant qu’ils ne quittent l'appareil. Cela signifie qu’avec un compte WhatsApp Business, les messages sont livrés en toute sécurité à la destination choisie par chaque entreprise.

L’API Cloud utilise les techniques de chiffrement standard du marché pour protéger les données en transit et au repos. L’API utilise l’API Graph pour envoyer des messages, et les webhooks pour recevoir des évènements ; tous deux fonctionnent sur le protocole HTTPS standard, protégé par TLS. Pour en savoir plus, consultez notre livre blanc sur le chiffrement.

Pour en savoir plus, consultez notre livre blanc sur le chiffrement.

Plafonds par paire

Les numéros de téléphone professionnels ne peuvent pas envoyer plus d’un message toutes les 6 secondes au même numéro de téléphone d’utilisateur·ice WhatsApp (soit 0,17 message par seconde). Cela équivaut à environ 10 messages par minute ou 600 messages par heure. Si vous dépassez ce plafond, l’API renvoie le code d’erreur 131056 tant que vous ne repassez pas en dessous.

Si besoin, vous pouvez envoyer en rafale jusqu’à 45 messages dans cet intervalle de 6 secondes. Dans ce cas, vous prenez une avance sur votre plafond par paire et il vous sera impossible d’envoyer d’autres messages au numéro concerné pendant une certaine période correspondant au temps qu’il vous aurait fallu pour envoyer « normalement » le même nombre de messages. Par exemple, il faut environ 2 minutes pour envoyer « normalement » 20 messages à un utilisateur ou une utilisatrice. Donc, si vous les envoyez en rafale, vous devrez attendre 2 minutes avant de pouvoir envoyer d’autres messages au même numéro.

Pour éviter d’avoir à calculer les temps d’attente post-rafale, en cas d’échec d’envoi d’un message consécutif à une rafale, nous vous recommandons de réessayer 4^X secondes plus tard, où X = 0 et augmente de 1 à chaque échec d’envoi, jusqu’à ce que la requête réussisse.

Outils

Gestionnaire WhatsApp

Notre application web Gestionnaire WhatsApp vous permet de gérer manuellement les ressources WhatsApp comme les comptes WhatsApp Business, les numéros de téléphone professionnels et les modèles, et d’accéder facilement aux insights, indices de qualité et plafonds de ces ressources. Les fonctionnalités du Gestionnaire WhatsApp sont presque toutes disponibles via l’API, à quelques exceptions mineures près.

Voici différentes méthodes permettant d’accéder au Gestionnaire WhatsApp. Chacune d’elles suppose que vous avez déjà suivi toutes les étapes de notre document Démarrer.

Via Meta Business Suite

  1. Connectez-vous à Meta Business Suite.
  2. Si vous avez plusieurs portefeuilles business, ouvrez le menu déroulant situé à gauche pour sélectionner le compte qui possède le compte WhatsApp Business (ou qui a accès à ce dernier) que vous souhaitez charger dans le Gestionnaire WhatsApp.
  3. Dans le menu de gauche, accédez à Comptes > Comptes WhatsApp.
  4. Sélectionnez le compte WhatsApp Business.
  5. Dans l’onglet Récapitulatif, puis cliquez sur le bouton Gestionnaire WhatsApp.

Via l’Espace App

  1. Accédez à Mes applications.
  2. Sélectionnez l’application associée au compte WhatsApp Business que vous souhaitez charger dans le Gestionnaire WhatsApp.
  3. Dans le menu de gauche, sélectionnez WhatsApp > Démarrage rapide.
  4. Cliquez sur la vignette Informations du compte dans la section WhatsApp Business.

Via une URL

Vous pouvez accéder directement à la vue d’ensemble du Gestionnaire WhatsApp, qui affiche tous les comptes WhatsApp Business qui sont détenus par ou partagés avec un portefeuille business donné, sur cette page :

https://business.facebook.com/wa/manage/home/

Par défaut, la vue d’ensemble charge le dernier compte business Meta que vous avez créé ou auquel on vous a donné accès, mais vous pouvez utiliser le menu déroulant de gauche pour sélectionner le portefeuille business auquel vous tentez d’accéder. Cette action vous fera cependant sortir de la vue d’ensemble et vous devrez alors utiliser le menu de gauche pour accéder à Comptes > Comptes WhatsApp > (sélectionner le compte WhatsApp Business voulu) > Paramètres > (bouton) Gestionnaire WhatsApp.

Si vous avez plusieurs portefeuilles business, vous pouvez aussi coller l’ID d’un compte à la fin de l’URL, puis ajouter cette dernière à vos favoris pour pouvoir ensuite y accéder directement :

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

Nous avons créé une collection Postman contenant des requêtes courantes de l’API Cloud dans notre espace de travail de la plateforme WhatsApp Business.