Gestion des noms d'utilisateur WhatsApp et des BSUID
Ce guide vous explique les modifications que vous devez apporter à votre intégration de la Messages API Vonage afin de prendre en charge les noms d'utilisateur WhatsApp et les BSUID.
Conditions préalables
- Une application Vonage active sur laquelle la fonctionnalité « Messages » est activée
- Un compte WhatsApp Business (WABA) et un numéro de téléphone WhatsApp associés à Meta et Vonage
- Points de terminaison Webhook configurés pour les messages entrants et les rappels d'état
Mettre à jour vos demandes d'envoi de messages
Vous pouvez désormais envoyer des messages en utilisant un BSUID en plus d'un numéro de téléphone, ou à la place de celui-ci. Le to Ce champ accepte désormais soit un numéro de téléphone, soit un BSUID pour les destinataires WhatsApp.
Envoyer uniquement vers un numéro de téléphone (comportement actuel, inchangé) :
À envoyer uniquement à un BSUID :
Important : lorsque vous utilisez un BSUID, veillez à toujours indiquer la valeur complète, c'est-à-dire le préfixe du code pays, le point et tous les caractères alphanumériques. L'omission ou la modification d'une partie quelconque du BSUID entraînera l'échec de la requête.
Gérer la réponse mise à jour à l'envoi d'un message
La réponse à la commande « send message » reste inchangée. Pour plus de détails, consultez la Spécification de l'API « Envoyer un message ».
Mettre à jour votre gestionnaire de rappel de statut (webhook)
Les rappels d'état pour les messages sortants « envoyés », « remis » et « lus » incluent désormais un whatsapp.recipient objet et un profile objet comportant de nouveaux champs.
Mise à jour du contenu de la fonction de rappel de statut :
{
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"status": "read",
"channel": "whatsapp",
"profile": {
"name": "John Smith",
"username": "johnSmith"
},
"usage": { "currency": "EUR", "price": "0" },
"whatsapp": {
"pricing": {
"type": "regular",
"pricing_model": "CBP",
"category": "service"
},
"recipient": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
},
"conversation": {
"id": "1234567890",
"origin": { "type": "marketing" }
}
}
}
Champs nouveaux et modifiés :
| Champ d'application | Description |
|---|---|
profile.username | Le nom d'utilisateur WhatsApp de l'utilisateur, s'il en a choisi un. Cette information n'apparaît pas lorsque le message a été envoyé ou si l'utilisateur n'a pas de nom d'utilisateur. |
whatsapp.recipient.user_id | Le BSUID de l'utilisateur. Toujours présent pour les statuts « livré » et « lu ». |
whatsapp.recipient.parent_user_id | Le BSUID parent de l'utilisateur. Ce champ n'apparaît que si votre entreprise a activé les BSUID parents. |
whatsapp.recipient.wa_id | Le numéro de téléphone de l'utilisateur. Ce champ est omis si le message a été envoyé à un BSUID et que le numéro de téléphone ne peut pas être inclus. |
Pour failed rappels d'état, recipient_user_id est omis si le message a été envoyé à un numéro de téléphone.
Mettre à jour votre gestionnaire de messages entrants (webhook)
Les webhooks pour les messages entrants incluent désormais un whatsapp.sender objet et une version mise à jour profile objet.
Mise à jour du contenu de la fonction de rappel pour les messages entrants :
{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"profile": {
"name": "Jane Smith",
"username": "janeSmith"
},
"message_type": "text",
"text": "Hello from Vonage!",
"whatsapp": {
"sender": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
}
}
}
Les from Ce champ affichera le numéro de téléphone de l'utilisateur s'il est disponible. Si ce n'est pas le cas, le BSUID s'affichera à la place.
Champs nouveaux et modifiés :
| Champ d'application | Description |
|---|---|
profile.username | Le nom d'utilisateur WhatsApp de l'utilisateur, s'il en a choisi un. Cette information est omise si l'utilisateur n'a pas de nom d'utilisateur. |
whatsapp.sender.user_id | Le BSUID de l'utilisateur. Toujours présent. |
whatsapp.sender.parent_user_id | Le BSUID parent de l'utilisateur. Ce champ n'apparaît que si votre entreprise a activé les BSUID parents. |
whatsapp.sender.wa_id | Le numéro de téléphone de l'utilisateur. Ce champ est omis si l'utilisateur a choisi un nom d'utilisateur et que le numéro de téléphone ne peut pas être inclus conformément aux conditions décrites ci-dessus. |
Demander le numéro de téléphone d'un utilisateur (facultatif)
Si votre intégration nécessite le numéro de téléphone d'un utilisateur — par exemple, à des fins d'authentification ou de vérification —, vous pouvez le demander directement dans la conversation. Il existe deux façons de procéder : via un message pré-approuvé modèle de message ou via un message interactif.
Option 1 : Message type avec un bouton permettant de demander les coordonnées
Vous devez d'abord créer et faire valider un modèle WhatsApp comprenant un REQUEST_CONTACT_INFO bouton via le API de gestion des modèles WhatsApp. Une fois approuvé, envoyez le modèle à l'aide de la Messages API :
Option 2 : Message interactif avec un bouton de demande de coordonnées
Vous pouvez également demander un numéro de téléphone au sein d'une fenêtre de conversation active à l'aide d'un message interactif, sans avoir besoin d'un modèle pré-approuvé :