Aller au contenu
34 min read

Se connecter avec la Meta Graph API

Pointez une intégration WhatsApp Cloud API existante vers WizMessage sans la réécrire — les chemins de Meta, les corps de requête de Meta, l’enveloppe d’erreur de Meta, les webhooks au format propre à Meta, et les points de terminaison de gestion de compte pour les modèles, le profil d’entreprise, les codes QR et les flux.

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

La WizMessage API comparée à l’API compatible Meta GraphChoisissez celle qui correspond à ce que vous avez déjàWizMessage API/api/v1/externalvariables de modèle nomméesinterface de mappage dans le tableau de bordchamp reference, consultation du statutnotre propre enveloppe JSONidéal si vous partez de zéroMeta Graph API/v26.0/{phone-number-id}/…corps de requête de Metaenveloppe d’erreur de Metagestion des modèles et du profilwebhooks au format de Metaidéal si vous avez du code Cloud APIMêmes clés, mêmes autorisations, mêmes limites de débit. Utilisez les deux si vous le souhaitez.
Deux surfaces, un seul compte. Aucune ne va disparaître.

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.
  • v26 seul est rejeté. Le numéro mineur n’est pas facultatif. v26.0 convient, v26 est une 404.

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êteValeur
AuthorizationBearer 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 190 et une 401. 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êteValeur
X-Subscription-WarningSubscription 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"
	}
}
Ce qu’il advient de l’accès à l’API après l’expiration d’un abonnementune clé d’APInormalaucun en-têtepériode de grâce7 jours, les appels aboutissent toujoursX-Subscription-Warning sur chaque réponserefusécode 10 à 403premier appel après l’expirationle compte à rebours démarre icifin de la périodeaucun avertissement supplémentaireUn renouvellement à tout moment rétablit l’accès en quelques minutes.
L’expiration en elle-même ne change rien. Le compte à rebours démarre lors de votre prochain appel.

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-Warning est le seul préavis existant — journalisez-le, sinon la première chose que vous apprendrez sera une 403.

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 : to prend 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.164 et rejette tout le reste, tandis que celle-ci transmet directement votre valeur à Meta. La seule exception est POST /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 contacts de 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.

Comment une erreur vous parvient selon que Meta l’a produite ou nonUne erreur sur cette surfaceMeta l’a rejetéetransmise mot pour motcode et sous-code de Metafbtrace_id propre à Metale statut est aussi celui de MetaNous l’avons rejetéeauthentification, permission, limite de débitexprimée avec les codes de Metaafin qu’un seul gestionnaire couvre les deux401 · 403 · 429 · 400 · 500Ne partez jamais du principe que type est OAuthException — Meta en utilise plusieurs.
Les erreurs propres à Meta sont transmises telles quelles. Les nôtres empruntent les codes de Meta.

Erreurs que nous levons

codeHTTPQuand
190401Clé 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.
10403La 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.
4429Le quota de la clé par minute ou quotidien est épuisé.
100400Requête mal formée, identifiant dans le chemin qui ne vous appartient pas, ou point de terminaison non pris en charge par cette surface.
2500Un 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 type dans cet exemple — GraphMethodException, et non OAuthException. Meta utilise plusieurs types d’exceptions et nous ne les normalisons pas. Basez vos branchements sur error.code, qui est numérique et stable ; traitez type comme 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éthodeCheminCe qu’il fait
POST/{version}/{phone-number-id}/mediaTé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}/downloadLes octets.
DELETE/{version}/{media-id}Le supprimer, renvoie {"success": true}.
Téléverser un fichier une seule fois et l’envoyer de façon répétéePOST /{v}/{pnid}/mediale fichier lui-même{ id }réutilisablePOST /{v}/{pnid}/messagesréférencer l’identifiantDistribuéles statuts arrivent par webhook
Le téléversement renvoie un identifiant. Cet identifiant est ce que vous insérez dans un message.

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 :

AppelPermission
POST /{v}/{pnid}/messages avec "type": "template"send_template
identique, type valant image, video, audio, document ou stickersend_media
identique, tout autre cas — texte, interactif, réaction, localisation, contacts et marquer comme lusend_text
POST /{v}/{pnid}/media — téléversementsend_media
DELETE /{v}/{media-id}send_media
GET /{v}/{media-id} et /downloadview_messages

Gestion du compte — voir Gestion du compte :

AppelPermission
GET /{v}/{waba-id}/message_templatesview_templates
POST et DELETE /{v}/{waba-id}/message_templatesmanage_templates
GET /{v}/{waba-id}/template_analyticsview_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 fluxview_templates
POST sur ces six mêmes élémentsmanage_profile
DELETE /{v}/{pnid}/message_qrdls/{code} et DELETE /{v}/{pnid}/block_usersmanage_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_media ici. Sur l’API WizMessage, il ne nécessite aucune permission, en partant du principe que send_media ré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 à renvoyer 403, en voici la raison.

Note : view_templates contrô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 à renvoyer 403 avec 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_profile et view_analytics ne 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.

Les points de terminaison de gestion de compte regroupés selon la permission requise par chacunTout lireles huit ressourcesprofil, codes QR, commerceliste de blocage, paramètres, fluxmodèlesview_templatesÉcrire sur le compteprofil et présenceprofil d’entreprise, codes QRcommerce, liste de blocageparamètres, fluxmanage_profileÉcrire des modèlescréation et suppressionmessage_templatesl’analytique est séparéemanage_templatesL’analytique des modèles a son propre badge : view_analytics.
La lecture correspond à un seul badge. L’écriture se divise selon ce que vous é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ête DELETE est 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_token et appsecret_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ête Authorization, 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 100 décrit dans Quand un identifiant n’est pas le vôtre.

