تسجيل الدخولابدأ الفترة التجريبية المجانية
Meta Tech Provider

أسماء مستخدمي WhatsApp ومعرّفات BSUID: ما يتغيّر في خطّاف الويب (webhooks) لـ Cloud API

تتيح أسماء المستخدمين (usernames) في WhatsApp عرض اسم بدلاً من رقم الهاتف، ولذلك تحمل webhooks الخاصة برسائل Cloud API منذ أوائل أبريل 2026 معرّف المستخدم على مستوى النشاط التجاري (BSUID)، مثل US.13491208655302741918، في الحقلين user_id وfrom_user_id. أما مستخدم لديه اسم مستخدم ولم تجرِ بينه وبين الرقم أي رسالة أو مكالمة خلال 30 يوماً وليس في دفتر جهات الاتصال، فيُحذف الحقلان wa_id وfrom.

يربط easyCoexistence رقم تطبيق WhatsApp Business بـ Cloud API عبر Coexistence، ويوجّه webhooks الرسائل وsmb_message_echoes إلى endpoint الخاص بك كما ترسلها Meta، بما فيها حقول BSUID، بينما تمنح get_api_credentials كودك ما يحتاجه للرد بالحقل recipient.

April 2026

متى بدأت معرّفات BSUID تظهر في webhooks الخاصة بـ Cloud API، قبل وصول أسماء المستخدمين إلى مستخدمي WhatsApp.

July 2026

متى بدأت واجهات برمجة التطبيقات (API) قبول الرسائل المُرسلة إلى BSUID، عبر الحقل recipient بدلاً من to.

30 days

فترة المراجعة الرجعية، لكل رقم هاتف للنشاط التجاري، التي تُبقي فيها أي رسالة أو مكالمة مع المستخدم رقمه ظاهراً في webhooks.

128

الحد الأقصى لعدد الأحرف الأبجدية الرقمية التي تلي رمز الدولة المكوّن من حرفين والنقطة في BSUID.

131062

خطأ في Messages API: المستلمون بمعرّف المستخدم على مستوى النشاط التجاري (BSUID) غير مدعومين لهذه الرسالة.

user_changed_user_id

نوع رسالة النظام عند تغيّر BSUID دون الإبلاغ عن رقم هاتف، مع BSUID القديم في previous_user_id.

ما هي أسماء المستخدمين في WhatsApp ومعرّفات BSUID؟

اسم المستخدم (username) اسم اختياري وفريد يمكن لمستخدم WhatsApp تعيينه، فيظهر في التطبيق بدلاً من رقم الهاتف، وتطرحه Meta تدريجياً خلال عام 2026. أما BSUID فهو معرّف داخلي أضافته Meta كي تستطيع الأنشطة التجارية التمييز بين مستخدميها، ويُولَّد تلقائياً، وهو فريد لكل زوج من Business Portfolio ومستخدم، ويُكتب على شكل رمز الدولة المكوّن من حرفين وفق ISO 3166، ثم نقطة، ثم ما يصل إلى 128 حرفاً أبجدياً رقمياً. وتشترط Meta على الشركاء والأنشطة التجارية المتكاملة مباشرة دعمه، لأن أي نشاط تجاري لا يتحكم في تبنّي مستخدميه لأسماء المستخدمين.

أي الحقول تحمل المعرّفات الجديدة؟

خصائص جديدة إلى جانب الحقول التي كانت تحمل رقم الهاتف، في webhooks الخاصة بـ messages و status و system و user_preferences. وتظهر حقول parent فقط لمحافظ Business Portfolio التي أدرجتها Meta في معرّفات BSUID الأصلية (parent BSUID)، وهي معرّفات تعمل عبر المحافظ المدرجة:

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 الثلاثة. يبقى الرقم في webhooks إذا راسل رقم هاتف النشاط التجاري رقم المستخدم أو اتصل به خلال آخر 30 يوماً، أو تلقى منه رسالة أو مكالمة خلال هذه المدة، أو كان المستخدم في دفتر جهات الاتصال الخاص بالـ Business Portfolio. تُحسب فترة 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?" }
        }]
      }
    }]
  }]
}

