התחברותהתחילו תקופת ניסיון
Meta Tech Provider

שמות משתמש ב-WhatsApp ומזהי BSUID: מה משתנה בוובהוקים (Webhook) של Cloud API

שמות משתמש ב-WhatsApp מאפשרים להציג שם במקום מספר הטלפון, ולכן מאז תחילת אפריל 2026 הוובהוקים של הודעות Cloud API כוללים גם מזהה משתמש המוגבל לעסק (BSUID), כמו US.13491208655302741918, והשדות user_id וגם from_user_id נושאים אותו. אצל משתמש עם שם משתמש שלא הייתה איתו הודעה או שיחה במספר ב-30 הימים האחרונים ואינו מופיע בספר אנשי הקשר, השדה wa_id והשדה from מושמטים.

easyCoexistence מחברת מספר של אפליקציית WhatsApp Business ל-Cloud API דרך Coexistence, ומנתבת את הוובהוקים messages וגם smb_message_echoes לנקודת הקצה שלכם כפי ש-Meta שולחת אותם, כולל שדות BSUID.

April 2026

מתי התחילו להופיע מזהי BSUID בוובהוקים של Cloud API, לפני שמשתמשי WhatsApp הגיעו לשמות משתמש.

July 2026

מתי ה-APIs התחילו לקבל הודעות שנשלחות ל-BSUID, עם הנמען בשדה recipient במקום בשדה to.

30 days

חלון הזמן לכל מספר טלפון עסקי, שבו כל הודעה או שיחה עם המשתמש שומרת את מספרו בוובהוקים.

128

רוב התווים האלפאנומריים במזהה BSUID, אחרי קוד המדינה בן שתי האותיות והנקודה.

131062

שגיאת Messages API: נמענים מסוג Business-scoped User ID (BSUID) אינם נתמכים להודעה הזו.

user_changed_user_id

השדה previous_user_id מכיל את ה-BSUID הישן, בהודעת מערכת לשינוי BSUID שמדווחת בלי מספר טלפון.

מה הם שמות משתמש ב-WhatsApp ומזהי BSUID?

שם משתמש הוא שם ייחודי ואופציונלי שמשתמש WhatsApp יכול לקבוע, והוא מוצג באפליקציה במקום מספר הטלפון; Meta משיקה שמות משתמש בהדרגה במהלך 2026. BSUID הוא מזהה צד-שרת ש-Meta הוסיפה כדי שעסקים יוכלו עדיין להבחין בין משתמשים: הוא נוצר אוטומטית, ייחודי לכל זוג של Business Portfolio ומשתמש, ומורכב מקוד המדינה לפי ISO 3166 בן שתי האותיות, נקודה ועד 128 תווים אלפאנומריים. Meta מחייבת שותפים ועסקים עם חיבור ישיר לתמוך בו, מכיוון שאף עסק אינו שולט באימוץ שמות משתמש על ידי המשתמשים שלו.

אילו שדות נושאים את המזהים החדשים?

שדות חדשים לצד השדות שהחזיקו את מספר הטלפון, בוובהוקים messages, status, system וגם user_preferences. השדות ההוריים מופיעים רק עבור Business Portfolio ש-Meta רשמה לתוכנית parent BSUIDs, והם פועלים בין התיקים שנרשמו:

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

מתי מספר הטלפון מושמט?

כאשר למשתמש יש שם משתמש ואף אחד משלושת התנאים של Meta לא מתקיים. המספר נשאר בוובהוקים אם מספר הטלפון העסקי שלח הודעה או התקשר למספר של המשתמש ב-30 הימים האחרונים, קיבל ממנו הודעה או שיחה באותה תקופה, או שהמשתמש נמצא בספר אנשי הקשר של התיק. חלון ה-30 הימים נספר לכל מספר טלפון עסקי, כך שמספר שני באותו תיק עשוי לקבל רק את ה-BSUID של אותו משתמש. משתמשים בלי שם משתמש ממשיכים להגיע עם מספר הטלפון וה-BSUID שלהם יחד.

איך נראית הודעה נכנסת כעת?

כמו קודם, עם ה-BSUID לצד מספר הטלפון או במקומו. בדוגמה של Meta למשתמש עם שם משתמש שמספרו לא ניתן לשיתוף, השדה contacts כולל את profile.name, את profile.username ואת user_id, וההודעה נושאת את from_user_id במקום השדה 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?" }
        }]
      }
    }]
  }]
}

איך משתנים וובהוקי הסטטוס?

