Kirjaudu sisäänAloita ilmainen kokeilu
Meta Tech Provider

WhatsApp-käyttäjänimet ja yrityskohtaiset käyttäjätunnukset (BSUID): mitä muuttuu Cloud API -rajapinnan webhookeissa

WhatsApp-käyttäjänimet antavat käyttäjille mahdollisuuden näyttää nimen puhelinnumeron sijaan, joten huhtikuun alusta 2026 lähtien Cloud API -rajapinnan viestien webhookeissa on myös yrityskohtainen käyttäjätunnus (BSUID), esimerkiksi US.13491208655302741918, kentissä user_id ja from_user_id. Jos käyttäjällä on käyttäjänimi, eikä hänen numeronsa kautta ole ollut viestiä tai puhelua 30 päivään eikä hän ole yhteystietoluettelossa, wa_id ja from jätetään pois.

easyCoexistence yhdistää WhatsApp Business -sovelluksen numeron Cloud API -rajapintaan Coexistencen kautta ja reitittää sen messages- ja smb_message_echoes-webhookit endpointiisi sellaisinaan kuin Meta ne lähettää, BSUID-kentät mukaan lukien.

April 2026

Milloin BSUID:t alkoivat ilmestyä Cloud API -webhookeihin, ennen kuin käyttäjänimet tulivat WhatsApp-käyttäjille.

July 2026

Milloin API:t alkoivat hyväksyä BSUID:lle lähetettyjä viestejä, jotka asetetaan recipient-kenttään to-kentän sijaan.

30 days

Seurantajakso yhtä yrityksen puhelinnumeroa kohden: minkä tahansa viestin tai puhelun aikana käyttäjän numero säilyy webhookeissa.

128

Suurin osa BSUID:n kaksikirjaimisen maakoodin ja pisteen jälkeisistä aakkosnumeerisista merkeistä.

131062

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

user_changed_user_id

Järjestelmäviestin tyyppi BSUID-muutokselle, joka ilmoitetaan ilman puhelinnumeroa, ja vanha BSUID kentässä previous_user_id.

Mitä ovat WhatsApp-käyttäjänimet ja BSUID:t?

Käyttäjänimi on valinnainen, yksilöllinen nimi, jonka WhatsApp-käyttäjä voi asettaa. Sovelluksessa se näkyy puhelinnumeron sijaan. Meta ottaa käyttäjänimet käyttöön asteittain vuonna 2026. BSUID on taustajärjestelmän tunniste, jonka Meta on lisännyt, jotta yritykset pystyvät edelleen erottamaan käyttäjät toisistaan. Se muodostetaan automaattisesti, se on yksilöllinen kullekin Business Portfolio -kokonaisuuden ja käyttäjän yhdistelmälle, ja se on muotoa: käyttäjän ISO 3166 -maakoodi kahdella kirjaimella, piste ja enintään 128 aakkosnumeerista merkkiä. Meta edellyttää, että kumppanit ja suoraan integroidut yritykset tukevat sitä, koska yksikään yritys ei päätä, ottavatko sen käyttäjät käyttäjänimet käyttöön.

Mitkä kentät kantavat uudet tunnisteet?

Uudet kentät ovat puhelinnumerokenttien rinnalla messages-, status-, system- ja user_preferences-webhookeissa. Emo-BSUID-kentät näkyvät vain Business Portfolio -kokonaisuuksille, jotka Meta on ottanut mukaan emo-BSUID-järjestelmään, ja ne toimivat mukana olevien kokonaisuuksien välillä:

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

Milloin puhelinnumero jätetään pois?

Kun käyttäjällä on käyttäjänimi eikä mikään Metan kolmesta ehdosta täyty. Numero säilyy webhookeissa, jos yrityksen puhelinnumero on viimeisten 30 päivän aikana lähettänyt viestin tai soittanut käyttäjän numeroon, vastaanottanut viestin tai puhelun siltä, tai jos käyttäjä on Business Portfolio -kokonaisuuden yhteystietoluettelossa. 30 päivän seuranta lasketaan erikseen kullekin yrityksen puhelinnumerolle, joten saman kokonaisuuden toinen numero voi saada vain saman käyttäjän BSUID:n. Ilman käyttäjänimeä olevat käyttäjät saapuvat edelleen sekä puhelinnumeron että BSUID:n kanssa.

Miltä saapuva viesti näyttää nyt?

Kuten ennenkin, BSUID puhelinnumeron vieressä tai sen tilalla. Metan esimerkissä käyttäjästä, jolla on käyttäjänimi ja jonka numeroa ei voi jakaa, contacts sisältää kentät profile.name, profile.username ja user_id, ja viesti kantaa from_user_id-kenttää siinä, missä from oli ennen:

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

Miten status-webhookit muuttuvat?

Lähetetyt, toimitetut ja luetut tilat saavat contacts-taulukon, jossa on käyttäjän nimi, user_id, wa_id silloin kun numeroa voi jakaa, ja username toimitetuissa ja luetuissa. statuses-kentässä recipient_user_id kantaa BSUID:n, ja recipient_id jätetään pois, kun lähetit BSUID:lle eikä numeroa voi jakaa. Epäonnistuneessa tilassa ei ole contacts-taulukkoa, ja recipient_user_id puuttuu, kun viesti meni puhelinnumeroon, joten yhdistä epäonnistumiset viestin id:hen.

