Se connecterCommencer l’essai gratuit
Meta Tech Provider

Noms d'utilisateur WhatsApp et identifiants BSUID limités à l'entreprise : ce qui change dans les webhooks Cloud API

Les noms d'utilisateur WhatsApp permettent d'afficher un nom à la place du numéro de téléphone. Depuis début avril 2026, les webhooks messages Cloud API contiennent donc aussi un identifiant utilisateur limité à l'entreprise (BSUID), comme US.13491208655302741918, dans user_id et from_user_id. Pour un utilisateur ayant un nom d'utilisateur, sans message ni appel avec le numéro depuis 30 jours et absent du carnet de contacts, wa_id et from sont omis.

easyCoexistence connecte un numéro de l'application WhatsApp Business à la Cloud API via Coexistence et achemine ses webhooks messages et smb_message_echoes vers votre endpoint tels que Meta les envoie, champs BSUID inclus, tandis que get_api_credentials donne à votre code ce qu'il faut pour répondre avec recipient.

April 2026

Date d'apparition des BSUID dans les webhooks Cloud API, avant l'arrivée des noms d'utilisateur chez les utilisateurs WhatsApp.

July 2026

Date à partir de laquelle les API acceptent les messages envoyés à un BSUID, défini dans recipient au lieu de to.

30 days

Durée de conservation, par numéro de téléphone professionnel, pendant laquelle tout message ou appel avec l'utilisateur conserve son numéro dans les webhooks.

128

Nombre maximal de caractères alphanumériques après le code pays à deux lettres et le point d'un BSUID.

131062

Erreur de l'API Messages : les destinataires BSUID (identifiant utilisateur limité à l'entreprise) ne sont pas pris en charge pour ce message.

user_changed_user_id

Type de message système pour un changement de BSUID signalé sans numéro de téléphone, avec l'ancien BSUID dans previous_user_id.

Que sont les noms d'utilisateur WhatsApp et les BSUID ?

Un nom d'utilisateur est un nom unique et facultatif que peut choisir un utilisateur WhatsApp ; il s'affiche dans l'application à la place de son numéro de téléphone. Meta déploie progressivement ces noms en 2026. Un BSUID est l'identifiant interne ajouté par Meta pour que les entreprises puissent toujours distinguer leurs utilisateurs : il est généré automatiquement, il est unique pour chaque couple Business Portfolio et utilisateur, et il se présente sous la forme du code pays ISO 3166 à deux lettres, d'un point, puis de 128 caractères alphanumériques au maximum. Meta exige que les partenaires et les intégrations directes prennent en charge cet identifiant, car aucune entreprise ne contrôle l'adoption des noms d'utilisateur par ses utilisateurs.

Quels champs portent les nouveaux identifiants ?

De nouvelles propriétés s'ajoutent à celles qui contenaient le numéro de téléphone, dans les webhooks messages, status, system et user_preferences. Les champs parents n'apparaissent que pour les Business Portfolio que Meta a inscrits aux BSUID parents, qui fonctionnent sur l'ensemble des Business Portfolio inscrits :

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

Quand le numéro de téléphone est-il omis ?

Lorsque l'utilisateur possède un nom d'utilisateur et qu'aucune des trois conditions de Meta n'est remplie. Le numéro reste dans les webhooks si le numéro de téléphone professionnel a écrit à ce numéro ou l'a appelé au cours des 30 derniers jours, en a reçu un message ou un appel pendant cette période, ou si l'utilisateur figure dans le carnet de contacts du Business Portfolio. La période de 30 jours est comptée par numéro de téléphone professionnel : un second numéro du même portfolio peut donc ne recevoir que le BSUID du même utilisateur. Les utilisateurs sans nom d'utilisateur continuent d'arriver avec à la fois leur numéro de téléphone et leur BSUID.

À quoi ressemble désormais un message entrant ?

Comme auparavant, avec le BSUID à côté du numéro de téléphone ou à sa place. Dans l'exemple de Meta d'un utilisateur avec nom d'utilisateur dont le numéro ne peut pas être partagé, contacts contient profile.name, profile.username et user_id, et le message contient from_user_id à la place de l'ancien from :

