بعد التسجيل باستخدام ميزة "الرسائل التجارية"، يمكنك تلقّي رسائل نيابة عن وكيل الاختبار. يمكنك تلقّي رسائل حول العلامات التجارية التي تديرها بعد إنشاء وكيلة هذه العلامات التجارية وإثبات ملكيتها وإطلاقها.
عندما يرسل عميل رسالة إلى وكيل تديره، ترسل ميزة "الرسائل التجارية" حمولة بتنسيق JSON إلى الرد التلقائي على الويب تتضمّن معرّفات مختلفة ومحتوى الرسائل ومعلومات الموقع الجغرافي.
يُرجى استخدام صفحة سجلّات مطوّري البرامج لاتصالات الأنشطة التجارية لتصحيح أخطاء تسليم الرسائل.
التعامل مع الرسائل الواردة
تعتمد الطريقة التي يتعامل بها موظّف الدعم مع الرسائل التي يرسلها المستخدمون ويردّ عليها إلى حد كبير على منطق نشاطك التجاري. ومع ذلك، تكون خطوات الرد على رسالة المستخدم متسقة.
الإقرار بالرسالة
للإقرار برسالة مُستلَمة من خلال الرد التلقائي على الويب، يمكنك عرض استجابة HTTP صالحة على الرسائل المُرسلة إلى الرد التلقائي على الويب.
وفي حال تعذّر تسليم الرسالة بسبب انتهاء مهلة التسليم أو إمكانية الوصول إلى الرد التلقائي على الويب أو إعادة التوجيه أو مشاكل في الأذونات، تخزّن Google الرسالة وتعيد توجيهها، مع إعادة المحاولة عدة مرات، لمدة 7 أيام أو حتى يتلقّى الرد التلقائي على الويب الرسالة.
التأكّد من أن الرسالة واردة من Google
يجب عليك التحقق من أن Google أرسل الرسالة قبل معالجة محتوى الرسالة.
للتحقّق من أن Google أرسلت رسالة تلقيتها،
- تحليل عنوان الرسالة
X-Goog-Signature. وهي نسخة مجزّأة مشفّرة بتنسيق base64 من حمولة نص الرسالة. باستخدام الرمز المميّز للعميل (الذي تم تقديمه عند ضبط الردّ التلقائي على الويب) كمفتاح، أنشِئ رمز HMAC SHA512 لبايت حمولة الرسالة وشفّر النتيجة.
قارِن تجزئة
X-Goog-Signatureمع التجزئة التي أنشأتها.- وفي حال تطابق علامات التجزئة، أنت تؤكّد أنّ Google أرسلت الرسالة.
- وإذا لم تتطابق قيم التجزئة، يجب التحقّق من عملية التجزئة في رسالة معروفة. إذا كانت عملية التجزئة تعمل بشكل صحيح وتلقّيت رسالة تعتقد أنّه تم إرسالها إليك بطريقة احتيالية، يمكنك التواصل معنا (عليك تسجيل الدخول باستخدام حساب Google على ميزة "الرسائل التجارية").
يمكنك الاطّلاع على مثال التحقق من الرسالة في مستودعات GitHub لبرامج تتبُّع Echo في Java و Node.js وPython.
تحديد اللغة
يتواصل المستخدمون من العديد من المواقع الجغرافية بلغات متعددة. تمثّل ميزة "الرسائل التجارية"
إعدادات اللغة المفضّلة للمستخدمين في الحقلين resolvedLocale
وuserDeviceLocale، استنادًا إلى إعدادات اللغة في أجهزتهم.
يُرجى الاطّلاع على الأقلمة واللغات.
يمكنك توجيه الرسائل وإنشاء الردود استنادًا إلى الإعدادات المفضّلة للغة لدى المستخدمين كلما أمكن ذلك.
توجيه الرسالة استنادًا إلى سياقها
ويحدّد سياق الرسالة نوع المعلومات التي قد يبحث عنها المستخدم.
على سبيل المثال، إذا أرسل مستخدم رسالة ذات قيمة
placeId
، أرسل رسالة إلى موقع جغرافي محدّد (المشار إليه من خلال placeId) ومن المرجّح أن يطرح أسئلة متعلقة بالموقع الجغرافي. وبالمثل، إذا كانت الرسالة تحتوي على القيمة nearPlaceId، التي تحدّد موقعًا جغرافيًا بالقرب من المستخدم، من المرجّح أن يعرف المستخدم المعلومات الخاصة بالموقع الجغرافي، ولكن على موظّف الدعم التأكّد من الموقع الجغرافي الذي يريد المستخدم الدردشة معه قبل بدء المحادثة.
باستخدام معلومات سياق الرسالة، وجِّه الرسالة إلى أفضل موقع مناسب للرد:
- إذا كانت الرسالة في محادثة جديدة وكان سؤالًا شائعًا، يمكنك الإجابة باستخدام التشغيل المبرمَج.
- في حال لم يتمكّن النظام التلقائي من الإجابة عن السؤال، يمكنك توجيهه إلى موظّف دعم متاح مباشرةً.
- إذا كانت لغة الرسالة لا تتطابق مع اللغة التلقائية لوكيلك، يمكنك توجيه الرسالة إلى موظّف دعم يقدّم خدمة الدعم المحلية.
- إذا كان السؤال يتعلق بموقع جغرافي محدد، وجِّهه إلى مستخدم لديه معلومات حول ذلك الموقع الجغرافي.
- إذا كانت الرسالة في محادثة جارية، وجِّهها إلى موظّف الدعم المباشر الذي يشارك في المحادثة.
تحديد نوع الرسالة التي أرسلها المستخدم
يمكن للمستخدمين إرسال ثلاثة أنواع من الرسائل:
- الرسائل النصية هي ردود بأسلوب مرن.
- تتضمن رسائل الصور عنوان URL موقّع لصورة حمّلها المستخدم.
- تتضمن رسائل الاقتراح بيانات الإبلاغ عن الإحالات الناجحة ونص الإجراء المُقترَح أو الرد المُقترَح الذي نقر عليه المستخدم.
معالجة محتوى الرسالة
إذا كان الوكيل يستخدم التشغيل التلقائي، يجب أن يوجِّه محتوى رسالة المستخدم منطق وكيلك والاستجابة التالية له في المحادثة.
إن أسهل طريقة لتحديد غرض المستخدم هي بيانات الإبلاغ عن الإحالات الناجحة من رد مقترَح أو إجراء مقترح. بغض النظر عن النص المرتبط بالاقتراح، تكون بيانات الإبلاغ عن الإحالات الناجحة قابلة للقراءة آليًا.
إذا أرسل أحد المستخدمين رسالة نصية، قد يحلّل وكيلك الكلمات الرئيسية المتوافقة أو يستخدم فهم اللغة الطبيعية (كما هو الحال مع دمج Dialogflow) لمعالجة رسالة المستخدم وتحديد مسار للأمام.
إذا كان موظّف الدعم لا يعرف كيفية الردّ على رسالة المستخدم، عليه الاستجابة لحالة خطأ ومحاولة مواصلة المحادثة من خلال طلب معلومات إضافية من المستخدم، أو طلب الإدخال بطريقة مختلفة، أو تسليم المحادثة إلى موظّف دعم مباشر.
الردّ على المستخدم
بعد أن يحدّد موظّف الدعم الردّ الصحيح، سواء من خلال وكيل مبرمَج أو موظّف دعم متاح مباشرةً، يرسل الجهاز رسالة ويواصل المحادثة مع المستخدم.
عند إنشاء ردّ، يجب مراعاة لغة المستخدم. ويمكنك أيضًا تخصيص الردود من خلال استرداد القيم من العنصر userInfo في كل رسالة تتلقّاها.
أنواع الرسائل
يُظهر الرمز التالي كيف يتلقى الوكيل الرسائل.
للحصول على معلومات حول التنسيق والقيمة، يُرجى الاطّلاع على
UserMessage.
النص
إنّ النص العادي هو الطريقة الأكثر شيوعًا للردّ على المستخدمين. تكون الرسائل النصية بالتنسيق التالي.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"message": {
"messageId": "MESSAGE_ID",
"name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"text": "MESSAGE_TEXT",
"createTime": "MESSAGE_CREATE_TIME",
},
"dialogflowResponse": {
"autoResponded": "BOOLEAN",
"faqResponse": {
"userQuestion": "USER_QUESTION",
"answers": [{
"faqQuestion": "FAQ_QUESTION",
"faqAnswer": "FAQ_ANSWER",
"matchConfidenceLevel": "CONFIDENCE_LEVEL",
"matchConfidence": "CONFIDENCE_NUMERIC",
}],
},
},
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
لمعرفة خيارات التنسيق والقيمة، يُرجى الاطّلاع على
Message.
صورة
بالإضافة إلى إرسال الرسائل النصية، يمكن للمستخدمين إرسال الصور إلى وكيلك كرسائل.
يخزّن تطبيق "الرسائل التجارية" صورًا مشتركة لمدة 7 أيام على عناوين URL الموقَّعة، ويتضمّن عناوين URL هذه في الحقل text في حمولة الرسائل.
إذا كان الوكيل يتضمّن التشغيل التلقائي، تأكد من أن التشغيل التلقائي يعرف كيفية الاستجابة إذا شارك المستخدم صورة. بالنسبة إلى موظّفي الدعم المباشرين، تأكَّد من أنّ الصور تمرّ أو أنّ عناوين URL في الرسائل قابلة للنقر.
...
"message": {
"text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
}
...
لمعرفة خيارات التنسيق والقيمة، يُرجى الاطّلاع على
Message.
اقتراح
تتيح الردود المقترحة والإجراءات المقترحة للمستخدمين الاستجابة أو تنفيذ الإجراءات بنقرة واحدة. عندما ينقر المستخدم على اقتراح، يتلقى الوكيل حمولة مع نص الاقتراح وبيانات الإبلاغ عن الإحالات الناجحة.
تظهر رسائل الاقتراحات بالتنسيق التالي.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"suggestionResponse": {
"message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"postbackData": "POSTBACK_DATA",
"createTime": "RESPONSE_CREATE_TIME",
"text": "SUGGESTION_TEXT",
"suggestionType": "SUGGESTION_TYPE",
}
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
لمعرفة خيارات التنسيق والقيمة، يُرجى الاطّلاع على
SuggestionResponse.
طلب المصادقة
يتيح اقتراح طلب المصادقة للمستخدمين تسجيل الدخول باستخدام موفّر OAuth لتقديم تفاصيل الهوية مع الوكيل أو السماح للوكيل بتنفيذ إجراءات نيابة عن المستخدمين. يُرجى الاطّلاع على المصادقة باستخدام OAuth.
إذا سجّل مستخدم الدخول بنجاح باستخدام موفّر OAuth المحدّد، يتلقى الوكيل حمولةً برمز التفويض. في حال تعذّر على المستخدم تسجيل الدخول، يتلقى الوكيل حمولة مع تفاصيل الخطأ.
تكون رسائل طلب المصادقة بالتنسيق التالي.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"authenticationResponse": {
"code": "AUTHORIZATION_CODE",
"redirect_uri": "REDIRECT_URI",
"errorDetails": {
"error": "ERROR",
"errorDescription": "ERROR_DESCRIPTION",
},
}
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
لمعرفة خيارات التنسيق والقيمة، يُرجى الاطّلاع على
AuthenticationResponse.
سياق الرسالة
تحتوي كل رسالة على معلومات سياقية عن منشأ الرسالة.
...
"context": {
"customContext": "CUSTOM_CONTEXT",
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
"deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
"widget": {
"url": "WEBSITE_URL",
"widgetContext": "WIDGET_CONTEXT",
},
},
...
| الحقل | الوصف |
|---|---|
customContext |
بيانات السياق التي يحدّدها الشريك |
entryPoint |
يعرض سطح المكتب المحادثة التي بدأ المستخدم منها، على النحو المحدّد في EntryPoint. |
placeId |
معرّف فريد من قاعدة بيانات "أماكن Google" للموقع الجغرافي الذي راسله المستخدم. ولا يظهر هذا الاسم إلا في الرسائل الواردة من نقاط الدخول الخاصة بالموقع الجغرافي. |
nearPlaceId |
معرّف فريد من قاعدة بيانات "أماكن Google" للموقع الجغرافي الأول في "حزمة محلية". تأكّد من المواقع الجغرافية التي يريد المستخدمون إجراء محادثة معها
عند تلقّي قيم nearPlaceId. |
deflectedPhoneNumber |
رقم الهاتف الذي أدّت ميزة "الرسائل التجارية" إلى منع المستخدم من الاتصال عند بدء المحادثة. |
resolvedLocale |
أفضل مطابقة محسوبة للغة المستخدم (تم الإبلاغ عنها في
قيمة اللغة هي علامة لغة IETF BCP 47 بتنسيق سليم. |
userInfo.displayName |
اسم المستخدم الذي أرسل الرسالة. وفي حال إيقاف المستخدم مشاركة الهوية، سيكون هذا الحقل فارغًا. |
userInfo.userDeviceLocale |
لغة المستخدم، التي تم الإبلاغ عنها من خلال الجهاز، على شكل علامة لغة IETF BCP 47 بتنسيق سليم. |
widget.url |
عنوان URL للموقع الإلكتروني الذي تم عرض مساحة المحادثة عليه. |
widget.widgetContext |
قيمة السمة
data-bm-widget-context للأداة المُستخدَمة
لبدء المحادثة. |
سجل المحادثة
لا توفّر Google سجلّات المحادثات. يمكنك الحفاظ على محادثاتك السابقة، بطريقة متوافقة مع سياسة الخصوصية وأفضل الممارسات، حتى تتمكن من إرسال ردود مستنيرة من الرسائل المستقبلية من المستخدمين.