كيف تتغير webhooks الحالة؟

تكتسب حالات الإرسال والتسليم والقراءة مصفوفة contacts تضم اسم المستخدم ومعرّف user_id وwa_id عندما يمكن مشاركة الرقم، وusername في حالتي التسليم والقراءة. وفي الحالات، يحمل recipient_user_id معرّف BSUID، ويُحذف recipient_id عند الإرسال إلى BSUID إذا تعذرت مشاركة الرقم. أما حالة الفشل فليس فيها مصفوفة contacts، ويُحذف منها recipient_user_id عندما تُرسل الرسالة إلى رقم هاتف، لذا اربط حالات الفشل بمعرّف الرسالة.

كيف تخزّن المستخدمين وتطابقهم؟

بمعرّف BSUID أولاً، مع رقم الهاتف كمفتاح ثانٍ كلما وصل. خزّن BSUID كاملاً كسلسلة نصية، برمز الدولة والنقطة، لأن Meta ترفض الطلبات التي تعدّل أي جزء منه، وخزّن أيضاً معرّف BSUID الأصلي إذا كانت محافظك مدرجة فيه. اربط السجلات الموجودة بـ wa_id ما دام يصل، واحتفظ بـ BSUID إلى جانبها، لأن المستخدم الذي يتبنى اسم مستخدم لاحقاً قد يعود دون رقم. وتطلب الأسئلة الشائعة لدى 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. يعمل أي نوع رسالة ما عدا قوالب المصادقة بنقرة واحدة وبدون نقرة (zero-tap) ونسخ الرمز، فهذه تحتاج رقم هاتف، ولا يمكن الوصول إلى BSUID إلا من أرقام داخل Business Portfolio نفسها. يعني الخطأ 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، يُضاف إلى قالب من فئة utility أو marketing، أو يُرسل كرسالة تفاعلية من نوع request_contact_info. عندما يضغط المستخدم عليه يشارك رقمه داخل المحادثة، ويصل webhook الخاص بـ contacts بقيمة origin هي contact_request، مع الرقم في phones[].wa_id. أما جهة الاتصال التي تُشارك يدوياً فتصل بقيمة origin هي other مع ملف vCard. أتاحت Meta الزر في أوائل يوليو 2026، ولا يمكن تخصيص تسميته.

ما دفتر جهات الاتصال؟

مخزن تستضيفه Meta لكل Business Portfolio دون أي عمل تكامل من جانبك: بمجرد أن يراسل رقم هاتف النشاط التجاري رقم المستخدم أو يتصل به أو يتلقى منه رسالة أو مكالمة، يُسجَّل ذلك الرقم وBSUID، ويُستخدمان لملء webhooks اللاحقة برقم الهاتف، سواء كان للمستخدم اسم مستخدم أم لا. ولا تُحسب إلا التفاعلات التي تلت إطلاقه. ويمكن إيقافه من Meta Business Suite ثم إعدادات النشاط التجاري ثم معلومات النشاط التجاري، وهذا يحذف ما يحتويه، كما أن GET أو DELETE على /<BUSINESS_PHONE_NUMBER_ID>/contact_book مع bsuid يتحقق من إدخال واحد أو يحذفه.

ما الذي ينبغي أن يغيّره تكامل Coexistence؟

معالجته لثلاثة webhooks لا يتلقاها إلا رقم Coexistence، وهي تتغير أيضاً. في history يكتسب كل خيط محادثة كائن 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 بجانبه. طابق الأصداء والمحادثات المستوردة على user_id إلى جانب الرقم.

كيف تختبر قبل أن يتبنى المستخدمون أسماء المستخدمين؟