סטטוסים של נשלח, נמסר ונקרא מקבלים מערך contacts עם שם המשתמש, השדה user_id, השדה wa_id כשניתן לשתף את המספר, וגם השדה username בסטטוסי נמסר ונקרא. בתוך הסטטוסים, השדה recipient_user_id נושא את ה-BSUID, והשדה recipient_id מושמט כששלחתם ל-BSUID ואי אפשר לשתף את המספר. סטטוס של כשל אינו כולל מערך contacts, והשדה recipient_user_id מושמט כשההודעה נשלחה למספר טלפון, ולכן קשרו כשלים למזהה ההודעה.

איך שומרים ומתאימים משתמשים?

לפי ה-BSUID קודם, ומספר הטלפון כמפתח שני בכל פעם שהוא מגיע. שמרו את ה-BSUID המלא כמחרוזת, כולל קוד המדינה והנקודה, כי Meta דוחה בקשות שמשנות כל חלק בו, ושמרו גם את ה-BSUID ההורה אם התיקים שלכם רשומים. חברו רשומות קיימות לפי wa_id כל עוד הוא מגיע, ושמרו את ה-BSUID לצדן, כי משתמש שמאמץ שם משתמש מאוחר יותר עשוי לחזור בלי מספר. ה-FAQ של Meta מבקש את אותן חיבורים ב-CRM ובכלים שמזינים אותם.

מה קורה כששינוי מספר הטלפון של משתמש?

ה-BSUID שלו נוצר מחדש, והשינוי מגיע בוובהוק messages כהודעת מערכת, כי ל-Meta אין שדה user_id_update להירשם אליו. השדה system.type הוא user_changed_number כשניתן לשתף איתכם את המספר החדש, או user_changed_user_id כשניתן לדווח רק על שינוי ה-BSUID. השדה system.user_id מכיל את ה-BSUID החדש, והשדה system.previous_user_id את הישן, וכך הרשומה עוברת. טפלו בשני הסוגים.

איך משיבים למשתמש שמוכר רק לפי BSUID?

שולחים אל /<BUSINESS_PHONE_NUMBER_ID>/messages עם recipient מוגדר ל-BSUID ועם השדה to מושמט. כששניהם מופיעים, השדה to גובר וההשבה נשלחת למספר הטלפון. התגובה כוללת ב-contacts את input ו-user_id במקום wa_id. כל סוג הודעה עובד, חוץ מתבניות אימות מסוג one-tap, zero-tap או copy code, שדורשות מספר טלפון, ורק מספרים באותו תיק עסקי יכולים להגיע ל-BSUID. שגיאה 131062 פירושה שסוג ההודעה לא מקבל נמענים שהם 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." }
}

איך מבקשים ממשתמש את מספר הטלפון שלו?

בעזרת הכפתור REQUEST_CONTACT_INFO, שנוסף לתבנית שירות או שיווק או נשלח כהודעה אינטראקטיבית מסוג request_contact_info. משתמש שלוחץ עליו משתף את המספר בשרשור, ומגיע וובהוק contacts עם origin בערך contact_request והמספר ב-phones[].wa_id. איש קשר ששותף ידנית מגיע עם origin בערך other ובצירוף קובץ vCard. Meta הפעילה את הכפתור בתחילת יולי 2026, ואי אפשר להתאים את התווית שלו.

מה זה ספר אנשי הקשר?

מאגר ש-Meta מארחת לכל Business Portfolio, ללא עבודת אינטגרציה: ברגע שמספר טלפון עסקי שולח הודעה, מתקשר למשתמש, או מקבל ממנו הודעה או שיחה, המספר וה-BSUID נשמרים ומשמשים למילוי וובהוקים שמגיעים אחר כך במספר הטלפון, בין שיש שם משתמש ובין שאין. נספרות רק אינטראקציות שאחרי ההשקה שלו. אפשר לכבות אותו ב-Meta Business Suite, תחת Business settings ו-Business info, וזה מוחק את התוכן שלו. הנתיב GET או DELETE אל /<BUSINESS_PHONE_NUMBER_ID>/contact_book עם bsuid בודק או מסיר רשומה אחת.

מה אינטגרציית Coexistence צריכה לשנות?

הטיפול שלה בשלושת הוובהוקים שרק מספר Coexistence מקבל, גם הם משתנים. בהיסטוריה, לכל שרשור נוסף אובייקט context עם wa_id, user_id וגם username, והודעותיו מקבלות שדה from_user_id. בוובהוק smb_message_echoes נוסף מערך contacts, ואפשר להשמיט את message_echoes[].to, כשהשדה to_user_id נושא את ה-BSUID. עריכות וביטולים שנעשו באפליקציית WhatsApp Business מגיעים באותו אופן. בוובהוק smb_app_state_sync אפשר להשמיט את phone_number של איש קשר, כשלצדו מופיעים user_id וגם username. התאימו את ה-echoes ואת הצ'אטים המיובאים לפי user_id, לצד המספר.

