Se connecter avec la Meta Graph API
Il existe deux façons d’envoyer des messages WhatsApp via WizMessage. La WizMessage API est celle vers laquelle vous tourner si vous partez de zéro — elle vous offre des variables de modèle nommées, une interface de mappage et un champ reference sur lequel indexer vos propres enregistrements.
Cette page documente l’autre solution. Elle reproduit la WhatsApp Cloud API de Meta assez fidèlement pour que le code déjà écrit pour Meta fonctionne ici après avoir changé deux choses : l’URL de base et le jeton. Mêmes chemins, mêmes corps de requête, mêmes corps de réponse, même enveloppe d’erreur. Si vous avez une intégration existante, une bibliothèque ou un développeur qui connaît déjà la Cloud API, c’est le chemin le plus court.
Ce n’est pas seulement une surface d’envoi. Aux côtés de la messagerie, elle prend en charge les points de terminaison de gestion de compte — création et suppression de modèles, lecture et réécriture du profil d’entreprise, codes QR, paramètres commerciaux, liste de blocage, paramètres du téléphone et flux — tous sur les propres chemins de Meta. Gérer le compte est le catalogue, et Ce qui n’est pas disponible ici est l’autre moitié, tout aussi importante.
Les deux surfaces utilisent les mêmes clés d’API, les mêmes autorisations et les mêmes limites de débit. Rien n’est déprécié — choisissez par intégration, et vous pouvez utiliser les deux à la fois.
Laquelle choisir
Les bases
URL de base, et la version dans le chemin
https://wizmessage.com/v26.0/{phone-number-id}/messages
Le segment de version est réel et obligatoire, mais sa valeur ne change rien. Nous le faisons correspondre au format v{major}.{minor} puis nous l’ignorons — la plateforme décide de la version de Graph avec laquelle elle communique en amont.
Deux conséquences utiles à connaître :
- Figer une ancienne version continue de fonctionner. Lorsque Meta retire la version codée en dur dans votre code, les appels effectués ici continuent de fonctionner. Rien à planifier.
v26seul est rejeté. Le numéro mineur n’est pas facultatif.v26.0convient,v26est une404.
L’identifiant {phone-number-id} doit être le numéro WhatsApp associé à la clé d’API que vous utilisez. Tout le reste est refusé — voir Quand un identifiant n’est pas le vôtre.
Authentification
Envoyez votre clé d’API sous forme de jeton bearer, exactement comme vous enverriez un jeton d’accès à Meta.
| En-tête | Valeur |
|---|---|
Authorization | Bearer pk_live_… — votre clé d’API complète, pas le préfixe affiché dans le tableau de bord. |
X-API-Key est également accepté ici, de sorte qu’une clé fonctionnant déjà avec l’API WizMessage n’a besoin d’aucun changement d’en-tête. Bearer est la forme à privilégier : c’est ce qu’envoie un SDK Meta non modifié, ce qui est précisément l’intérêt de cette surface.
Note : « Require signature » doit être désactivé sur la clé. Ce n’est pas une question de préférence ici. Une clé sur laquelle cette option est activée ne peut pas enregistrer de webhook Meta Graph — le tableau de bord refuse avec « Signed-request enforcement is not compatible with the Graph format — disable it on this key first » — et chaque appel non signé qu’elle effectue sur cette surface est rejeté avec le
code 190et une401. Un client Cloud API prêt à l’emploi ne peut pas générer notre signature de requête, les deux sont donc mutuellement exclusifs par conception.
Votre abonnement
Le module API nécessite un abonnement actif Wiz Bot ou Wiz Pro. Cela s’applique aux deux surfaces — l’API WizMessage et celle-ci — et c’est vérifié à chaque appel, pas seulement lors de la création de la clé.
Si l’abonnement expire, l’API ne s’arrête pas à cet instant. Le premier appel après l’expiration démarre une fenêtre de sept jours et est autorisé à passer, et chaque réponse durant cette fenêtre comporte un en-tête :
| En-tête | Valeur |
|---|---|
X-Subscription-Warning | Subscription inactive. API access ends in 5 day(s). |
Une fois cette période écoulée, les appels sont refusés avec le code 10 de Graph et une 403 :
{
"error": {
"message": "(#10) Access denied. The API module requires an active Wiz Bot or Wiz Pro subscription. Renew at /subscriptions to restore access.",
"type": "OAuthException",
"code": 10,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
Trois détails qui déterminent si vous vous en apercevrez à temps :
- Le compte à rebours démarre lors de votre premier appel, pas à la date de facturation. Une clé qui reste inactive pendant deux semaines après une expiration bénéficie toujours de ses sept jours complets, débutant dès qu’elle effectue son appel suivant.
- La période s’applique par clé d’API, pas par compte. Chaque clé gère son propre compte à rebours à partir de son propre premier appel, de sorte qu’une clé utilisée pour vos tests et une clé en production expireront à des dates différentes. Vérifiez l’en-tête sur la clé qui compte.
- Le refus survient sans avertissement sur la requête qui le déclenche.
X-Subscription-Warningest le seul préavis existant — journalisez-le, sinon la première chose que vous apprendrez sera une403.
Note : Le renouvellement prend quelques minutes pour prendre effet, pas des secondes. La réponse relative aux droits est mise en cache pendant cinq minutes et l’état de l’abonnement sous-jacent pendant cinq autres minutes, de sorte qu’un renouvellement effectué alors qu’une intégration est en échec ne débloquera pas la situation dès la tentative suivante. Attendez quelques minutes avant de conclure que cela n’a pas fonctionné.
Envoyer un message
POST /{version}/{phone-number-id}/messages, avec le corps de Meta. Nous ne le validons pas au-delà de la vérification qu’il s’agit bien d’un message WhatsApp — Meta fait autorité sur ce à quoi ressemble un message valide, et ses erreurs sont bien meilleures que tout ce que nous pourrions inventer.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "text",
"text": { "preview_url": false, "body": "Your order has shipped." }
}
Note :
toprend uniquement des chiffres bruts ici —919876543210, sans+. C’est le format de Meta, et c’est l’erreur la plus fréquente lors du passage d’une surface à l’autre : l’API WizMessage exige+E.164et rejette tout le reste, tandis que celle-ci transmet directement votre valeur à Meta. La seule exception estPOST /messages/contacts, qui accepte l’une ou l’autre forme précisément pour qu’un corps Graph soit transposé tel quel.
L’envoi d’un modèle adopte également le format de Meta — des composants positionnels, pas des variables nommées. Il n’y a aucune couche de mappage sur cette surface, ce qui est le compromis consenti pour la compatibilité.
{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_failed_alert",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Priya Sharma" },
{ "type": "text", "text": "12 Aug 2026" },
{ "type": "text", "text": "Wiz Pro" }
]
}
]
}
}
Envoyer une fiche de contact
type: "contacts" est une vCard — un nom, et tout ce que vous y joignez par ailleurs. Cela a toujours fonctionné sur cette surface et fonctionne toujours, avec le corps de Meta inchangé.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "Priya Sharma",
"first_name": "Priya",
"last_name": "Sharma"
},
"phones": [
{ "phone": "+911122334455", "type": "WORK", "wa_id": "911122334455" }
],
"emails": [
{ "email": "[email protected]", "type": "WORK" }
],
"org": { "company": "Acme Retail", "department": "Support", "title": "Account Manager" }
}
]
}
name.formatted_name est le seul champ exigé par WhatsApp. phones[].wa_id est celui qui mérite d’être ajouté quoi qu’il en soit : grâce à lui, la fiche comporte un bouton Message qui ouvre une discussion avec cette personne, sans lui, la fiche peut seulement être enregistrée.
Ce corps exact s’envoie également à POST /messages/contacts sur l’API WizMessage — clés d’enveloppe, to en chiffres bruts et tout le reste. C’est le seul point de terminaison sur cette surface qui accepte ce format, et il existe parce que les deux éléments que ce chemin ne peut pas vous fournir valent la peine d’être obtenus : un envoi ici n’est pas enregistré sous un message_id, il n’y a donc aucun statut à consulter et aucun webhook message.sent auquel le faire correspondre, et le corps n’est que très peu vérifié avant d’atteindre Meta. Changer l’URL constitue l’intégralité de la migration.
Note : L’envoi de plusieurs fiches dans un seul message repose sur le tableau
contactsde Meta, et Meta en accepte jusqu’à 257. Le point de terminaison de WizMessage le plafonne à dix — un envoi groupé de fiches qui fonctionne ici est donc l’un des rares corps qui ne sera pas transposé tel quel.
Marquer un message comme lu
Les confirmations de lecture et les indicateurs de saisie sont envoyés au même point de terminaison, avec un corps qui ne comporte ni to ni type. La méthode markAsRead() de chaque SDK Cloud API dépend de ce fonctionnement, il est donc pris en charge exactement comme Meta le spécifie.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…"
}
La réponse est {"success": true} — et non l’enveloppe d’envoi ci-dessous. Faites un branchement selon l’appel que vous avez effectué plutôt que d’essayer de lire messages[0].id sur chaque réponse.
Ce qui est renvoyé
La réponse de Meta, inchangée :
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…" }]
}
Ce wamid est votre unique moyen d’identifier le message. Cette surface ne comporte délibérément aucun champ reference et aucun point de terminaison de recherche de statut — tous deux sont des ajouts de WizMessage que l’API de Meta ne possède pas, leur inclusion romprait donc la compatibilité qui justifie l’existence même de cette surface.
Pour suivre le sort d’un message, faites correspondre le wamid aux statuts de distribution qui arrivent sur votre webhook. Si vous préférez disposer de votre propre champ sur lequel vous baser, c’est précisément à cela que sert le champ reference de l’API WizMessage.
Erreurs
Les erreurs reviennent dans l’enveloppe de Meta, jamais dans la nôtre. L’origine de l’erreur détermine la part qui nous revient.
Erreurs que nous levons
code | HTTP | Quand |
|---|---|---|
190 | 401 | Clé manquante, inconnue, révoquée, suspendue ou expirée — ou appel non signé avec une clé qui exige des signatures. Également levée lorsque le compte WhatsApp lui-même a perdu sa connexion à Meta ; voir la note ci-dessous. |
10 | 403 | La clé ne dispose pas de la permission requise par cet appel (voir Permissions), ou l’abonnement du compte a expiré au-delà de sa période de grâce. |
4 | 429 | Le quota de la clé par minute ou quotidien est épuisé. |
100 | 400 | Requête mal formée, identifiant dans le chemin qui ne vous appartient pas, ou point de terminaison non pris en charge par cette surface. |
2 | 500 | Un problème est survenu de notre côté. Réessayez. |
Note : Deux situations distinctes renvoient
190, et elles nécessitent des solutions opposées. Si le message mentionne la clé, effectuez une rotation de la clé ou saisissez-la à nouveau. S’il indique "the connection to this WhatsApp Business Account needs to be renewed", la clé fonctionne parfaitement et c’est le compte qui a perdu sa liaison avec Meta — reconnectez-le depuis le tableau de bord. Effectuer la rotation d’une clé fonctionnelle en réponse à ce second cas fait perdre un après-midi et ne change rien.
Erreurs que Meta lève
Transmises exactement telles qu’elles sont reçues, avec le statut HTTP de Meta. Tout ce que Meta a envoyé est conservé — error_subcode, error_data.details et le propre fbtrace_id de Meta :
{
"error": {
"message": "Unsupported post request. Object with ID '106540352242922' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
"code": 100,
"type": "GraphMethodException",
"error_subcode": 33,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
Note : Notez le
typedans cet exemple —GraphMethodException, et nonOAuthException. Meta utilise plusieurs types d’exceptions et nous ne les normalisons pas. Basez vos branchements surerror.code, qui est numérique et stable ; traiteztypecomme un libellé destiné aux humains.
Quand un identifiant ne vous appartient pas
Chaque identifiant dans le chemin — l’identifiant du numéro de téléphone, l’identifiant WABA, un identifiant de média — est vérifié par rapport au compte associé à votre clé avant toute autre opération. Une discordance renvoie le code 100 formulé de la même façon que Meta formule un objet que vous ne pouvez pas voir :
Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.
Cette formulation est délibérée de la part de Meta et copiée délibérément ici : un identifiant qui existe mais appartient à quelqu’un d’autre et un identifiant qui n’existe pas du tout doivent être indiscernables, sinon l’erreur deviendrait un moyen de découvrir les numéros de téléphone d’autres personnes.
Médias
Quatre points de terminaison, correspondant à ceux de Meta.
| Méthode | Chemin | Ce qu’il fait |
|---|---|---|
POST | /{version}/{phone-number-id}/media | Téléverser un fichier. Multipart, renvoie {"id": "…"}. |
GET | /{version}/{media-id} | L’objet de métadonnées de Meta pour le fichier. |
GET | /{version}/{media-id}/download | Les octets. |
DELETE | /{version}/{media-id} | Le supprimer, renvoie {"success": true}. |
La seule différence délibérée
GET /{version}/{media-id} renvoie l’objet de métadonnées de Meta — messaging_product, mime_type, sha256, file_size, id — mais url pointe vers nous, et non vers l’hôte lookaside de Meta.
C’est indispensable. L’URL du média de Meta ne peut être récupérée qu’avec le jeton d’entreprise du compte WhatsApp, qui réside de notre côté et ne le quitte jamais. Nous vous transmettons donc une URL que vous pouvez récupérer : le point de terminaison de téléchargement ci-dessus, sur le même hôte et segment de version que vous avez appelés, authentifié avec le même jeton bearer que vous avez déjà envoyé.
Les clients traitent cette URL comme opaque et effectuent simplement un GET dessus avec leur jeton, raison pour laquelle un SDK non modifié ne s’en aperçoit pas. Si votre code applique un traitement particulier au nom d’hôte, c’est le seul endroit où il devra être modifié.
Permissions
Les mêmes pastilles de permission que l’API WizMessage, sur les mêmes clés. L’endroit d’où est lue la permission dépend de l’appel : le point de terminaison d’envoi la déduit du corps de la requête, car Meta regroupe tous les types de messages sous un chemin unique ; partout ailleurs, elle provient du chemin et de la méthode.
Envoi et médias :
| Appel | Permission |
|---|---|
POST /{v}/{pnid}/messages avec "type": "template" | send_template |
identique, type valant image, video, audio, document ou sticker | send_media |
| identique, tout autre cas — texte, interactif, réaction, localisation, contacts et marquer comme lu | send_text |
POST /{v}/{pnid}/media — téléversement | send_media |
DELETE /{v}/{media-id} | send_media |
GET /{v}/{media-id} et /download | view_messages |
Gestion du compte — voir Gestion du compte :
| Appel | Permission |
|---|---|
GET /{v}/{waba-id}/message_templates | view_templates |
POST et DELETE /{v}/{waba-id}/message_templates | manage_templates |
GET /{v}/{waba-id}/template_analytics | view_analytics |
GET sur le profil d’entreprise, les codes QR, les paramètres commerciaux, la liste de blocage, les paramètres du téléphone et les flux | view_templates |
POST sur ces six mêmes éléments | manage_profile |
DELETE /{v}/{pnid}/message_qrdls/{code} et DELETE /{v}/{pnid}/block_users | manage_profile |
Ce sont les deux seules requêtes DELETE du côté de la gestion. Il n’y a pas de suppression sur le profil d’entreprise, les paramètres commerciaux, les paramètres du téléphone ou les flux — un appel DELETE sur l’un d’entre eux est refusé avec le code 100, de la même manière qu’un point de terminaison qui n’existe pas.
Note : Le téléversement de médias nécessite
send_mediaici. Sur l’API WizMessage, il ne nécessite aucune permission, en partant du principe quesend_mediarégit l’envoi d’un fichier à un client plutôt que son dépôt sur les serveurs de Meta. Cette surface adopte une approche plus stricte. Si vous migrez une clé et que les téléversements commencent à renvoyer403, en voici la raison.
Note :
view_templatescontrôle bien plus que les modèles. La lecture du profil d’entreprise, des codes QR, des paramètres commerciaux, de la liste de blocage, des paramètres du téléphone et des flux se trouve entièrement derrière cette permission. Son nom est historique — il est antérieur à tout ce qui figure dans le deuxième tableau. Décochez-la en restreignant une clé et six opérations de lecture sans rapport se mettront à renvoyer403avec un message mentionnant les modèles, ce qui ne constitue pas un indice très utile.
Note : Trois pastilles sont réservées à Meta Graph.
manage_templates,manage_profileetview_analyticsne contrôlent rien sur l’API WizMessage — elles existent pour les points de terminaison de cette page. Toutes les trois ont été accordées à chaque clé déjà existante, de sorte que rien de ce qui fonctionnait ne s’est interrompu ; restreindre les droits implique de décocher délibérément ces options sur le formulaire de modification de la clé.
Un refus correspond au code 10 de Graph avec un statut 403 — jamais à notre PERMISSION_DENIED. Un seul gestionnaire d’erreurs couvre entièrement cette surface.
La propriété est vérifiée avant la permission. Si l’identifiant présent dans le chemin n’est pas celui associé à votre clé, la réponse est le code 100 et elle ne révèle jamais quelle permission vous manquait — sinon l’erreur elle-même deviendrait un moyen de sonder les comptes d’autrui.
Gérer le compte
Au-delà de l’envoi, cette surface relaie les points de terminaison de gestion de compte de Meta sur les propres chemins de Meta. Huit ressources, et la permission dont vous avez besoin varie selon que vous lisez ou écrivez.
Trois choses sont vraies pour chaque point de terminaison de cette section, et elles sont la raison même pour laquelle elle peut exister :
- Le corps de la requête est celui de Meta, transmis inchangé et non validé. Nous ne redocumentons pas les corps de Meta ici et nous ne les vérifions pas. La référence de Meta constitue la spécification, et c’est l’erreur de Meta qui est renvoyée si vous vous trompez — ce qui est une bien meilleure erreur que tout ce que nous pourrions inventer.
- Un corps n’est envoyé que sur
POST. Un corps joint à une requêteDELETEest supprimé avant que la requête ne parte de chez nous. La suppression de modèle chez Meta prend?name=ou?hsm_id=comme paramètres de requête, et non un corps, elle fonctionne donc comme documenté ; tout autre appel attendant un corps de suppression ne fonctionnera pas. - Votre chaîne de requête est transmise, à l’exception de
access_tokenetappsecret_proof. Ces deux éléments sont retirés, car Meta privilégie un jeton passé dans la chaîne de requête par rapport à l’en-têteAuthorization, et les laisser passer rendrait votre bearer optionnel. Un client qui s’authentifie par la chaîne de requête verra celle-ci discrètement ignorée — utilisez l’en-tête.
Note : L’ID WABA et l’ID de numéro de téléphone dans ces chemins doivent être ceux associés à votre clé. Cela est vérifié avant que quoi que ce soit ne quitte notre réseau, et une discordance renvoie le même
code 100décrit dans Quand un identifiant n’est pas le vôtre.
Note :
paging.nextpointe vers Meta, pas vers nous. Les réponses sont renvoyées exactement telles que Meta les a envoyées, de sorte qu’un liennextdans une réponse paginée est une URLgraph.facebook.com— et votre clé d’API ne s’y authentifie pas. Paginez en récupérantpaging.cursors.afteret en réémettant la requête sur cet hôte avec?after=.
Modèles
GET https://wizmessage.com/v26.0/{waba-id}/message_templates?limit=25
POST https://wizmessage.com/v26.0/{waba-id}/message_templates
DELETE https://wizmessage.com/v26.0/{waba-id}/message_templates?name=order_shipped
| Méthode | Permission | Renvoie |
|---|---|---|
GET | view_templates | Le { data, paging } de Meta |
POST | manage_templates | La réponse de création de Meta |
DELETE | manage_templates | La réponse de suppression de Meta |
GET accepte limit (1–100, 25 par défaut) et after pour la pagination par curseur.
Note :
GETn’accepte quelimitetafter. Les autres filtres de Meta sur cette arête —name,status,fields,language,category,name_or_content— sont silencieusement ignorés, et non rejetés. Une requête pour?status=APPROVEDrenvoie un200contenant tous les modèles, qu’ils soient approuvés ou non. Filtrez de votre côté, ou utilisezafterpour paginer la liste complète. C’est le seul endroit sur cette page où un client migré reçoit une mauvaise réponse plutôt qu’une erreur, il convient donc de vérifier votre code à ce sujet.
Analytique des modèles
GET https://wizmessage.com/v26.0/{waba-id}/template_analytics
Nécessite view_analytics. Meta exige start et renvoie le code 100 — « (#100) The parameter start is required » — en son absence. granularity et les autres paramètres sont ceux de Meta ; transmettez-les et ils arrivent inchangés.
Profil d’entreprise
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile
GET nécessite view_templates et renvoie le { data } de Meta. POST nécessite manage_profile.
Codes QR
GET https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
POST https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
DELETE https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls/{code}
GET nécessite view_templates et renvoie le { data } de Meta. POST et DELETE nécessitent manage_profile.
Le chemin /{code} est DELETE uniquement. Il n’y a pas de GET ni de POST sur un code individuel — lisez la collection et faites votre choix dedans.
Paramètres de commerce
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
GET nécessite view_templates et renvoie le { data } de Meta. POST nécessite manage_profile.
Clients bloqués
GET https://wizmessage.com/v26.0/{phone-number-id}/block_users
POST https://wizmessage.com/v26.0/{phone-number-id}/block_users
DELETE https://wizmessage.com/v26.0/{phone-number-id}/block_users
GET nécessite view_templates et renvoie le { data } de Meta. POST et DELETE nécessitent manage_profile. Notez que le déblocage s’effectue par un DELETE sur la collection elle-même, et non sur un chemin par client.
Paramètres du numéro de téléphone
GET https://wizmessage.com/v26.0/{phone-number-id}/settings
POST https://wizmessage.com/v26.0/{phone-number-id}/settings
GET nécessite view_templates et renvoie { calling, storage_configuration }. POST nécessite manage_profile.
Note : Le chemin est
/settings. Certaines documentations d’API tierces appellent celawhatsapp_calling_settings— ce chemin n’existe pas chez Meta et renvoie ici lecode 2500, car nous le transmettons et Meta le rejette. Voir Ce qui n’est pas disponible ici.
Flux
GET https://wizmessage.com/v26.0/{waba-id}/flows
POST https://wizmessage.com/v26.0/{waba-id}/flows
GET nécessite view_templates et renvoie le { data, paging } de Meta. POST nécessite manage_profile.
Ce qui n’est pas disponible ici
Tout ce qui précède a été confirmé sur un compte WhatsApp réel. Tout ce qui suit également — c’est pourquoi cette section peut vous expliquer pourquoi un point de terminaison est manquant, et c’est généralement ce qui détermine ce que vous devez faire ensuite.
Ce que renvoie un point de terminaison non disponible. Tout ce qui ne figure pas sur la liste ci-dessus répond avec la formulation propre à Meta pour un chemin qu’elle ne dessert pas — code 100 à 400 :
Unsupported get request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.
Un chemin qui est pris en charge mais appelé avec une méthode qu’il ne propose pas renvoie le même code avec un message plus court : « Unsupported delete request. » Les deux sont délibérément impossibles à distinguer d’un objet que vous ne pouvez tout simplement pas voir — une erreur confirmant quels points de terminaison existent permettrait de cartographier la surface.
Refusés délibérément
Ceux-ci sont bloqués sur toutes les méthodes, avant que quoi que ce soit ne soit transmis :
| Chemin | Pourquoi |
|---|---|
register, deregister, request_code, verify_code | Un numéro en coexistence ne doit jamais être enregistré sur la Cloud API. C’est précisément ainsi qu’un compte finit par échouer à chaque envoi avec l’erreur 133010, et ce n’est pas réversible de votre côté. |
subscribed_apps | Toutes les méthodes, y compris GET. Un DELETE ici désabonnerait nos webhooks de votre propre compte WhatsApp et romprait silencieusement votre propre intégration ; nous ne proposons pas non plus la lecture, plutôt que de laisser un chemin où un faux pas provoquerait cela. |
marketing_messages | Les envois marketing passent par les outils de campagne du tableau de bord, qui appliquent le débit d’envoi par compte. |
/{template-id}/unpause | Meta identifie le modèle par un simple identifiant sans compte dans le chemin, nous ne pouvons donc pas prouver que le modèle vous appartient avant d’agir dessus. Réactivez-le depuis le tableau de bord. |
messages sur toute méthode sauf POST | Le chemin d’envoi porte le limiteur de débit et la gestion de la suspension de compte. Seul POST est acheminé. |
Non disponible sur un numéro en coexistence
Les propres réponses de Meta, vérifiées sur un compte réel le 10 août 2026 :
| Chemin | Réponse de Meta |
|---|---|
/{phone-number-id}/conversational_automation | code 100 — « Tried accessing nonexisting field » |
/{phone-number-id}/calls | code 100 — « Tried accessing nonexisting field » |
/{phone-number-id}/groups | code 131000 avec une 500 |
Il s’agit de restrictions imposées par Meta sur les numéros fonctionnant en coexistence avec l’application WhatsApp Business, et non des nôtres — nous transmettons la requête et voici ce qui revient. Meta élargit la disponibilité de temps à autre ; si l’un d’entre eux compte pour vous, il est donc préférable de retester plutôt que de vous fier indéfiniment à ce tableau.
Chemins qui n’existent nulle part
Chacun d’entre eux apparaît dans des documentations d’API tierces et n’est pas un point de terminaison Meta. Tous les quatre renvoient le code 2500, « Unknown path components » :
| Ce que vous avez pu lire | Ce qu’il faut utiliser à la place |
|---|---|
POST /{phone-number-id}/mark_message_as_read | POST /{phone-number-id}/messages avec un corps status: "read" — voir Marquer un message comme lu |
GET /{phone-number-id}/message_status | Les statuts de distribution arrivent sur votre webhook ; voir Choisir ce que vous recevez |
/{phone-number-id}/whatsapp_calling_settings | /{phone-number-id}/settings |
/{phone-number-id}/conversational_components | Rien — le chemin réel le plus proche est conversational_automation, qui n’est pas disponible sur un numéro en coexistence |
Réel chez Meta, absent de notre liste
GET /{waba-id}/phone_numbers fonctionne chez Meta et n’est ni bloqué ni transféré ici, il répond donc avec le code 100. C’est l’un des premiers points de terminaison qu’un client Cloud API appelle, il convient donc de le mentionner : votre clé est déjà rattachée à exactement un numéro de téléphone, et son identifiant est celui que vous indiquez dans chaque chemin de cette page. Vous pouvez le lire dans l’onglet « Overview » de la clé sur le tableau de bord.
Lectures de nœuds seuls
GET /{v}/{waba-id}?fields=… et GET /{v}/{phone-number-id}?fields=… fonctionnent chez Meta mais pas ici. Un chemin à segment unique sur cette surface est un identifiant de média — c’est ce que signifie GET /{v}/{media-id} — par conséquent, un identifiant WABA à cet emplacement est recherché en tant que média et échoue.
L’échec est déroutant si vous ne vous y attendez pas : il vérifie d’abord view_messages, de sorte qu’une clé sans cette autorisation reçoit une 403 mentionnant une autorisation qui n’a rien à voir avec ce qui a été demandé. Utilisez plutôt les formes d’arête — /{waba-id}/message_templates, /{phone-number-id}/settings, et le reste de Gérer le compte.
Webhooks au format Meta
L’onglet des webhooks du tableau de bord s’ouvre sur un format de charge utile. WizMessage (v1) est la charge utile documentée sur l’autre page ; c’est ce qu’une clé utilise tant que vous ne la modifiez pas.

Choisissez Meta Graph et votre point de terminaison cessera de recevoir notre charge utile {version, event, timestamp, data} pour commencer à recevoir l’enveloppe que Meta nous a envoyée, transmise telle quelle — une distribution par modification.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"time": 1770000123,
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [{ "profile": { "name": "Priya Sharma" }, "wa_id": "919876543210" }],
"messages": [
{
"from": "919876543210",
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg…",
"timestamp": "1770000123",
"type": "text",
"text": { "body": "Has it shipped yet?" }
}
]
},
"field": "messages"
}
]
}
]
}
Si vous disposez déjà d’un gestionnaire de webhook Cloud API, c’est exactement la structure pour laquelle il a été conçu.
Changer de format modifie également ce que l’onglet vous demande : les cases à cocher des événements sont remplacées par les noms de champs propres à Meta, et un jeton de vérification apparaît.