بأداة الاختبار من Meta في لوحة تحكم التطبيق: ضمن Use cases، ثم Connect with customers through WhatsApp، ثم Customize، ثم Configuration، يرسل رابط Test بجوار webhook الرسائل عينة إلى نقطة النهاية (endpoint) الخاصة بك. وتغطي الرسائل الواردة والحالات في أربعة سيناريوهات:

  • مستخدم بلا اسم مستخدم: حقول BSUID ورقم الهاتف، دون username.
  • مستخدم لديه اسم مستخدم ولا يتوفر رقمه: username وBSUID، دون حقول رقم الهاتف.
  • مستخدم لديه اسم مستخدم ويتوفر رقمه: username وBSUID ورقم الهاتف.
  • Business Portfolio مدرجة في معرّفات BSUID الأصلية: معرّف BSUID أصلي إلى جانب معرّف BSUID الخاص بالمحفظة.

كيف يتعامل easyCoexistence مع معرّفات BSUID؟

ينقلها كما ترسلها Meta. الرقم الذي يُوجَّه إلى endpoint الخاص بك عبر set_webhook_destination تصله webhooks الرسائل وsmb_message_echoes مباشرة من Meta، بما فيها user_id وfrom_user_id وto_user_id وusername، ومع تفعيل الأتمتة أو إعادة التوجيه يمرّر easyCoexistence القيمة التي أرسلتها Meta دون تغيير. وللرد على معرّف BSUID، يستخدم كودك get_api_credentials الذي يعيد معرّف رقم الهاتف، وendpoint الإرسال، ورمز الوصول (token) الخاص بك عند توفره؛ وتأخذ أدوات 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.
  • مطابقة أصداء Coexistence على to وحده. في smb_message_echoes قد يُترك الحقل to دون قيمة، فلا يُرى الرد المكتوب من التطبيق إلا إذا طُوبق to_user_id أيضاً.
إنجاز ذلك باستخدام EasyCoexistence

يُراقَب كل اتصال على مدار الساعة (24/7). من US$ 9 إلى US$ 0.75 لكل اتصال شهرياً، وينخفض السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.

الأسئلة الشائعة

هل يحصل المستخدمون بلا اسم مستخدم على BSUID أيضاً؟

نعم. تضع Meta user_id في webhooks الرسائل سواء كان للمستخدم اسم مستخدم أم لا، لذلك يصل معظم المستخدمين برقم هاتفهم وBSUID معاً.

هل يمكن أن يكون لرقم Coexistence اسم مستخدم تجاري؟

نعم. منذ 29 يونيو 2026 يمكن للنشاط التجاري تبنّي اسم مستخدم أو تغييره في Meta Business Suite أو WhatsApp Manager أو تطبيق WhatsApp Business أو عبر Username API؛ ولا يخفي الاسم رقم النشاط التجاري، ويُبلغ business_username_updates عن كل تغيّر في الحالة.

هل يعمل BSUID عبر محافظ Business Portfolio؟

لا. ينتمي BSUID إلى محفظة واحدة ومستخدم واحد، ولا يستطيع رقم في محفظة أخرى مراسلته. أما الأنشطة التجارية المُدارة التي تدرجها Meta فتحصل على معرّفات BSUID أصلية، تحمل ENT بعد رمز الدولة، وتعمل عبر المحافظ المدرجة لديها.

كم تبلغ تكلفة easyCoexistence لرقم WhatsApp؟

من US$ 9 إلى US$ 0.75 لكل اتصال شهرياً، حسب عدد اتصالاتك، وأول 3 أيام مجانية. تبقى رسوم الرسائل الخاصة بـ Meta على طريقة الدفع في حساب WhatsApp Business Account الخاص بك.

تابع القراءة

هل أنت مستعد للبدء؟

أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.

ابدأ الفترة التجريبية المجانية

تم التحقق في