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"
}

Plus d'informations