Avant de pouvoir en enregistrer un
Trois éléments sont requis, et le tableau de bord vous indiquera lequel est manquant :
- Un secret de webhook. C’est la seule clé servant à calculer
X-Hub-Signature-256; sans lui, une distribution ne serait pas signée et serait invérifiable. Générez-en un dans l’onglet Webhooks de la clé. - Un jeton de vérification. La chaîne de caractères de votre choix ; votre point de terminaison doit également la connaître.
- Une URL qui répond déjà. Voir ci-dessous.
Le handshake de vérification
Lorsque vous enregistrez, nous appelons votre URL exactement comme le ferait Meta :
GET https://your-server.example/webhooks
?hub.mode=subscribe
&hub.verify_token=<the token you set>
&hub.challenge=482910337
Votre point de terminaison doit vérifier que hub.verify_token correspond à ce que vous avez configuré, puis renvoyer un code 200 avec hub.challenge comme corps de réponse complet — sans encapsulation JSON, sans guillemets, rien d’autre. Le challenge est un nombre à 9 chiffres, de sorte qu’un gestionnaire qui effectue un parseInt avant de le renvoyer le transmet sans modification.
Si le challenge n’est pas renvoyé à l’identique, l’enregistrement est refusé et rien n’est sauvegardé. C’est ce qui empêche quiconque de pointer notre file d’attente de distribution vers une URL qu’il ne contrôle pas.
// express
app.get('/webhooks', (req, res) => {
if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === VERIFY_TOKEN) {
return res.status(200).send(req.query['hub.challenge'])
}
res.sendStatus(403)
})
Vérifier la signature
Chaque distribution comporte X-Hub-Signature-256, calculé comme le calcule Meta : HMAC-SHA256 du corps brut de la requête, avec votre secret de webhook pour clé, en hexadécimal, préfixé par sha256=.
| En-tête | Valeur |
|---|---|
X-Hub-Signature-256 | sha256= + HMAC-SHA256 du corps brut, avec votre secret de webhook pour clé, hexadécimal en minuscules. |
X-Webhook-Event | meta.<field> — le champ que transporte cette distribution. |
X-Webhook-Id | Identifiant unique de cette tentative de distribution. Dédupliquez dessus. |
User-Agent | facebookplatform/1.0 (+http://developers.facebook.com) |
Remarque : Ce n’est pas le même calcul que pour le format WizMessage. Celui-ci signe
timestamp + "." + rawBodyet envoie l’horodatage dans son propre en-tête ; celui-là signe le corps seul, sans horodatage nulle part. Si vous utilisez les deux formats sur un même serveur, séparez bien les deux vérificateurs — un vérificateur partagé échouera sur celui pour lequel il n’a pas été conçu.
Signez les octets bruts tels qu’ils sont reçus. L’analyse du JSON et sa resérialisation modifient l’ordre des clés et les espacements, et la signature ne correspondra jamais.
const crypto = require('node:crypto')
// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
const provided = req.get('X-Hub-Signature-256') || ''
if (!provided.startsWith('sha256=')) return false
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body) // the raw Buffer, not a parsed object
.digest('hex')
// Constant-time compare — a plain === leaks timing information.
const a = Buffer.from(expected, 'hex')
const b = Buffer.from(provided.slice('sha256='.length), 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
Choisir ce que vous recevez
Le format WizMessage vous fait cocher des événements. Celui-ci vous fait cocher les noms de champs de Meta, qui correspondent à ce à quoi vous vous abonneriez dans l’App Dashboard de Meta.
| Champ | Ce qui arrive |
|---|---|
messages | Messages entrants et statuts de distribution. Lisez la remarque ci-dessous. |
message_status | Statuts de distribution, en tant que champ dédié. |
smb_message_echoes | Messages envoyés par l’entreprise depuis l’application WhatsApp Business sur son téléphone. |
smb_app_state_sync | Modifications du carnet d’adresses effectuées sur ce téléphone. |
user_id_update | L’identité WhatsApp d’un contact a changé. |
message_template_status_update | Un modèle a été approuvé, rejeté ou mis en pause. |
message_template_quality_update | La note de qualité d’un modèle a évolué. |
account_update | Le compte WhatsApp a été connecté, déconnecté, restreint ou retiré. |
history | Conversations passées, pendant la synchronisation initiale. Charges utiles volumineuses — ne vous y abonnez que si vous les souhaitez. |
Les nouveaux webhooks Graph commencent par être abonnés à messages uniquement. Décocher tous les champs désactive les distributions sans supprimer la configuration.
Remarque :
messagestransporte déjà les statuts de distribution. Meta envoie les deux sous"field": "messages"— les messages entrants dans un tableaumessages, les rapports de distribution dans un tableaustatusessur le même objet de valeur. L’abonnement par défaut suffit donc à faire la corrélation avec lewamidque vous avez obtenu après un envoi.message_statusest un champ supplémentaire, pas celui dont vous avez besoin pour le suivi des statuts de base. Lisezvalue.statusesavant de supposer qu’il vous manque un abonnement.
Trois différences par rapport au format WizMessage
À lire si vous migrez une intégration, car chacune d’elles modifie discrètement ce qui arrive.
- La distribution n’est pas conditionnée par le système de chatbot. Avec le format WizMessage, les messages entrants n’atteignent votre point de terminaison que lorsque le système de chatbot du compte est réglé sur Webhook. Le format Graph ignore totalement ce paramètre — configurer une URL et s’abonner à un champ constitue toute la démarche d’activation.
- Vous recevez
status: "sent"et les statuts de campagne. Le format WizMessage ignore délibérément les deux. Ici, vous recevez ce que Meta a envoyé, ce qui signifie un trafic de statuts nettement plus important sur un compte diffusant des campagnes de masse. - Il n’y a aucun
message.sentsynthétique. Le format WizMessage en fabrique un pour les messages envoyés depuis l’API, le tableau de bord ou le téléphone. Meta couvre le même périmètre avecsmb_message_echoeset le statutsent, rien n’est donc inventé ici.
Distribution, nouvelles tentatives et désactivation
Identique au format WizMessage — le même tableau s’applique. En résumé : nous attendons 10 secondes, ne suivons jamais les redirections, réessayons les erreurs 5xx/408/429/timeouts cinq fois avec un intervalle croissant, ne réessayons jamais les autres erreurs 4xx, et traitons 410 Gone comme « désactiver ce webhook ».
Les distributions se font au moins une fois. Dédupliquez sur X-Webhook-Id, et répondez rapidement par un code 2xx.
Tester sans écrire de code
La boîte de dialogue Test API de la clé dispose d’une commande API Format. Définissez-la sur Meta Graph et le sélecteur de point de terminaison est remplacé par la cible réelle de votre compte — POST /v26.0/{your phone number id}/messages — avec un corps au format Meta prérempli.

« Simulate Only » renvoie la requête sans contacter Meta ; passer à « Send Real Message » l’envoie et vous montre la réponse réelle de Meta, enveloppe d’erreur comprise.
La boîte de dialogue cible POST /{phone-number-id}/messages et rien d’autre, les points de terminaison de gestion du compte ne sont donc pas accessibles depuis celle-ci — essayez-les avec curl ou votre propre client.
Get code comporte le même contrôle, de sorte que l’extrait généré cible la surface que vous choisissez, dans l’un des huit langages. Laissez « Require signature » désactivé sur une clé que vous prévoyez d’utiliser ici — s’il est activé, l’extrait Graph généré signe également la requête, la seule chose qu’un client Cloud API non modifié ne peut pas faire.