Miten tallennat ja yhdistät käyttäjät?

Ensisijaisesti BSUID:n mukaan, ja puhelinnumero toisena avaimena aina kun se saapuu. Tallenna koko BSUID merkkijonona, maakoodi ja piste mukaan lukien, sillä Meta hylkää pyynnöt, jotka muuttavat mitä tahansa sen osaa. Tallenna myös emo-BSUID, jos Business Portfolio -kokonaisuutesi on liitetty siihen. Yhdistä olemassa olevat tietueet wa_id-kentän perusteella niin kauan kuin se saapuu, ja säilytä BSUID niiden vieressä, koska käyttäjä, joka ottaa käyttäjänimen myöhemmin, voi palata ilman numeroa. Metan UKK pyytää samat yhdistämiset CRM-järjestelmissä ja työkaluissa, joita ne syöttävät.

Mitä tapahtuu, kun käyttäjä vaihtaa puhelinnumeronsa?

Käyttäjän BSUID luodaan uudelleen, ja muutos saapuu messages-kenttään järjestelmäviestinä, koska Metalla ei ole user_id_update-kenttää, johon tilata. system.type on user_changed_number, kun uusi numero voidaan jakaa sinulle, tai user_changed_user_id, kun voidaan raportoida vain BSUID-muutos. system.user_id sisältää uuden BSUID:n ja system.previous_user_id vanhan, ja näin tietue siirtyy mukana. Käsittele molemmat tyypit.

Miten vastaat käyttäjälle, joka tunnetaan vain BSUID:llä?

Lähetä osoitteeseen /<BUSINESS_PHONE_NUMBER_ID>/messages, jossa recipient on BSUID ja to jätetty pois. Jos molemmat ovat mukana, to voittaa ja vastaus menee puhelinnumeroon. Vastauksen contacts-merkintä sisältää silloin input- ja user_id-kentät eikä wa_id-kenttää. Mikä tahansa viestityyppi käy, paitsi yhden napautuksen, nollanapautuksen ja koodin kopioinnin todennuksen viestipohjat, jotka vaativat puhelinnumeron, ja BSUID:iin voivat vastata vain saman Business Portfolio -kokonaisuuden numerot. Virhe 131062 tarkoittaa, että viestityyppi ei hyväksy BSUID-vastaanottajia.

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

Miten pyydät käyttäjältä puhelinnumeron?

REQUEST_CONTACT_INFO-painikkeella, joka lisätään utility- tai markkinointiviestipohjaan tai lähetetään interaktiivisena viestinä tyyppiä request_contact_info. Käyttäjä, joka napauttaa sitä, jakaa numeronsa keskusteluun, ja contacts-webhook saapuu origin-kentällä, jonka arvo on contact_request ja numero kentässä phones[].wa_id. Käsin jaettu yhteystieto saapuu origin-arvolla other ja vCardina. Meta teki painikkeen saataville heinäkuun alussa 2026, eikä sen tekstiä voi muuttaa.

Mikä on yhteystietoluettelo?

Metan ylläpitämä tallennus jokaiselle Business Portfolio -kokonaisuudelle ilman integrointityötä: kun yrityksen puhelinnumero lähettää viestin, soittaa tai vastaanottaa viestin käyttäjän puhelinnumerosta, numero ja BSUID tallennetaan, ja niitä käytetään täyttämään myöhempiä webhookeja puhelinnumerolla, käyttäjänimestä riippumatta. Vain sen käynnistymisen jälkeiset vuorovaikutukset lasketaan. Sen voi kytkeä pois päältä Meta Business Suite -sovelluksessa kohdassa Yritysasetukset ja Yritystiedot, mikä poistaa sen sisällön. GET- tai DELETE-pyyntö osoitteeseen /<BUSINESS_PHONE_NUMBER_ID>/contact_book bsuid-kentän kanssa tarkistaa tai poistaa yhden merkinnän.

Mitä Coexistence-integraation pitää muuttaa?

Sen käsittelyä kolmesta webhookista, jotka vain Coexistence-numero saa, ja nämä muuttuvat myös. history-webhookissa jokainen keskustelu saa context-objektin, jossa on wa_id, user_id ja username, ja sen viestit saavat from_user_id-kentän. smb_message_echoes-webhookiin lisätään contacts-taulukko, ja message_echoes[].to voidaan jättää pois, kun to_user_id kantaa BSUID:n. WhatsApp Business -sovelluksessa tehdyt muokkaukset ja poistot saapuvat samalla tavalla. smb_app_state_sync-webhookissa yhteyshenkilön phone_number voi jäädä pois, ja user_id ja username ovat sen vieressä. Yhdistä kaiut ja tuodut keskustelut user_id-kentän mukaan numeron lisäksi.

Miten voit testata ennen kuin käyttäjät ottavat käyttäjänimet käyttöön?

