InloggenGratis proefperiode starten
Meta Tech Provider

WhatsApp-gebruikersnamen en BSUID's: wat er verandert in Cloud API-webhooks

WhatsApp-gebruikersnamen laten gebruikers een naam tonen in plaats van hun telefoonnummer. Daarom bevatten Cloud API-webhooks voor berichten sinds begin april 2026 ook een bedrijfsgebonden gebruikers-ID (BSUID), zoals US.13491208655302741918, in user_id en from_user_id. Voor een gebruiker met een gebruikersnaam die 30 dagen geen bericht of oproep met het nummer heeft gehad en niet in het contactenboek staat, worden wa_id en from weggelaten.

easyCoexistence verbindt een WhatsApp Business-app-nummer via Coexistence met de Cloud API en stuurt de webhooks voor messages en smb_message_echoes door naar je endpoint zoals Meta ze verstuurt, inclusief de BSUID-velden.

April 2026

Wanneer BSUID's in Cloud API-webhooks begonnen te verschijnen, vóórdat gebruikersnamen bij WhatsApp-gebruikers aankwamen.

July 2026

Wanneer de API's berichten naar een BSUID begonnen te accepteren, ingesteld in recipient in plaats van to.

30 days

Terugkijkperiode per bedrijfstelefoonnummer, waarbinnen elk bericht of elke oproep met de gebruiker hun nummer in webhooks behoudt.

128

Het maximale aantal alfanumerieke tekens na de tweeletterige landcode en de punt van een BSUID.

131062

Fout in de Messages API: Business-scoped User ID (BSUID) recipients are not supported for this message.

user_changed_user_id

Type systeembericht voor een BSUID-wijziging gemeld zonder telefoonnummer, met de oude BSUID in previous_user_id.

Wat zijn WhatsApp-gebruikersnamen en BSUID's?

Een gebruikersnaam is een optionele, unieke naam die een WhatsApp-gebruiker kan instellen en die in de app in plaats van het telefoonnummer wordt getoond; Meta rolt gebruikersnamen in 2026 geleidelijk uit. Een BSUID is de backend-identifier die Meta heeft toegevoegd zodat bedrijven gebruikers nog steeds uit elkaar kunnen houden: automatisch gegenereerd, uniek per Business Portfolio en gebruikerspaar, en geschreven als de tweeletterige ISO 3166-landcode van de gebruiker, een punt en maximaal 128 alfanumerieke tekens. Meta vereist dat partners en rechtstreeks geïntegreerde bedrijven dit ondersteunen, omdat geen enkel bedrijf bepaalt of zijn gebruikers gebruikersnamen gaan gebruiken.

Welke velden bevatten de nieuwe identifiers?

Nieuwe eigenschappen naast de velden die het telefoonnummer bevatten, in de webhooks voor messages, status, system en user_preferences. De bovenliggende velden verschijnen alleen voor Business Portfolio's die Meta heeft ingeschreven voor parent BSUID's, die over de ingeschreven portfolio's heen werken:

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

Wanneer wordt het telefoonnummer weggelaten?

Wanneer de gebruiker een gebruikersnaam heeft en geen van Meta's drie voorwaarden geldt. Het nummer blijft in webhooks staan als het bedrijfstelefoonnummer het nummer van die gebruiker in de afgelopen 30 dagen een bericht heeft gestuurd of heeft gebeld, er in die tijd een bericht of oproep van heeft ontvangen, of de gebruiker in het contactenboek van de portfolio staat. De terugkijkperiode van 30 dagen wordt per bedrijfstelefoonnummer geteld, dus een tweede nummer in dezelfde portfolio kan voor dezelfde gebruiker alleen de BSUID ontvangen. Gebruikers zonder gebruikersnaam blijven binnenkomen met zowel hun telefoonnummer als hun BSUID.

Hoe ziet een binnenkomend bericht er nu uit?

Zoals voorheen, met de BSUID naast het telefoonnummer of in de plaats daarvan. In Meta's voorbeeld van een gebruiker met een gebruikersnaam wiens nummer niet gedeeld kan worden, bevat contacts profile.name, profile.username en user_id, en bevat het bericht from_user_id op de plek waar vroeger from stond:

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

Hoe veranderen statuswebhooks?

