يتلقّى وكيلك أحداث الويب هوك من منصة RBM، لإعلامك بكل من تفاعلات المستخدمين والتحديثات على مستوى المنصة.
يتم تصنيف هذه الأحداث حسب مصدرها:
- أحداث المستخدم: هي الإشعارات التي يتم إرسالها من جهاز المستخدم إلى وكيلك، وتشير إلى تفاعل مع وكيلك.
- أحداث المنصة: إشعارات بشأن تغييرات حالة إطلاق الوكيل وانتهاء صلاحية الرسائل التي ترسلها منصة RBM
للاطّلاع على تفاصيل حول أحداث الحالة التي يرسلها وكيلك إلى جهاز المستخدم، يُرجى الاطّلاع على مقالة إرسال الأحداث.
للحصول على تفاصيل حول كيفية التعامل مع رسائل المستخدمين، مثل النصوص والملفات والمواقع الجغرافية وغيرها، يُرجى الاطّلاع على تلقّي الرسائل.
أحداث المستخدم
أحداث المستخدم هي إشعارات من جهاز المستخدم تبلّغ عن حالة الرسالة أو تغييرات الاشتراك (أي أنّ المستخدم قد ألغى الاشتراك أو أعاد الاشتراك في تطبيق "رسائل Google").
للحصول على خيارات التنسيق والقيم الكاملة، يُرجى الاطّلاع على مرجع UserEvent.
يتلقّى المستخدم رسالة الوكيل
يشير هذا الحدث إلى أنّه تم تسليم رسالة بنجاح إلى جهاز المستخدم.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "DELIVERED",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}يقرأ المستخدم رسالة الوكيل
يشير هذا الحدث إلى أنّه تم فتح رسالة أو الإقرار بها.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "READ",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}يبدأ المستخدم الكتابة
يشير هذا الحدث إلى أنّ المستخدم يكتب ردًا.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "IS_TYPING",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}ينقر المستخدم على إجراء مقترَح
عندما ينقر المستخدم على إجراء مقترَح، يتلقّى وكيلك حدثًا يتضمّن بيانات تسجيل الإحالات الناجحة للإجراء.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}إلغاء المستخدم الاشتراك في المحادثة
يشير هذا الحدث إلى أنّ المستخدم قد ألغى الاشتراك في تلقّي الرسائل غير الضرورية، مثل الرسائل الترويجية، من وكيلك والمؤسسة التي يمثّلها. يبدأ المستخدمون هذا الحدث من خلال إلغاء الاشتراك في محادثة RBM في "رسائل Google".
في ما يلي مثال على حمولة JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}آلية عمل ميزة إلغاء الاشتراك
- يتوفّر دائمًا خيار إلغاء الاشتراك ضمن قائمة المحادثة. بالنسبة إلى الوكلاء الذين يرسلون رسائل ترويجية ومتعددة الاستخدامات، يظهر هذا الخيار أيضًا مباشرةً في المحادثة بعد عدد معيّن من الرسائل غير المقروءة (تختلف القواعد المحدّدة حسب البلد).
يؤدي اختيار إلغاء الاشتراك إلى تنفيذ إجراءَين في الوقت نفسه: يرسل تطبيق "رسائل Google" كلمة رئيسية خاصة بالبلد (على سبيل المثال، "إيقاف") إلى وكيلك، وترسل منصة "مراسلة المؤسسات من خلال خدمات الاتصالات التفاعلية (RBM)" الحدث
UNSUBSCRIBEإلى الويب هوك.يتم تحديد الكلمة الرئيسية من خلال رمز البلد المكوّن من حرفَين لرقم هاتف المستخدم. يسرد الجدول التالي الكلمات الرئيسية لكل بلد متوافق.
البلد (رمز البلد) كلمة رئيسية لإلغاء الاشتراك الولايات المتحدة (US) والهند (IN) والمملكة المتحدة (GB) وألمانيا (DE) وهولندا (NL) STOP إسبانيا (ES) والمكسيك (MX) BAJA فرنسا (FR) STOP البرازيل (BR) parar بعد إلغاء المستخدم الاشتراك، تبقى المحادثة في بريده الوارد ما لم يتم الإبلاغ عنها كرسالة غير مرغوب فيها، وفي هذه الحالة يتم نقلها إلى مجلد الرسائل غير المرغوب فيها والمحظورة.
لتحديد انتهاكات السياسات وقواعد النشاط التجاري، تراقب Google أنماط الرسائل بعد إلغاء المستخدم الاشتراك.
قواعد العمل
- بصفتك شريك RBM الذي يدير هذه المحادثة، تقع على عاتقك مسؤولية الامتثال لطلب المستخدم بإلغاء الاشتراك.
- إذا لم تتمكّن من إلغاء الاشتراك ضمن سلسلة الرسائل، عليك إرسال رسالة تأكيد فورًا تتضمّن رابطًا مباشرًا إلى الموقع الإلكتروني أو التطبيق حيث يمكن للمستخدمين إدارة خياراتهم المفضّلة بشأن الاشتراك.
- بعد إلغاء المستخدم الاشتراك، يُحظر إرسال رسائل غير ضرورية.
- ولا يزال مسموحًا بالرسائل الأساسية. وتشمل هذه الميزات ما يلي:
- عمليات المصادقة، مثل كلمات المرور الصالحة لمرة واحدة (OTP)
- إشعارات حول خدمة معيّنة طلبها المستخدم ووافق عليها
- تأكيد طلب المستخدم بإلغاء الاشتراك، مع معلومات لإدارة خياراته المفضّلة بشأن التواصل بشكل أكبر
مثال
إذا ألغى مستخدم اشتراكه في وكيل شركة طيران حالة استخدامه متعدّدة الاستخدامات، يجب التوقف عن إرسال الرسائل التسويقية. ومع ذلك، يمكنك إرسال إشعارات بشأن الرحلات الجوية إذا قدّم المستخدم موافقة صريحة على تلقّي إشعارات بشأن تلك الرحلة الجوية المحدّدة.
أسباب إلغاء الاشتراك
عندما يلغي مستخدم اشتراكه في وكيلك، يمكنه اختيار سبب من بين الخيارات التالية:
- رسائل كثيرة للغاية
- لم أشترك في هذه الخدمة
- لم أعُد أريد الاشتراك
- يبدو ذلك كأنه عملية خداع
- غير ذلك
للحد من الانحياز في الاختيار، يتم عرض الخيارات الأربعة الأولى بترتيب عشوائي لكل مستخدم. ويظل هذا الترتيب ثابتًا في جميع زيارات المستخدم، ويظل الخيار غير ذلك ثابتًا في أسفل القائمة.
يتم تجميع أسباب إلغاء الاشتراك وعرضها في نظرة عامة على الإحصاءات لمساعدتك في فهم سبب إلغاء المستخدمين لاشتراكاتهم.
يعيد المستخدم الاشتراك في المحادثة
يشير هذا الحدث إلى أنّ المستخدم يريد تلقّي رسائل من وكيلك مجددًا، بما في ذلك المحتوى غير الضروري مثل العروض الترويجية. يمكن للمستخدمين بدء هذا الحدث من خلال إعادة الاشتراك في محادثة ألغوا اشتراكهم فيها سابقًا في "رسائل Google".
في ما يلي مثال على حمولة JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}آلية عمل ميزة "إعادة الاشتراك"
- يتيح خيار اشتراك، المتوفّر من قائمة المحادثة ورابط داخل المحادثة، للمستخدمين إعادة الاشتراك في محادثة ألغوا اشتراكهم فيها.
يؤدي اختيار اشتراك إلى تنفيذ إجراءَين في الوقت نفسه: يرسل تطبيق "رسائل Google" كلمة رئيسية خاصة بالبلد (مثل "START") إلى وكيلك، وترسل منصة مراسلة المؤسسات من خلال خدمات الاتصالات التفاعلية (RBM) حدث SUBSCRIBE إلى الويب هوك. يتم تحديد الكلمة الرئيسية المحدّدة من خلال رمز البلد المكوّن من حرفَين لرقم هاتف المستخدم. يسرد الجدول التالي الكلمات الرئيسية لكل بلد معتمد.
البلد (رمز البلد) الكلمة الرئيسية "اشتراك" الولايات المتحدة (US) والهند (IN) والمملكة المتحدة (GB) وألمانيا (DE) وهولندا (NL) البدء إسبانيا (ES) والمكسيك (MX) ALTA فرنسا (FR) Démarrer البرازيل (BR) começar
قواعد العمل
- بصفتك شريك RBM الذي يدير هذه المحادثة، تقع على عاتقك مسؤولية الامتثال لطلب المستخدم بإعادة الاشتراك.
- تنطبق إعادة الاشتراك على جميع أنواع الرسائل، بما في ذلك المحتوى غير الضروري، مثل الرسائل الترويجية.
- إذا أرسل مستخدم رسالة إلى مؤسستك بعد إلغاء الاشتراك، يمكن اعتبار ذلك طلبًا لإعادة الاشتراك.
- إذا أعاد المستخدم الاشتراك خارج قناة المراسلة (على سبيل المثال، على موقعك الإلكتروني)، تقع على عاتقك كشريك في RBM مسؤولية تعديل حالته واستئناف إرسال الرسائل وفقًا لذلك.
أحداث المنصة
ترسل منصة RBM أحداث المنصة لإعلام وكيلك بالتغييرات التي تطرأ على حالة إطلاق الوكيل أو انتهاء صلاحية الرسائل.
تغيّرت حالة إطلاق الوكيل
ترسل منصة RBM طلب AgentLaunchEvent
لكل تغيير في حالة إطلاق وكيلك. على سبيل المثال، عندما تتغيّر حالة الوكيل من "PENDING" إلى "LAUNCHED". يتم تسليم الحدث كرسالة Pub/Sub. لتمييز هذا الحدث عن الأحداث الأخرى، يُرجى التحقّق من
مسار message.attributes.type بحثًا عن القيمة agent_launch_event.
إعدادات الويب هوك
يمكنك استخدام الويب هوك على مستوى الشريك أو الوكيل لتلقّي هذه الإشعارات.
المتطلبات الأساسية
- اضبط إعدادات الويب هوك لرسائل RBM (هذا شرط أساسي لتلقّي رسائل المستخدمين وأحداثهم).
- للتمييز بين أحداث المستخدم وأحداث حالة تشغيل الوكيل، تحقَّق من مسار
message.attributes.typeبحثًا عن القيمةagent_launch_event.
بنية حمولة الحدث
يتم تسليم AgentLaunchEvent كرسالة Pub/Sub.
وفي ما يلي مثال لذلك:
{
"message": {
"attributes": {
"business_id": "rbm-chatbot-id@rbm.goog",
"event_type": "REJECTED",
"product": "RBM",
"project_number": "3338881441851",
"type": "agent_launch_event"
},
"data": "....BASE64-encoded-JSON-with-notification...",
"messageId": "14150481888479752",
"message_id": "14150481888479752",
"publishTime": "2025-03-05T18:50:21.88Z",
"publish_time": "2025-03-05T18:50:21.88Z"
},
"subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}
يشير الحقل AgentLaunchEvent.LaunchState في حمولة الحدث إلى حالة الإطلاق الجديدة للوكيل. في ما يلي القيم المحتمَلة:
| القيمة | حالة إطلاق الوكيل | التفاصيل |
|---|---|---|
PENDING |
في انتظار المراجعة | تم إرسال الطلب إلى مشغّل شبكة الجوّال لمراجعته. |
LAUNCHED |
تم طرح الميزة. | يُسمح بالرسائل على مشغّل شبكة جوّال معيّن. |
REJECTED |
تم رفضه من قِبل مشغّل شبكة جوّال معيّن | يتم تحديد سبب الرفض في التعليق. |
SUSPENDED |
تم تعليقها على مشغّل شبكة جوّال معيّن | يتم تحديد سبب التعليق في التعليق. |
UNLAUNCHED |
لم يتم إطلاقها | يُسمح بالتعديل للوكلاء الذين تم إلغاء إطلاقهم من جميع مشغّلي شبكة الجوّال. |
يحتوي حقل البيانات على عنصر JSON بترميز Base64 يتضمّن تفاصيل حالة الإطلاق. في ما يلي مثال على ملف JSON الذي تم فك ترميزه:
{
"eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
"agentId": "rbm-chatbot-id@rbm.goog",
"botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
"brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
"brandDisplayName": "Chatbots brand",
"regionId": "/v1/regions/fi-rcs",
"oldLaunchState": "PENDING",
"newLaunchState": "REJECTED",
"actingParty": "rbm-support@google.com",
"comment": "Carrier has rejected the launch: policy violation",
"sendTime": "2025-03-05T18:50:19.386436Z"
}
تغييرات في حالة الإطلاق التي بدأها مشغّل شبكة الجوّال
في ما يلي عمليات النقل المسموح بها والتي يتعامل معها عادةً مشغّلو شبكات الجوّال أثناء عملية المراجعة والتنفيذ:
| حالة الإطلاق القديمة | حالة الإطلاق الجديدة | إجراء التشغيل |
|---|---|---|
PENDING |
LAUNCHED |
الموافقة على طلب إطلاق |
PENDING |
REJECTED |
رفض طلب إطلاق |
LAUNCHED |
SUSPENDED |
تعليق الحساب لأسباب تتعلق بالتنفيذ أو الإدارة |
SUSPENDED |
LAUNCHED |
استعادة وكيل إلى الحالة النشطة |
SUSPENDED |
UNLAUNCHED |
إنهاء وكيل |
REJECTED |
LAUNCHED |
الموافقة على طلب إطلاق تم رفضه سابقًا |
تغييرات في حالة الإطلاق بدأها الشريك
في ما يلي عمليات النقل المسموح بها والتي يتولّاها الشركاء عادةً:
| حالة الإطلاق القديمة | حالة الإطلاق الجديدة | إجراء التشغيل |
|---|---|---|
UNSPECIFIED |
PENDING |
أرسِل النموذج للمراجعة. |
PENDING |
UNLAUNCHED |
إلغاء طلب إطلاق في انتظار المراجعة |
UNLAUNCHED |
PENDING |
أرسِل النموذج للمراجعة. |
REJECTED |
PENDING |
أعِد إرسالها للمراجعة. |
SUSPENDED |
PENDING |
أعِد إرسالها للمراجعة. |
انتهت صلاحية الرسالة، وتم الإبطال بنجاح
يشير هذا الحدث إلى انتهاء مدة بقاء الرسالة (TTL) وإبطالها بنجاح. هذا مؤشر جيد لاستراتيجية المراسلة الاحتياطية.
للحصول على خيارات التنسيق والقيم الكاملة، يُرجى الاطّلاع على مرجع ServerEvent.
{
"phoneNumber": "PHONE_NUMBER",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID",
"eventType": "TTL_EXPIRATION_REVOKED",
"eventId": "EVENT_ID",
"sendTime": "TIMESTAMP"
}انتهت صلاحية الرسالة، وتعذّر إبطالها
يشير هذا الحدث إلى انتهاء صلاحية مدة صلاحية الرسالة، ولكن لم يتم إلغاؤها بنجاح.
للحصول على خيارات التنسيق والقيم الكاملة، يُرجى الاطّلاع على مرجع ServerEvent.
{
"phoneNumber": "PHONE_NUMBER",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID",
"eventType": "TTL_EXPIRATION_REVOKE_FAILED",
"eventId": "EVENT_ID",
"sendTime": "TIMESTAMP"
}لا نضمن تسليم الرسائل.
- إذا تم تسليم الرسالة، ستتلقّى حدث
DELIVEREDعلى الويب هوك. - إذا لم يتم تسليم الرسالة، استخدِم واجهة برمجة التطبيقات الخاصة بالإبطال من أجل إرسال طلب إبطال.
إذا كانت الرسالة حسّاسة للوقت، مثل كلمة مرور صالحة لمرة واحدة أو تنبيه بشأن عملية احتيال، من الأفضل إرسال الرسالة من خلال قناة بديلة مثل الرسائل القصيرة SMS حتى إذا أدّى ذلك إلى إرسال رسائل مكرّرة إلى المستخدم.