messages webhook: a text from a user known only by BSUID
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
        "contacts": [{
          "profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
          "user_id": "US.13491208655302741918"
        }],
        "messages": [{
          "from_user_id": "US.13491208655302741918",
          "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
          "timestamp": "1749416383",
          "type": "text",
          "text": { "body": "Does it come in another color?" }
        }]
      }
    }]
  }]
}

Comment changent les webhooks status ?

Les status sent, delivered et read gagnent un tableau contacts avec le nom de l'utilisateur, user_id, wa_id lorsque le numéro peut être partagé, et username sur delivered et read. Dans les status, recipient_user_id contient le BSUID, et recipient_id est omis lorsque vous avez envoyé à un BSUID et que le numéro ne peut pas être partagé. Un status failed n'a pas de tableau contacts et omet recipient_user_id lorsque le message a été envoyé à un numéro de téléphone : rattachez donc les échecs à l'id du message.

Comment stocker et associer les utilisateurs ?

Par BSUID d'abord, avec le numéro de téléphone comme deuxième clé chaque fois qu'il arrive. Stockez le BSUID entier sous forme de chaîne, code pays et point compris, car Meta rejette les requêtes qui modifient une partie de celui-ci, et stockez aussi le BSUID parent si vos Business Portfolio sont inscrits. Rattachez les enregistrements existants à wa_id tant qu'il arrive, et conservez le BSUID à côté, car un utilisateur qui adopte un nom d'utilisateur plus tard peut revenir sans numéro. La FAQ de Meta demande les mêmes jointures dans les CRM et dans les outils qu'ils alimentent.

Que se passe-t-il lorsqu'un utilisateur change de numéro de téléphone ?

Son BSUID est régénéré, et le changement arrive sur le champ messages sous forme de message système, car Meta n'a pas de champ user_id_update auquel s'abonner. system.type vaut user_changed_number lorsque le nouveau numéro peut être partagé avec vous, ou user_changed_user_id lorsque seul le changement de BSUID peut être signalé ; system.user_id contient le nouveau BSUID et system.previous_user_id l'ancien, ce qui permet de reporter l'enregistrement. Gérez les deux types.

Comment répondre à un utilisateur connu seulement par son BSUID ?

Envoyez à /<BUSINESS_PHONE_NUMBER_ID>/messages avec recipient défini sur le BSUID et to omis ; si les deux sont présents, to l'emporte et la réponse part vers le numéro de téléphone. L'entrée contacts de la réponse contient alors input et user_id au lieu de wa_id. Tous les types de message fonctionnent, sauf les templates d'authentification one-tap, zero-tap et copy code, qui exigent un numéro de téléphone, et seuls les numéros du même Business Portfolio peuvent atteindre un BSUID. L'erreur 131062 signifie que ce type de message n'accepte pas les destinataires BSUID.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

Comment demander le numéro de téléphone à un utilisateur ?

Avec le bouton REQUEST_CONTACT_INFO, ajouté à un template utility ou marketing, ou envoyé comme message interactif de type request_contact_info. Un utilisateur qui appuie dessus partage son numéro dans la conversation, et un webhook contacts arrive avec origin défini sur contact_request et le numéro dans phones[].wa_id ; un contact partagé à la main arrive avec origin à la valeur other et une vCard. Meta a rendu le bouton disponible début juillet 2026, et son libellé ne peut pas être personnalisé.

Qu'est-ce que le carnet de contacts ?

Un répertoire que Meta héberge pour chaque Business Portfolio, sans travail d'intégration : dès qu'un numéro de téléphone professionnel écrit à un utilisateur, l'appelle ou reçoit de sa part un message ou un appel, ce numéro et le BSUID sont enregistrés et servent à compléter les webhooks suivants avec le numéro de téléphone, avec ou sans nom d'utilisateur. Seules les interactions postérieures à son lancement comptent. On peut le désactiver dans Meta Business Suite, Paramètres de l'entreprise, Informations sur l'entreprise, ce qui supprime son contenu ; GET ou DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book avec un bsuid permet de vérifier ou de retirer une entrée.

Que doit modifier une intégration Coexistence ?

Sa gestion des trois webhooks que seul un numéro Coexistence reçoit, qui changent aussi. Dans history, chaque fil gagne un objet context avec wa_id, user_id et username, et ses messages gagnent from_user_id. Dans smb_message_echoes, un tableau contacts est ajouté, et message_echoes[].to peut être omis tandis que to_user_id contient le BSUID ; les modifications et révocations faites dans l'application WhatsApp Business arrivent de la même manière. Dans smb_app_state_sync, le phone_number d'un contact peut être omis, avec user_id et username à côté. Rapprochez les échos et les conversations importées sur user_id en plus du numéro.