Verzonden, afgeleverde en gelezen statussen krijgen een contacts-array met de naam van de gebruiker, user_id, wa_id wanneer het nummer gedeeld kan worden, en username bij afgeleverd en gelezen. Bij statussen bevat recipient_user_id de BSUID, en wordt recipient_id weggelaten wanneer je naar een BSUID hebt verzonden en het nummer niet gedeeld kan worden. Een mislukte status heeft geen contacts-array en laat recipient_user_id weg wanneer het bericht naar een telefoonnummer ging, dus koppel fouten aan de bericht-id.

Hoe sla je gebruikers op en koppel je ze?

Op BSUID eerst, met het telefoonnummer als tweede sleutel zodra het binnenkomt. Sla de volledige BSUID op als string, inclusief landcode en punt, omdat Meta verzoeken afwijst die een deel ervan wijzigen, en sla ook de parent BSUID op als je portfolio's zijn ingeschreven. Koppel bestaande records op wa_id zolang die nog binnenkomt en bewaar de BSUID ernaast, want een gebruiker die later een gebruikersnaam kiest kan terugkomen zonder nummer. Meta's FAQ vraagt om dezelfde koppelingen in CRM's en in de tools die ervan gebruikmaken.

Wat gebeurt er als een gebruiker zijn telefoonnummer wijzigt?

Zijn BSUID wordt opnieuw gegenereerd, en de wijziging komt binnen op het messages-veld als systeembericht, omdat Meta geen user_id_update-veld heeft om op te abonneren. system.type is user_changed_number wanneer het nieuwe nummer met je gedeeld kan worden, of user_changed_user_id wanneer alleen de BSUID-wijziging gemeld kan worden; system.user_id bevat de nieuwe BSUID en system.previous_user_id de oude, waarmee een record meeverhuist. Verwerk beide typen.

Hoe antwoord je een gebruiker die alleen bekend is via een BSUID?

Verstuur naar /<BUSINESS_PHONE_NUMBER_ID>/messages met recipient ingesteld op de BSUID en to weggelaten; als beide aanwezig zijn, wint to en gaat het antwoord naar het telefoonnummer. De contacts-vermelding in het antwoord bevat dan input en user_id in plaats van wa_id. Elk berichttype werkt behalve one-tap-, zero-tap- en copy code-authenticatietemplates, die een telefoonnummer nodig hebben, en alleen nummers binnen dezelfde Business Portfolio kunnen een BSUID bereiken. Fout 131062 betekent dat het berichttype geen BSUID-ontvangers accepteert.

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

Hoe vraag je een gebruiker om zijn telefoonnummer?

Met de knop REQUEST_CONTACT_INFO, toegevoegd aan een utility- of marketingtemplate of verstuurd als interactief bericht van het type request_contact_info. Een gebruiker die erop tikt deelt zijn nummer in de thread, en er komt een contacts-webhook binnen met origin ingesteld op contact_request en het nummer in phones[].wa_id; een contact dat handmatig wordt gedeeld komt binnen met origin other en een vCard. Meta maakte de knop begin juli 2026 beschikbaar, en het label kan niet worden aangepast.

Wat is het contactenboek?

Een opslag die Meta voor elke Business Portfolio beheert, zonder integratiewerk: zodra een bedrijfstelefoonnummer een bericht stuurt, belt of van het telefoonnummer van een gebruiker hoort, worden dat nummer en de BSUID vastgelegd en gebruikt om latere webhooks aan te vullen met het telefoonnummer, of de gebruiker nu een gebruikersnaam heeft of niet. Alleen interacties na de lancering tellen mee. Het kan worden uitgeschakeld in Meta Business Suite, Bedrijfsinstellingen, Bedrijfsinformatie, wat opgeslagen gegevens verwijdert, en GET of DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book met een bsuid controleert of verwijdert één vermelding.

Wat moet een Coexistence-integratie veranderen?

De verwerking van de drie webhooks die alleen een Coexistence-nummer ontvangt, die eveneens veranderen. In history krijgt elke thread een context-object met wa_id, user_id en username, en krijgen de berichten from_user_id. In smb_message_echoes wordt een contacts-array toegevoegd, en message_echoes[].to kan worden weggelaten terwijl to_user_id de BSUID bevat; bewerkingen en intrekkingen die in de WhatsApp Business-app zijn gemaakt, komen op dezelfde manier binnen. In smb_app_state_sync kan phone_number van een contact worden weggelaten, met user_id en username ernaast. Koppel echo's en geïmporteerde chats ook op user_id naast het nummer.

