كيفية استيراد سجل محادثات تطبيق WhatsApp Business وجهات الاتصال عبر واجهة برمجة التطبيقات (API)
يمكن لرقم تطبيق WhatsApp Business المتصل عبر Coexistence إرسال جهات اتصاله الحالية وما يصل إلى 180 يومًا من المحادثات الفردية إلى API مرة واحدة، خلال 24 ساعة من الإعداد. تصل جهات الاتصال عبر خطاف الويب (webhook) بالحقل smb_app_state_sync، وتصل المحادثات عبر webhook بالحقل history، على أجزاء مرتبة بحسب metadata.chunk_order، ويدل metadata.progress عند القيمة 100 على اكتمال الاستيراد. يختار النشاط التجاري داخل التطبيق ما إذا كان سيشارك المحادثات.
يربط easyCoexistence أرقام تطبيق WhatsApp Business لعملائك عبر Coexistence، ويطلب من Meta جهات اتصالهم وسجل محادثاتهم لحظة تجهيز خطاف الويب الخاص بك، فينتقل السجل مباشرة إلى نقطة النهاية دون تخزينه في الطريق، مع مراقبة كل رقم على مدار الساعة.
المدى الزمني الذي تصل إليه خطافات السجل، محسوبًا من وقت إعداد النشاط التجاري على Cloud API.
المدة بعد الإعداد التي يجب خلالها مزامنة جهات اتصال النشاط التجاري وسجل رسائله.
رمز الخطأ في خطاف السجل عندما يكون النشاط التجاري قد أوقف مشاركة السجل في تطبيق WhatsApp Business.
عدد المرات التي يمكن أن تعمل فيها كل مزامنة، ولتكرارها يحتاج العميل إلى إلغاء الربط وإكمال Embedded Signup مرة أخرى.
القيمة التي تدل على اكتمال مزامنة السجل.
كيف يبدأ الاستيراد؟
يبدأ بوجهة webhook على الرقم. عند الاتصال مع webhook_url مضبوطًا مسبقًا في جلسة الربط، أو عند تعيينه باستخدام PUT /connections/{id}/webhook خلال 24 ساعة من الاتصال، يطلب easyCoexistence البيانات من Meta مرة واحدة: POST /{phone_number_id}/smb_app_data مع sync_type بالقيمة smb_app_state_sync لجهات الاتصال، ثم history للمحادثات، وهو الترتيب الذي توثّقه Meta. يسجل سجل أحداث الرقم history_sync_requested مع قيم request_id من Meta للدعم، أو history_sync_failed مع السبب.
ما الذي تحمله webhooks جهات الاتصال؟
الحقل smb_app_state_sync مع مصفوفة state_sync في القيمة. يحمل كل عنصر النوع contact، وكائن جهة اتصال يضم full_name وfirst_name وphone_number، وإجراء add أو remove، وmetadata.timestamp. تُحذف الأسماء عند remove. تواصل Meta إرسال هذه الخطافات بعد الاستيراد كلما أضاف النشاط التجاري جهة اتصال أو عدّلها أو حذفها في تطبيق WhatsApp Business، فيبقى دفتر العناوين متزامنًا مع الهاتف.
ما الذي تحمله webhooks السجل؟
الحقل history مع مصفوفة history في القيمة. يحمل كل عنصر metadata، فيه phase وchunk_order وprogress، وthreads، واحدًا لكل عميل: معرّف الخيط هو رقم العميل، وmessages تسرد تلك المحادثة الفردية، الواردة والصادرة، مع from الذي يحدد الطرف المُرسِل لكل رسالة. تحمل الرسالة id وtimestamp وtype، ومحتواها تحت اسم النوع، وhistory_context.status مثل READ أو DELIVERED. لا تُدرج المحادثات الجماعية.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WABA_ID>",
"changes": [
{
"field": "history",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
"history": [
{
"metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
"threads": [
{
"id": "<CUSTOMER_NUMBER>",
"messages": [
{
"from": "<CUSTOMER_NUMBER>",
"id": "wamid.<ID>",
"timestamp": "1790726400",
"type": "text",
"text": { "body": "<MESSAGE_TEXT>" },
"history_context": { "status": "READ" }
}
]
}
]
}
]
}
}
]
}
]
}كيف تُستورد الوسائط؟
أولًا كعناصر نائبة. تصل رسالة الوسائط بالنوع media_placeholder، بلا محتوى ولا معرّف وسائط. ثم ترسل Meta خطافات history منفصلة تحمل معرّفات الوسائط، لكن فقط للوسائط المرسلة خلال 14 يومًا من الإعداد، فاجلب تلك الملفات من Meta باستخدام رمز الوصول (token) الخاص بالعميل. الوسائط الأقدم من ذلك تبقى عنصرًا نائبًا، فاعرضها كمرفق غير متاح بدلًا من ترك فجوة في الخيط.
بأي ترتيب تصل الأجزاء، ومتى ينتهي الاستيراد؟
ليس بالضرورة بالترتيب. تقسم Meta المحادثات إلى ثلاث مراحل، من الأحدث إلى الأقدم: المرحلة 0 هي اليوم السابق للإعداد، والمرحلة 1 تصل إلى اليوم 90، والمرحلة 2 إلى اليوم 180. قد تصل الأجزاء خارج التسلسل، لذا رتّبها بحسب metadata.chunk_order. تمثل metadata.progress النسبة المئوية للمزامنة كلها، والقيمة 100 تعني اكتمالها، ورقم المرحلة وحده لا يدل على انتهاء المرحلة.
ماذا لو رفض النشاط التجاري مشاركة المحادثات؟
أثناء الاتصال يسأل تطبيق WhatsApp Business النشاط التجاري عما إذا كان سيشارك سجل محادثاته. يصل الرفض كخطاف history بلا رسائل ومعه مصفوفة errors، رمزها 2593109، وعنوانها: أوقف النشاط التجاري مزامنة السجل من WhatsApp Business App. تستمر جهات الاتصال في الوصول، وتتدفق الرسائل المباشرة بشكل طبيعي منذ لحظة اتصال الرقم.
هل يمكن تشغيل الاستيراد مرة أخرى؟
ليس على الاتصال نفسه. تسمح Meta بمزامنة واحدة فقط لكل اتصال، خلال 24 ساعة من الإعداد، ولا يمكن إعادة تشغيلها. لتشغيلها مرة أخرى يلزم أن يفصل العميل الرقم ثم يربطه من جديد، فيُعد ذلك إعدادًا جديدًا. ومع بقاء وجهتك محفوظة، يطلب easyCoexistence الاستيراد مجددًا، لذا أزل التكرار باستخدام id لكل رسالة. ويشمل ذلك عودة الرقم بعد قاعدة الـ14 يومًا.
ماذا يجب أن يكون جاهزًا قبل إرسال رابط الربط؟
نقطة النهاية (endpoint) الخاصة بك، تعمل وتستجيب. تتحقق Meta من الرابط عبر مصافحة GET عند تطبيق الوجهة، ويُطلب الاستيراد مرة واحدة مباشرة بعدها. إذا فشلت المصافحة، يبقى الرقم متصلًا لكن بلا وجهة، ويشرح last_error في الجلسة السبب، ولا يُستورد شيء ما لم تصلح نقطة النهاية وتعيّنها باستخدام PUT /connections/{id}/webhook خلال 24 ساعة. أما الرقم بلا webhook_url فلا يحصل على أي استيراد، لأن المحتوى المرسل إلى easyCoexistence يُتجاهل.
كيفية إعداده
- Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
- Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
- Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
- Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.
الأخطاء الشائعة
- رفض الأجزاء الكبيرة من السجل. قد تبلغ حمولات Meta 3 MB، بينما يحلل Express بيانات JSON حتى 100 KB افتراضيًا، فارفع الحد وإلا تفشل الأجزاء وتواصل Meta إعادة المحاولة.
- معالجة الأجزاء بترتيب الوصول. قد تصل خارج التسلسل، لذا رتّبها بحسب metadata.chunk_order وانتظر progress 100 قبل اعتبار الاستيراد مكتملًا.
- إدراج السجل دون إزالة التكرار. قد تتداخل الرسائل المباشرة مع الاستيراد، وإعادة الاتصال تشغّله من جديد، لذا اربط كل رسالة بمعرّفها id.
- إرسال رابط الربط قبل أن تستجيب نقطة النهاية لمصافحة Meta. عندئذ لا تُطبَّق الوجهة، وما لم تعيّنها خلال 24 ساعة فلن يُستورد سجل الرقم أبدًا.
من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويتناقص السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
ما المدى الزمني الذي يصل إليه استيراد سجل محادثات WhatsApp؟
حتى 180 يومًا قبل ربط الرقم بـ Cloud API، ويشمل المحادثات الفردية في الاتجاهين.
هل تُستورد المحادثات الجماعية؟
لا. تستثني Meta الرسائل التي تكون جزءًا من محادثة جماعية.
هل تصل محادثات WhatsApp القديمة للعميل إلى webhook الخاص بي؟
نعم، حتى 180 يومًا من المحادثات الفردية، تُرسل مرة واحدة خلال 24 ساعة من الإعداد، إذا اختار النشاط التجاري داخل التطبيق مشاركتها.
هل يحتفظ easyCoexistence بنسخة من المحادثات المستوردة؟
لا. ترسل Meta السجل مباشرة إلى webhook_url الخاص بك، مثل الرسائل المباشرة، ولا يُخزَّن شيء في الطريق.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في