Note : paging.next pointe vers Meta, pas vers nous. Les réponses sont renvoyées exactement telles que Meta les a envoyées, de sorte qu’un lien next dans une réponse paginée est une URL graph.facebook.com — et votre clé d’API ne s’y authentifie pas. Paginez en récupérant paging.cursors.after et 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éthodePermissionRenvoie
GETview_templatesLe { data, paging } de Meta
POSTmanage_templatesLa réponse de création de Meta
DELETEmanage_templatesLa réponse de suppression de Meta

GET accepte limit (1–100, 25 par défaut) et after pour la pagination par curseur.

Note : GET n’accepte que limit et after. 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=APPROVED renvoie un 200 contenant tous les modèles, qu’ils soient approuvés ou non. Filtrez de votre côté, ou utilisez after pour 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 cela whatsapp_calling_settings — ce chemin n’existe pas chez Meta et renvoie ici le code 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.

Pourquoi un point de terminaison peut ne pas être disponible sur cette surfaceun point de terminaison qui n’est pas iciNous le refusonsregistration, subscribed_appscela bloquerait votre compteaucune solution de contournementMeta le refusepas sur un numéro en coexistenceconversational_automation, callsla propre réponse de MetaIl n’existe pasquatre chemins issus de miroirs d’APIMeta répond code 2500utiliser le vrai cheminUn quatrième groupe ne figure tout simplement pas encore sur notre liste — voir ci-dessous.
Quatre raisons, et une seule vient de nous.

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 :

CheminPourquoi
register, deregister, request_code, verify_codeUn 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_appsToutes 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_messagesLes envois marketing passent par les outils de campagne du tableau de bord, qui appliquent le débit d’envoi par compte.
/{template-id}/unpauseMeta 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 POSTLe 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 :

CheminRéponse de Meta
/{phone-number-id}/conversational_automationcode 100 — « Tried accessing nonexisting field »
/{phone-number-id}/callscode 100 — « Tried accessing nonexisting field »
/{phone-number-id}/groupscode 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 lireCe qu’il faut utiliser à la place
POST /{phone-number-id}/mark_message_as_readPOST /{phone-number-id}/messages avec un corps status: "read" — voir Marquer un message comme lu
GET /{phone-number-id}/message_statusLes 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_componentsRien — 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.

L’onglet Webhooks avec le format de charge utile défini sur WizMessage, montrant les cases à cocher des événements v1

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.

L’onglet Webhooks au format Meta Graph, montrant le jeton de vérification et les neuf noms de champs Meta auxquels s’abonner

Avant de pouvoir en enregistrer un

Trois éléments sont requis, et le tableau de bord vous indiquera lequel est manquant :

Ce qui doit être en place avant de pouvoir enregistrer un webhook Meta GraphSecret de webhooksert de clé à la signatureJeton de vérificationprouve que l’URL est la vôtreUne URL activenous l’appelons avant d’enregistrerEnregistréles distributions commencentUne URL qui ne répond pas encore ne peut pas être enregistrée. Déployez d’abord, configurez ensuite.
Les trois éléments sont vérifiés lorsque vous cliquez sur enregistrer, dans cet ordre.
  • 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êteValeur
X-Hub-Signature-256sha256= + HMAC-SHA256 du corps brut, avec votre secret de webhook pour clé, hexadécimal en minuscules.
X-Webhook-Eventmeta.<field> — le champ que transporte cette distribution.
X-Webhook-IdIdentifiant unique de cette tentative de distribution. Dédupliquez dessus.
User-Agentfacebookplatform/1.0 (+http://developers.facebook.com)

Remarque : Ce n’est pas le même calcul que pour le format WizMessage. Celui-ci signe timestamp + "." + rawBody et 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.

ChampCe qui arrive
messagesMessages entrants et statuts de distribution. Lisez la remarque ci-dessous.
message_statusStatuts de distribution, en tant que champ dédié.
smb_message_echoesMessages envoyés par l’entreprise depuis l’application WhatsApp Business sur son téléphone.
smb_app_state_syncModifications du carnet d’adresses effectuées sur ce téléphone.
user_id_updateL’identité WhatsApp d’un contact a changé.
message_template_status_updateUn modèle a été approuvé, rejeté ou mis en pause.
message_template_quality_updateLa note de qualité d’un modèle a évolué.
account_updateLe compte WhatsApp a été connecté, déconnecté, restreint ou retiré.
historyConversations 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 : messages transporte déjà les statuts de distribution. Meta envoie les deux sous "field": "messages" — les messages entrants dans un tableau messages, les rapports de distribution dans un tableau statuses sur le même objet de valeur. L’abonnement par défaut suffit donc à faire la corrélation avec le wamid que vous avez obtenu après un envoi. message_status est un champ supplémentaire, pas celui dont vous avez besoin pour le suivi des statuts de base. Lisez value.statuses avant 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.

Trois comportements qui diffèrent entre les deux formats de webhookAucun filtre chatbotdistribué dans les deux casla v1 exige le mode bot = WebhookGraph ignore ce paramètreVous recevez « sent »et les statuts de campagnela v1 filtre les deuxGraph transmet toutPas de « sent » synthétiqueles événements propres à Meta à la placesmb_message_echoeset les statutsAttendez-vous à plus de trafic sur le format Graph que ce que le même compte produisait sur la v1.
Tous trois font que le format Graph distribue plus, et non moins.
  • 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.sent synthé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 avec smb_message_echoes et le statut sent, 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.

La boîte de dialogue Test API en mode Meta Graph, montrant le point de terminaison messages en lecture seule et un corps de requête au format Meta

« 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.