Hoe kun je testen voordat gebruikers gebruikersnamen overnemen?

Met de testtool van Meta in het App Dashboard: onder Use cases, Connect with customers through WhatsApp, Customize, Configuration stuurt de Test-link naast de messages-webhook een voorbeeld naar je endpoint. Die dekt binnenkomende berichten en statussen in vier scenario's:

  • Een gebruiker zonder gebruikersnaam: velden voor BSUID en telefoonnummer, en geen gebruikersnaam.
  • Een gebruiker met een gebruikersnaam wiens nummer niet beschikbaar is: gebruikersnaam en BSUID, zonder velden voor het telefoonnummer.
  • Een gebruiker met een gebruikersnaam wiens nummer beschikbaar is: gebruikersnaam, BSUID en telefoonnummer.
  • Een portfolio ingeschreven voor parent BSUID's: een parent BSUID naast de eigen BSUID van de portfolio.

Hoe gaat easyCoexistence om met BSUID's?

Het geeft ze door zoals Meta ze verstuurt. Een nummer dat met set_webhook_destination naar je endpoint is geleid, krijgt zijn messages- en smb_message_echoes-webhooks rechtstreeks van Meta, inclusief user_id, from_user_id, to_user_id en username, en met automatiseringen of doorsturen ingeschakeld stuurt easyCoexistence de waarde die Meta verstuurde ongewijzigd door. Om een BSUID te beantwoorden, gebruikt je code get_api_credentials, die het phone number ID van het nummer, het verzend-endpoint en, indien beschikbaar, je eigen token teruggeeft; de tools send_message en send_template nemen een telefoonnummer in internationale cijfers.

Veelgemaakte fouten

  • Contacten koppelen op wa_id alleen. Een gebruiker met een gebruikersnaam die 30 dagen geen contact met het nummer heeft gehad, komt alleen met user_id en from_user_id binnen, en een handler die wa_id vereist mist het bericht.
  • De landcodeprefix van een BSUID afkappen. Meta wil de volledige waarde, inclusief landcode en punt, en een verzoek waarin iets is gewijzigd mislukt.
  • Wachten op een user_id_update-veld. Meta heeft er geen: BSUID-wijzigingen komen binnen op messages als systeemberichten van het type user_changed_number of user_changed_user_id.
  • Coexistence-echo's alleen op to koppelen. In smb_message_echoes kan het veld to worden weggelaten, dus een antwoord dat in de app is getypt blijft onzichtbaar tenzij ook to_user_id wordt gekoppeld.
Dit doen met EasyCoexistence

Met get_api_credentials krijgt je code wat het nodig heeft om met recipient te antwoorden. Elke verbinding wordt 24/7 bewaakt. Van US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, en de eerste 3 dagen zijn gratis.

Veelgestelde vragen

Krijgen gebruikers zonder gebruikersnaam ook een BSUID?

Ja. Meta zet user_id in messages-webhooks, of de gebruiker nu een gebruikersnaam heeft of niet, dus de meeste gebruikers komen binnen met zowel hun telefoonnummer als hun BSUID.

Kan een Coexistence-nummer een zakelijke gebruikersnaam hebben?

Ja. Sinds 29 juni 2026 kan een bedrijf er een kiezen of wijzigen in Meta Business Suite, WhatsApp Manager, de WhatsApp Business-app of de Username API. Het verbergt het bedrijfsnummer niet, en business_username_updates meldt elke statuswijziging.

Werkt een BSUID over Business Portfolio's heen?

Nee. Een BSUID hoort bij één portfolio en gebruiker, en een nummer in een andere portfolio kan er geen berichten naartoe sturen. Beheerde bedrijven die Meta inschrijft, krijgen parent BSUID's, met ENT na de landcode, die werken over hun ingeschreven portfolio's heen.

Hoeveel kost easyCoexistence per WhatsApp-nummer?

Van US$ 9 tot US$ 0,75 per verbinding per maand, afhankelijk van hoeveel verbindingen je hebt, en de eerste 3 dagen zijn gratis. Meta's eigen berichtkosten blijven op de betaalmethode van je WhatsApp Business Account staan.

Lees verder

Klaar om te beginnen?

Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.

Start je gratis proefperiode

Geverifieerd op