Gestion des noms d'utilisateur WhatsApp Business
Meta WhatsApp permet aux entreprises d'adopter un nom d'utilisateur facultatif et unique, associé à un numéro de téléphone WhatsApp Business spécifique. Lorsqu'un nom d'utilisateur est actif, il s'affiche dans l'application WhatsApp de l'utilisateur à côté (ou à la place) du numéro de téléphone, ce qui renforce la visibilité de votre marque dans les conversations.
Vonage met cette fonctionnalité à disposition via l'API Channel Manager afin que vous puissiez gérer les noms d'utilisateur par programmation.
Remarque : les noms d'utilisateur professionnels constituent un outil de promotion de la marque et non une fonctionnalité de confidentialité. Le numéro de téléphone de votre entreprise reste visible dans l'application WhatsApp même après avoir choisi un nom d'utilisateur.
Fonctionnement des identifiants professionnels
Un nom d'utilisateur professionnel correspond à un rapport biunivoque : chaque nom d'utilisateur est associé à un seul et même numéro de téléphone WhatsApp Business. Vonage n'enregistre un nom d'utilisateur dans sa base de données qu'après confirmation par Meta que ce nom d'utilisateur est actif (via un webhook).
Lorsque vous récupérez un numéro à l'aide des points de terminaison « List Numbers » ou « Get Number », le username Ce champ n'apparaît dans la réponse que s'il existe un nom d'utilisateur actif associé à ce numéro. Si aucun nom d'utilisateur actif n'est défini, le champ est entièrement omis (il n'est pas renvoyé sous la forme null).
Valeurs d'état du nom d'utilisateur
| Statut | Description |
|---|---|
approved |
Le nom d'utilisateur est validé et visible par les utilisateurs de WhatsApp. La fonctionnalité est désormais disponible. |
reserved |
Le nom d'utilisateur est réservé mais n'est pas encore visible. Cette fonctionnalité n'est pas encore disponible dans la région de l'utilisateur. |
Règles relatives au format des noms d'utilisateur
Les noms d'utilisateur doivent respecter les consignes de mise en forme de Meta. Avant de proposer un nom d'utilisateur, assurez-vous qu'il répond à l'ensemble des critères suivants :
- Longueur : 3 à 35 caractères
- Caractères autorisés : lettres anglaises (a-z, A-Z), chiffres (0-9), point (.) et trait de soulignement (_)
- Doit contenir au moins une lettre de l'alphabet anglais
- Ne doit pas commencer ni se terminer par un point, ni contenir deux points consécutifs
- Ne doit pas commencer par « www »
- Ne doit pas se terminer par un suffixe de domaine (par exemple, .com, .org, .net, .edu, .gov, .mil, .us, .in, .html)
La casse n'est pas prise en compte lors de la comparaison des noms d'utilisateur, mais le point et le trait de soulignement ne sont pas interchangeables. Par exemple, myid, my.idet my_id sont tous considérés comme des noms d'utilisateur distincts.
Pour consulter la liste complète et officielle des règles, reportez-vous au Documentation sur les noms d'utilisateur Meta Business.
Authentification
Tous les points de terminaison de gestion des noms d'utilisateur prennent en charge l'authentification Basic Auth et JWT. Votre clé API doit être associée au compte WhatsApp Business (WABA) auquel appartient le numéro de téléphone que vous gérez.
Si votre clé API n'est pas associée au numéro de téléphone indiqué, l'API renvoie un 401 ou 403 Erreur. L'API de Meta n'est pas appelée dans ce cas.
URL de base
Tous les points de terminaison de gestion des noms d'utilisateur respectent la convention de chemin d'accès de l'API Channel Manager :
https://api.nexmo.com/v1/channel-manager/whatsapp/numbers/:whatsapp_number/...
Les :whatsapp_number Le paramètre « path » ne doit contenir que des chiffres, sans signe « + » ni « - » au début (par exemple, 447000000000).
Points de terminaison disponibles
Obtenir des suggestions de noms d'utilisateur réservés
Récupérez la liste des noms d'utilisateur que Meta a pré-réservés pour un numéro de téléphone professionnel. Cela constitue un bon point de départ si vous ne savez pas quel nom d'utilisateur choisir.
GET /v1/channel-manager/whatsapp/numbers/:whatsapp_number/username-suggestions
Exemple de demande :
curl -X GET https://api.nexmo.com/v1/channel-manager/whatsapp/numbers/447000000000/username-suggestions \
-H "Authorization: Bearer $VONAGE_JWT"
Exemple de réponse (suggestions disponibles) :
{
"username_suggestions": [
"vonage_support",
"vonagesupport",
"vonage.support"
]
}
Si Meta ne propose aucune suggestion concernant ce nombre, le username_suggestions Le tableau renvoyé est vide.
| Code HTTP | Description |
|---|---|
404 |
Numéro de téléphone introuvable ou non associé à la clé API authentifiée |
4xx |
Numéro de téléphone non enregistré ou non associé à Meta |
401 / 403 |
La clé API n'est pas associée à ce numéro de téléphone |
Adopter, modifier ou supprimer un nom d'utilisateur
Utilisez ce point de terminaison pour créer un nouveau nom d'utilisateur, modifier un nom d'utilisateur existant ou supprimer un nom d'utilisateur associé à un numéro de téléphone professionnel.
PATCH /v1/channel-manager/whatsapp/numbers/:whatsapp_number/username
Champs du corps de la requête :
| Champ d'application | Type | Exigée | Description |
|---|---|---|---|
username |
chaîne de caractères | Oui | Nom d'utilisateur professionnel souhaité. Doit respecter les règles de format. Passez une chaîne vide ("") pour supprimer un nom d'utilisateur existant ou annuler une demande en attente. |
transfer_action |
chaîne de caractères | Non | Détermine le comportement à adopter lorsque le nom d'utilisateur demandé est déjà utilisé par un autre numéro de téléphone au sein du même portefeuille WABA. Valeurs : none (par défaut — la requête échoue si le nom d'utilisateur est déjà utilisé) ou force_transfer (déplace le nom d'utilisateur de l'autre numéro vers celui-ci). |
Exemple de demande — adoption ou modification d'un nom d'utilisateur :
curl -X PATCH https://api.nexmo.com/v1/channel-manager/whatsapp/numbers/447000000000/username \
-H "Authorization: Bearer $VONAGE_JWT" \
-H "Content-Type: application/json" \
-d '{
"username": "vonage_support"
}'
Exemple de requête — suppression d'un nom d'utilisateur :
curl -X PATCH https://api.nexmo.com/v1/channel-manager/whatsapp/numbers/447000000000/username \
-H "Authorization: Bearer $VONAGE_JWT" \
-H "Content-Type: application/json" \
-d '{
"username": ""
}'
Réponse — 202 Accepté :
La demande a été transmise à Meta et est en attente de validation. Vonage n'enregistre le nom d'utilisateur dans sa base de données qu'une fois que le statut est passé à « ACTIF » via un webhook.
{
"status": "approved"
}
Réponses d'erreur :
| Code HTTP | Code d'erreur Meta | Description |
|---|---|---|
400 |
100 | Format de nom d'utilisateur non valide |
409 |
147001 | Ce nom d'utilisateur est déjà pris ou indisponible |
403 |
147002 | Account non éligible — limite de messages trop faible |
422 |
147003 | Le numéro de téléphone doit d'abord être associé à une page Facebook |
422 |
147004 | Le numéro de téléphone doit d'abord être associé à un compte Instagram |
409 |
147005 | Ce nom d'utilisateur est déjà utilisé sur un autre numéro du même portefeuille. Renvoyez la demande en indiquant « transfer_action: force_transfer » pour le transférer. |
422 |
133010 | Numéro de téléphone non enregistré pour l'utilisation de l'API |
401 / 403 |
- | La clé API n'est pas associée à ce numéro de téléphone |
404 |
- | Numéro de téléphone introuvable ou aucun identifiant actif à supprimer |
Récupérer le nom d'utilisateur actuel
Récupérer le nom d'utilisateur actuel et son statut pour un numéro de téléphone professionnel.
GET /v1/channel-manager/whatsapp/numbers/:whatsapp_number/username
Exemple de demande :
curl -X GET https://api.nexmo.com/v1/channel-manager/whatsapp/numbers/447000000000/username \
-H "Authorization: Bearer $VONAGE_JWT"
Exemple de réponse (le nom d'utilisateur existe) :
{
"username": "vonage_support",
"status": "approved"
}
Exemple de réponse (aucun nom d'utilisateur défini) :
{
"username": null,
"status": null
}
| Code HTTP | Description |
|---|---|
404 |
Numéro de téléphone introuvable ou non associé à la clé API authentifiée |
401 / 403 |
La clé API n'est pas associée à ce numéro de téléphone |
Champ « Nom d'utilisateur » dans les réponses chiffrées
Les username Un champ a été ajouté aux réponses des points de terminaison existants « List Numbers » et « Get Number ». Il n'apparaît que lorsqu'un nom d'utilisateur avec ACTIVE le statut existe pour ce numéro. Si aucun nom d'utilisateur actif n'est défini, ce champ n'apparaît pas dans la réponse.
Terminaux concernés :
- GET
/v1/channel-manager/whatsapp/wabas/:waba_id/numbers - GET
/v1/channel-manager/whatsapp/numbers/:whatsapp_number
Exemple de réponse mise à jour :
{
"verified_name": "Vonage Support",
"display_phone_number": "+44 7000 000000",
"phone_number": "447000000000",
"number_id": "3900084270039015",
"waba_id": "345688589250625",
"api_key": "ccc333",
"messaging_limit_tier": "TIER_100K",
"quality_score": {
"score": "GREEN"
},
"username": "vonage_support"
}