איך בודקים לפני שמשתמשים מאמצים שמות משתמש?

בכלי הבדיקה של Meta ב-App Dashboard: תחת Use cases, Connect with customers through WhatsApp, Customize, Configuration, הקישור Test שליד הוובהוק messages שולח דוגמה לנקודת הקצה שלכם. הוא מכסה הודעות נכנסות וסטטוסים בארבעה תרחישים:

  • משתמש ללא שם משתמש: שדות BSUID ומספר טלפון, בלי שם משתמש.
  • משתמש עם שם משתמש שמספרו אינו זמין: שם משתמש ו-BSUID, ללא שדות מספר טלפון.
  • משתמש עם שם משתמש שמספרו זמין: שם משתמש, BSUID ומספר טלפון.
  • תיק שנרשם לתוכנית parent BSUIDs: BSUID הורה לצד ה-BSUID של התיק עצמו.

איך easyCoexistence מטפלת ב-BSUID?

מעבירה אותם הלאה כפי ש-Meta שולחת אותם. מספר שמנותב לנקודת הקצה שלכם באמצעות set_webhook_destination מקבל את הוובהוקים messages וגם smb_message_echoes ישירות מ-Meta, כולל user_id, from_user_id, to_user_id וגם username. וכשהאוטומציות או ההעברה פעילות, easyCoexistence מעבירה את הערך ש-Meta שלחה ללא שינוי. כדי להשיב ל-BSUID, הקוד שלכם משתמש ב-get_api_credentials, שמחזיר את מזהה מספר הטלפון, את נקודת הקצה לשליחה שלו ואת האסימון שלכם כשהוא זמין. הכלים send_message וגם send_template מקבלים מספר טלפון בספרות בינלאומיות.

טעויות נפוצות

  • קישור אנשי קשר לפי wa_id בלבד. משתמש עם שם משתמש שלא הייתה איתו מגע במספר ב-30 הימים האחרונים מגיע עם השדות user_id וגם from_user_id בלבד, וקוד שדורש wa_id מפספס את ההודעה.
  • קיצוץ קוד המדינה ב-BSUID. Meta דורשת את הערך המלא, כולל קוד המדינה והנקודה, ובקשה שבה שונה חלק כלשהו ממנו נכשלת.
  • המתנה לשדה user_id_update. ל-Meta אין שדה כזה: שינויי BSUID מגיעים בוובהוק messages כהודעות מערכת מסוג user_changed_number או user_changed_user_id.
  • התאמת ה-echoes של Coexistence לפי to בלבד. בוובהוק smb_message_echoes השדה to יכול להיעדר, כך שתשובה שנכתבה באפליקציה לא תיראה לכם אלא אם גם to_user_id מותאם.
עושים את זה עם EasyCoexistence

בעזרת get_api_credentials הקוד שלכם מקבל את מה שצריך כדי להשיב לפי recipient. כל חיבור נמצא תחת ניטור 24/7. US$ 9 עד US$ 0.75 לחיבור בחודש, והמחיר יורד ככל שמוסיפים חיבורים, עם 3 הימים הראשונים בחינם.

שאלות נפוצות

האם למשתמשים בלי שם משתמש יש גם BSUID?

כן. Meta מגדירה את user_id בוובהוקים messages בין אם למשתמש יש שם משתמש ובין אם לא, כך שרוב המשתמשים מגיעים עם מספר הטלפון וה-BSUID שלהם יחד.

האם למספר Coexistence יכול להיות שם משתמש עסקי?

כן. מאז 29 ביוני 2026 עסק יכול לאמץ או לשנות שם כזה ב-Meta Business Suite, ב-WhatsApp Manager, באפליקציית WhatsApp Business או דרך Username API. הוא אינו מסתיר את מספר העסק, והוובהוק business_username_updates מדווח על כל שינוי סטטוס.

האם BSUID עובד בין Business Portfolio שונים?

לא. BSUID שייך לתיק ולמשתמש אחד, ומספר בתיק אחר אינו יכול לשלוח הודעה אליו. עסקים מנוהלים ש-Meta רושמת מקבלים parent BSUIDs, עם ENT אחרי קוד המדינה, שפועלים בין התיקים שנרשמו.

כמה עולה easyCoexistence למספר WhatsApp?

US$ 9 עד US$ 0.75 לחיבור בחודש, לפי מספר החיבורים שלכם, עם 3 הימים הראשונים בחינם. חיובי ההודעות של Meta עצמם נשארים בשיטת התשלום של חשבון WhatsApp Business שלכם.

המשיכו לקרוא

מוכנים להתחיל?

מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.

התחילו תקופת ניסיון בחינם

נבדק ב-