Metan testityökalulla sovelluksen hallintapaneelissa: kohdassa Use cases, Connect with customers through WhatsApp, Customize, Configuration, messages-webhookin vieressä oleva Test-linkki lähettää näytteen endpointiisi. Se kattaa saapuvat viestit ja tilat neljässä skenaariossa:

  • Käyttäjä ilman käyttäjänimeä: BSUID- ja puhelinnumerokentät, ei käyttäjänimeä.
  • Käyttäjä käyttäjänimellä, jonka numero ei ole saatavilla: käyttäjänimi ja BSUID, ei puhelinnumerokenttiä.
  • Käyttäjä käyttäjänimellä, jonka numero on saatavilla: käyttäjänimi, BSUID ja puhelinnumero.
  • Business Portfolio, joka on liitetty emo-BSUID-järjestelmään: emo-BSUID oman kokonaisuutensa BSUID:n vieressä.

Miten easyCoexistence käsittelee BSUID:t?

Se välittää ne eteenpäin sellaisina kuin Meta ne lähettää. Numero, joka on reititetty endpointiisi set_webhook_destination-työkalulla, saa messages- ja smb_message_echoes-webhookinsa suoraan Metalta, user_id, from_user_id, to_user_id ja username mukaan lukien, ja kun automaatiot tai edelleenlähetys ovat päällä, easyCoexistence välittää Metan lähettämän arvon muuttumattomana. Vastataksesi BSUID:lle koodisi käyttää get_api_credentials-työkalua, joka palauttaa numeron puhelinnumeron tunnuksen, sen lähetysendpointin ja tarvittaessa oman tokenisi. send_message- ja send_template-työkalut ottavat puhelinnumeron kansainvälisessä numeromuodossa.

Yleiset virheet

  • Yhteystietojen tunnistaminen pelkän wa_id-kentän varassa. Käyttäjä, jolla on käyttäjänimi ja jonka kanssa numeroon ei ole ollut yhteyttä 30 päivään, saapuu vain user_id- ja from_user_id-kentillä, joten käsittelijä, joka vaatii wa_id-kentän, ohittaa viestin.
  • BSUID:n maakoodin poistaminen. Meta vaatii koko arvon, maakoodi ja piste mukaan lukien, ja pyyntö, jossa mikä tahansa osa on muutettu, epäonnistuu.
  • user_id_update-kentän odottaminen. Metalla sitä ei ole: BSUID-muutokset saapuvat messages-kenttään järjestelmäviesteinä tyyppiä user_changed_number tai user_changed_user_id.
  • Coexistence-kaikujen yhdistäminen vain to-kentän perusteella. smb_message_echoes-webhookissa to-kenttä voidaan jättää pois, joten sovelluksessa kirjoitettu vastaus jää huomaamatta, ellei to_user_id ole myös yhdistetty.
Näin teet tämän EasyCoexistencen avulla

get_api_credentials antaa koodillesi tarvittavat tiedot vastata recipient-kentällä. Jokaista yhteyttä valvotaan ympäri vuorokauden. Hinta on US$ 9 ja laskee US$ 0,75:een per yhteys kuukaudessa, kun yhteyksiä lisätään, ja ensimmäiset 3 päivää ovat ilmaisessa kokeilussa.

Usein kysytyt kysymykset

Saavatko käyttäjät ilman käyttäjänimeä myös BSUID:n?

Kyllä. Meta asettaa user_id-kentän messages-webhookeihin riippumatta siitä, onko käyttäjällä käyttäjänimi, joten useimmat käyttäjät saapuvat sekä puhelinnumeron että BSUID:n kanssa.

Voiko Coexistence-numerolla olla yrityksen käyttäjänimi?

Kyllä. Kesäkuun 29. päivästä 2026 alkaen yritys voi ottaa tai vaihtaa sen Meta Business Suitessa, WhatsApp Managerissa, WhatsApp Business -sovelluksessa tai Username API:ssa. Se ei piilota yrityksen numeroa, ja business_username_updates raportoi jokaisen tilamuutoksen.

Toimiiko BSUID eri Business Portfolio -kokonaisuuksien yli?

Ei. BSUID kuuluu yhdelle kokonaisuudelle ja käyttäjälle, eikä toisen kokonaisuuden numero voi lähettää sille viestejä. Metan liittämät hallinnoidut yritykset saavat emo-BSUID:t, joissa maakoodin jälkeen on ENT, ja ne toimivat liitettyjen kokonaisuuksien yli.

Kuinka paljon easyCoexistence maksaa WhatsApp-numerosta?

Hinta on US$ 9 ja laskee US$ 0,75:een yhteyttä kohden kuukaudessa riippuen yhteyksien määrästä, ja ensimmäiset 3 päivää ovat ilmaisessa kokeilussa. Metan omat viestimaksut menevät edelleen WhatsApp Business -tilisi maksutavalle.

Lue lisää

Valmis aloittamaan?

Ota WhatsApp Coexistence käyttöön minuuteissa, ei kuukausissa. Sovellus toimii edelleen puhelimessa.

Aloita ilmainen kokeilu

Vahvistettu