Comment tester avant que les utilisateurs n'adoptent les noms d'utilisateur ?

Avec l'outil de test de Meta dans le dashboard de l'application : sous Cas d'usage, Se connecter aux clients via WhatsApp, Personnaliser, Configuration, le lien Test à côté du webhook messages envoie un exemple à votre endpoint. Il couvre les messages entrants et les status dans quatre scénarios :

  • Un utilisateur sans nom d'utilisateur : champs BSUID et numéro de téléphone, sans username.
  • Un utilisateur avec nom d'utilisateur dont le numéro est indisponible : username et BSUID, sans champs de numéro de téléphone.
  • Un utilisateur avec nom d'utilisateur dont le numéro est disponible : username, BSUID et numéro de téléphone.
  • Un Business Portfolio inscrit aux BSUID parents : un BSUID parent à côté du BSUID propre au portfolio.

Comment easyCoexistence gère-t-il les BSUID ?

Il les transmet tels que Meta les envoie. Un numéro acheminé vers votre endpoint avec set_webhook_destination reçoit directement de Meta ses webhooks messages et smb_message_echoes, avec user_id, from_user_id, to_user_id et username inclus, et lorsque les automatisations ou le transfert sont activés, easyCoexistence transfère la valeur envoyée par Meta sans la modifier. Pour répondre à un BSUID, votre code utilise get_api_credentials, qui renvoie l'ID du numéro de téléphone, son endpoint d'envoi et, lorsqu'il est disponible, votre propre token ; les outils send_message et send_template prennent un numéro de téléphone au format international.

Erreurs courantes

  • Indexer les contacts uniquement sur wa_id. Un utilisateur ayant un nom d'utilisateur et sans contact avec le numéro depuis 30 jours arrive avec seulement user_id et from_user_id ; un gestionnaire qui exige wa_id manque le message.
  • Tronquer le préfixe pays d'un BSUID. Meta attend la valeur entière, code pays et point compris, et une requête dont une partie est modifiée échoue.
  • Attendre un champ user_id_update. Meta n'en a pas : les changements de BSUID arrivent sur messages sous forme de messages système de type user_changed_number ou user_changed_user_id.
  • Rapprocher les échos Coexistence sur to seul. Dans smb_message_echoes le champ to peut être omis, donc une réponse tapée dans l'application reste invisible si to_user_id n'est pas rapproché également.
Faire cela avec EasyCoexistence

Chaque connexion est surveillée 24h/24, 7j/7. De US$ 9 à US$ 0,75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec les 3 premiers jours gratuits.

Questions fréquemment posées

Les utilisateurs sans nom d'utilisateur reçoivent-ils aussi un BSUID ?

Oui. Meta renseigne user_id dans les webhooks messages, que l'utilisateur ait ou non un nom d'utilisateur, si bien que la plupart des utilisateurs arrivent avec à la fois leur numéro de téléphone et leur BSUID.

Un numéro Coexistence peut-il avoir un nom d'utilisateur professionnel ?

Oui. Depuis le 29 juin 2026, une entreprise peut en adopter ou en modifier un dans Meta Business Suite, WhatsApp Manager, l'application WhatsApp Business ou l'API Username ; cela ne masque pas le numéro professionnel, et business_username_updates signale chaque changement de status.

Un BSUID fonctionne-t-il entre plusieurs Business Portfolio ?

Non. Un BSUID appartient à un seul Business Portfolio et à un seul utilisateur, et un numéro d'un autre Business Portfolio ne peut pas lui écrire. Les entreprises gérées que Meta inscrit reçoivent des BSUID parents, avec ENT après le code pays, qui fonctionnent sur l'ensemble de leurs Business Portfolio inscrits.

Combien coûte easyCoexistence pour un numéro WhatsApp ?

De US$ 9 à US$ 0,75 par connexion et par mois selon le nombre de connexions, et les 3 premiers jours sont gratuits. Les frais de message propres à Meta restent sur le moyen de paiement de votre compte WhatsApp Business.

Poursuivre la lecture

Prêt à commencer ?

Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.

Commencer l'essai gratuit

Vérifié le