إرسال الرسائل

يتواصل وكلاء RCS for Business مع المستخدمين من خلال إرسال الرسائل وتلقّيها. لإرسال رسائل إلى المستخدمين، يرسل وكيلك طلبات الرسائل إلى واجهة برمجة التطبيقات الخاصة بميزة "المراسلة التجارية من خلال RCS". يمكن أن يتضمّن الطلب الواحد نصًا وبطاقات تفاعلية وملفات وسائط وملفات PDF وردودًا مقترَحة وإجراءات مقترَحة.

تعرض منصة RCS for Business أخطاء في حالات معيّنة لمساعدتك في إدارة تسليم الرسائل:

  • إذا أرسلت رسالة إلى مستخدم لا يتيح جهازه خدمة RCS أو لم يفعّلها، ستعرض منصة RCS for Business الخطأ 404 NOT_FOUND. في هذه الحالة، يمكنك محاولة الوصول إلى المستخدم من خلال الطرق الاحتياطية المحدّدة في البنية الأساسية لديك.
  • إذا أرسلت رسالة إلى مستخدم RCS على شبكة لم يتم إطلاق وكيلك عليها بعد، أو على شبكة لم تفعّل حركة بيانات RCS، ستعرض منصة RCS for Business الخطأ 404 NOT_FOUND.
  • إذا أرسلت رسالة تتضمّن ميزات لا يتيحها جهاز المستخدم، ستعرض منصة "RCS for Business" الخطأ 400 INVALID_ARGUMENT ولن يتم تسليم رسالتك.

كجزء من استراتيجية المراسلة المتعددة القنوات، من الأفضل إبطال الرسائل التي لا يتم تسليمها بعد فترة زمنية معقولة وإرسالها من خلال قناة مختلفة. لإبطال الرسائل تلقائيًا في وقت محدّد مسبقًا، يمكنك ضبط تاريخ انتهاء صلاحية الرسالة.

المتلقّي غير متّصل بالإنترنت

تستمر منصة RCS for Business في قبول الرسائل لتسليمها إذا كان المستلِم غير متصل بالإنترنت. ستتلقّى ردًا برمز الحالة 200 OK، وستحتفظ منصة RCS for Business بالرسالة وتحاول إعادة تسليمها لمدة 30 يومًا. لا حاجة إلى طلب إعادة إرسال الرسالة من خلال RCS for Business.

تحذف خدمة RCS for Business أي رسائل لم يتم تسليمها بعد 30 يومًا من إرسالها.

استنادًا إلى حالة استخدام الوكيل، قد تحتاج إلى إبطال رسالة لم يتم تسليمها قبل انتهاء مهلة الـ 30 يومًا هذه. يمكن أن يمنع الإبطال المستخدمين غير المتصلين بالإنترنت من تلقّي رسالة قديمة عند عودتهم إلى الاتصال بالإنترنت. هناك عدة طرق لإبطال رسالة:

ضبط تاريخ انتهاء صلاحية الرسالة

هل رسالة وكيلك حسّاسة للوقت؟ على سبيل المثال، كلمات المرور الصالحة لمرة واحدة تكون صالحة لفترة قصيرة فقط. تنتهي صلاحية العروض المتاحة لفترة محدودة. ولا تكون التذكيرات بالمواعيد ذات صلة بعد تاريخ الموعد. للحفاظ على الرسائل في الوقت المناسب وذات صلة، قم بتعيين انتهاء صلاحية الرسالة. يمكن أن يمنع ذلك المستخدمين غير المتصلين بالإنترنت من تلقّي محتوى قديم عندما يعودون إلى الإنترنت. ويُعدّ انتهاء الصلاحية أيضًا إشارة جيدة لاستخدام استراتيجية المراسلة الاحتياطية لكي يحصل المستخدمون على المعلومات التي يحتاجون إليها في الوقت المناسب.

لضبط تاريخ انتهاء صلاحية الرسالة، حدِّد أحد الحقول التالية في رسالة الوكيل:

  • ‫expireTime: الوقت المحدّد بالتوقيت العالمي المنسَّق (UTC) الذي تنتهي فيه صلاحية الرسالة
  • ttl(مدة البقاء): مقدار الوقت قبل انتهاء صلاحية الرسالة.

للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة AgentMessage.

الحدّ الأقصى للقيمة لكل من ttl وexpireTime هو 15 يومًا بعد إرسال الرسالة.

الحد الأدنى لقيمة ttl وexpireTime هو ست ثوانٍ بعد إرسال الرسالة.

اقتراحات لضبط انتهاء صلاحية الرسائل

  • بالنسبة إلى رسائل المصادقة (كلمة المرور الصالحة لمرة واحدة): اضبط ttl على 15 ثانية أو أكثر بعد إرسال الرسالة لتقليل احتمال حدوث حالات سباق التسليم والإبطال بشكل كبير.

  • بالنسبة إلى رسائل المعاملات والرسائل الترويجية: اضبط فترات انتهاء صلاحية أطول (60 ثانية على الأقل، أو دقائق إلى ساعات حسب حالة الاستخدام) لأنّ الأجهزة تتطلّب وقتًا إضافيًا لفحص الرسائل وتنزيل محتوى الوسائط التفاعلية المتقدّمة أو معالجته، وقد يواجه المستخدمون انقطاعات قصيرة في الاتصال (على سبيل المثال، في مصعد أو نفق).

مدة البقاء (TTL) للرسالة

عند ضبط مدة صلاحية لرسالة في RCS for Business، يمكنك تحديد المدة التي يجب أن تُعتبر فيها الرسالة صالحة وقابلة للتسليم. إذا لم يتم تسليم الرسالة بنجاح إلى جهاز المستخدم خلال فترة TTL هذه، ستحاول منصة RCS for Business إبطالها تلقائيًا.

عند بدء عملية إبطال رسالة، أنت تطلب من منصة RCS for Business إيقاف محاولة تسليم هذه الرسالة المحدّدة. ومع ذلك، لا يؤثر هذا الإجراء إلا في محاولات التسليم المستقبلية. إذا استردّ جهاز المستخدم الرسالة بنجاح، تتم معالجة الرسالة، ولا يمكن لمنصة RCS for Business إبطال الرسالة من جهاز المستخدم.

في ما يلي ما يمكن توقُّعه بشأن الإشعارات:

  • تم تسليم الرسالة خلال مدة البقاء: إذا اتصل جهاز المستخدم بالإنترنت وتلقّى الرسالة قبل انتهاء مدة البقاء، ستتلقّى إشعارًا من DELIVERED. لن يتم إرسال إشعار بالإبطال، لأنّه تم تسليم الرسالة بنجاح. هذا هو السيناريو الأكثر شيوعًا والمتوقّع.

  • عدم تسليم الرسالة قبل انتهاء صلاحية مدة البقاء: إذا انتهت صلاحية مدة البقاء قبل وصول الرسالة إلى جهاز المستخدم (على سبيل المثال، إذا كان الجهاز غير متصل بالإنترنت)، تحاول منصة RCS for Business إلغاء الرسالة. ستتلقّى إشعارًا من TTL_EXPIRATION_REVOKED يشير إلى أنّه تمت إزالة الرسالة بنجاح من قائمة انتظار التسليم. وفي هذه الحالة، لن يتلقّى المستخدم الرسالة.

اقتراحات للتعامل مع الحالات الهامشية

يعالج نظامنا تسليم رسائل RCS for Business وانتهاء صلاحية TTL في الوقت نفسه. لهذا السبب، قد تظهر لك في حالات نادرة جدًا حالات قصوى يكون فيها توقيت الإشعارات غير متوقّع. على سبيل المثال، قد تتلقّى إشعارًا بالتسليم وإشعارًا بانتهاء صلاحية الرسالة، أو قد لا تتلقّى أيًا منهما.

في ما يلي اقتراحاتنا بشأن التعامل مع إشعارات الرسائل في RCS for Business:

  • إشعار DELIVERED: إذا تلقّيت إشعار DELIVERED لرسالة، يؤكّد ذلك وصول الرسالة إلى المستخدم. يمكنك تجاهل أي إشعارات لاحقة بشأن انتهاء صلاحية هذه الرسالة المحددة.

  • إشعار TTL_EXPIRATION_REVOKED: إذا تلقّيت إشعارًا بانتهاء صلاحية الرسالة يتضمّن الحالة TTL_EXPIRATION_REVOKED، يعني ذلك أنّ نظام RCS for Business سيتوقف عن محاولة تسليم هذه الرسالة المحدّدة. يجب التعامل مع هذه الرسالة على أنّها لم يتم تسليمها، واتّباع استراتيجية احتياطية إذا لزم الأمر.

  • إشعار TTL مع أي حالة أخرى: إذا تلقّيت إشعار TTL مع أي حالة أخرى، يشير ذلك إلى محاولة إبطال غير حاسمة.

    • بالنسبة إلى الرسائل المهمة، مثل كلمات المرور الصالحة لمرة واحدة (OTP)، يمكنك بدء طريقة الاحتياطية.
    • بالنسبة إلى الرسائل غير المُهمّة، يمكنك تحديد ما إذا كنت تريد بدء الاحتياطي أم لا.
  • عدم تلقّي إشعارات: في حالات نادرة، قد يتعذّر على النظام إرسال إشعار TTL، وقد يتعذّر أيضًا على العميل إنشاء إشعار بالتسليم. هذه حالة نادرة للغاية.

ضبط نوع حركة الرسائل

تتضمّن واجهة RBM API حقل messageTrafficType لتصنيف الرسائل. على الرغم من أنّ حالات استخدام الوكيل لا تزال تحدّد سلوك الوكيل وقواعد النشاط التجاري التي تنطبق، يتيح messageTrafficType تصنيف محتوى الرسائل بشكل أكثر تفصيلاً. في النهاية، يتيح ذلك لوكيل واحد التعامل مع حالات استخدام متعددة. ولن يؤثر ذلك في حالات استخدام الوكيل الحالية أو قواعد العمل في الوقت الحالي.

هذا الحقل اختياري، ولكن ننصحك بضبطه الآن حتى لا تظهر لك رسالة خطأ عندما يصبح الحقل مطلوبًا.

لضبط نوع الرسائل، يجب تحديد messageTrafficType المناسب لكل رسالة استنادًا إلى محتواها. يسرد الجدول التالي أنواع الزيارات المتوافقة وحالات استخدام الوكيل المتوقعة. هذا التعيين هو إرشادات مقترَحة حول الاستخدام المتوقّع، وليس قيدًا تفرضه واجهة برمجة التطبيقات في الوقت الحالي.

نوع الزيارات محتوى الرسالة حالة استخدام الوكيل المقترَحة
AUTHENTICATION لرسائل المصادقة كلمات مرور OTP
TRANSACTION للرسائل المتعلقة بخدمات أو منتجات حالية للمستخدم على سبيل المثال: رسائل التأكيد أو إيصالات الدفع أو تفاصيل الحجز معاملات أو حالات متعددة
PROMOTION للرسائل الترويجية، مثل العروض أو الخصومات أو الإشعارات أو غيرها من المحتوى الترويجي ترويجي أو متعدد الاستخدامات
SERVICEREQUEST للرسائل حول الخدمات التي طلبها المستخدم صراحةً كلمة مرور صالحة لمرة واحدة (OTP) أو رسائل معاملات أو رسائل ترويجية أو رسائل متعددة الاستخدامات
ACKNOWLEDGEMENT للرسائل المستخدَمة لتأكيد إجراء اتّخذه المستخدم، وتحديدًا طلب إلغاء الاشتراك يؤكّد ذلك أنّه تم استلام طلب المستخدم وجارٍ معالجته. كلمة مرور صالحة لمرة واحدة (OTP) أو رسائل معاملات أو رسائل ترويجية أو رسائل متعددة الاستخدامات

في حال عدم ضبط نوع الزيارات، يحدّد النظام النوع التلقائي لحالة استخدام الوكيل.

حالة استخدام الوكيل نوع الزيارات التلقائي
OTP AUTHENTICATION
المعاملات TRANSACTION
Promotional PROMOTION
متعددة الاستخدامات MESSAGE_TRAFFIC_TYPE_UNSPECIFIED

الوكلاء المتعدّدو الاستخدامات ليس لديهم نوع زيارات تلقائي. يجب ضبط نوع الزيارات بشكل صريح لكل رسالة استنادًا إلى محتواها. في حال عدم استبدال قيمة MESSAGE_TRAFFIC_TYPE_UNSPECIFIED، سيتم قبول الرسالة وتسليمها بدون تصنيف محدّد لنوع الزيارات.

الحد الأقصى المسموح به لحجم الرسائل

الحد الأقصى لحجم سلسلة AgentMessage بالكامل هو 250 كيلوبايت. ويبلغ الحد الأقصى لعدد الأحرف في الجزء النصي من الرسالة 3072 حرفًا.

لتجنُّب استهلاك البيانات بشكل غير متوقّع للمستخدمين، يبلغ الحد الأقصى لحجم الملف الذي يمكن إرساله من خلال RCS for Business‏ 100 ميغابايت، ويجب ألا يتجاوز إجمالي الحجم المجمّع لجميع الوسائط ومرفقات PDF ضمن رسالة واحدة في RCS for Business‏ 100 ميغابايت. (1 ميغابايت = 1,048,576 بايت). لمزيد من المعلومات، يُرجى الاطّلاع على ملفات الوسائط وملفات PDF.

نص

تتكوّن أبسط الرسائل من نص. الرسائل النصية هي الأنسب لتوصيل المعلومات دون الحاجة إلى مرئيات أو تفاعل معقد أو استجابة.

مثال

يرسل الرمز التالي رسالة نصية عادية. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة phones.agentMessages.create.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!"
  },
  "messageTrafficType": "PROMOTION"
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
};

// Send a simple message to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444"
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create a simple RBM text message
message_text = messages.TextMessage('Hello, world!')

# Send text message to the device
messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

محتوى الرسالة الأساسية - تحويل الرسائل القصيرة SMS

قدّم مشغّلو شبكات الجوّال نماذج فوترة لدعم نقل الرسائل القصيرة SMS إلى RCS for Business. تُعرف الرسالة التي تحتوي على ما يصل إلى 160 حرفًا بتنسيق UTF-8 في خدمة RCS for Business باسم "الرسالة الأساسية".

عند إنشاء طلب لإرسال رسالة أساسية، يُرجى العِلم أنّ الأحرف تُحتسب كبايت واحد (UTF-8). إذا أرسلت رسالة تحتوي على رموز خاصة، مثل رموز الإيموجي أو دليل الرموز المتعدد البايتات، يُحتسب كل حرف كحرفَين إلى 4 أحرف أو أكثر من أحرف UTF-8.

أدخِل بعض النصوص في المربّع للتحقّق من طولها:

قد تتيح برامج RCS معاينات الروابط. إذا كانت رسالة RCS for Business النصية فقط تتضمّن عنوان URL لموقع إلكتروني يحتوي على علامات OpenGraph، يمكن للعميل إنشاء معاينة (صورة وعنوان وما إلى ذلك)، ما يوفّر تجربة أكثر ثراءً. على سبيل المثال، يمكنك الاطّلاع على رسالة أساسية تتضمّن معاينة لعنوان URL.

يُرجى العِلم أنّ عميل RCS قد يسمح للمستخدم بإيقاف معاينات الروابط.

كلمات مرور صالحة لمرة واحدة لإثبات هوية المستخدم

يمكنك استخدام ميزة "RCS للمؤسسات" لإرسال كلمات مرور صالحة لمرة واحدة (OTP) من أجل التحقّق من هوية المستخدمين تلقائيًا باستخدام واجهة برمجة التطبيقات SMS Retriever API. لا تتوفّر واجهة برمجة تطبيقات مخصّصة لقراءة كلمات المرور الصالحة لمرة واحدة التي تصل من خلال RCS for Business.

طريقة العمل على أجهزة Android

بالنسبة إلى تطبيقات Android المسجَّلة في SMS Retriever API، تستمع واجهة برمجة التطبيقات إلى رسالة RCS for Business منسَّقة بشكل صحيح. يجب أن تحتوي هذه الرسالة على كل من كلمة المرور الصالحة لمرة واحدة (OTP) وتجزئة فريدة تحدّد تطبيقك.

عند تلقّي رسالة من خلال ميزة RCS for Business بالتنسيق الصحيح، تعالجها واجهة SMS Retriever API بالطريقة نفسها التي تعالج بها كلمة المرور الصالحة لمرة واحدة (OTP) في رسالة SMS. بعد مطابقة التجزئة مع تطبيقك، يتم استخراج كلمة المرور الصالحة لمرة واحدة (OTP) وإعادة توجيهها إلى تطبيقك للتحقّق من المستخدم تلقائيًا.

  • نموذج رسالة نصية من RCS for Business للتحقّق من هوية المستخدم: Your code is <OTP><app hash>.
  • مثلاً: Your code is 123456 M8tue43FGT.

لمزيد من المعلومات حول SMS Retriever وواجهات برمجة التطبيقات ذات الصلة، يُرجى الاطّلاع على مستندات SMS Retriever. لمعرفة تفاصيل حول التأكّد من هوية المستخدم تلقائيًا في التطبيقات المسجَّلة باستخدام واجهة برمجة التطبيقات SMS Retriever API، يُرجى الاطّلاع على المخطّط البياني التالي.

طريقة العمل على أجهزة iOS

في أجهزة iOS، ترصد ميزة معالجة كلمات المرور الصالحة لمرة واحدة (OTP) المضمّنة في النظام تلقائيًا كلمات المرور الصالحة لمرة واحدة (OTP) في RCS for Business وتقترحها لملئها تلقائيًا، تمامًا مثل كلمات المرور الصالحة لمرة واحدة (OTP) في الرسائل القصيرة. لا يلزم دمج واجهة برمجة تطبيقات معيّنة لكي يقرأ تطبيق iOS كلمة المرور الصالحة لمرة واحدة.

ملفات الوسائط وملفات PDF

عند إرسال رسالة تتضمّن صورة أو فيديو أو ملفًا صوتيًا أو ملف PDF، يجب أن يقدّم وكيلك عنوان URL متاحًا للجميع للمحتوى أو أن يحمّل الملف مباشرةً.

الحد الأقصى لحجم الملف الذي يمكن إرساله هو 100 ميغابايت، ويجب ألا يتجاوز إجمالي حجم جميع مرفقات الوسائط وملفات PDF في رسالة واحدة 100 ميغابايت.

ضغط الوسائط وتحويل ترميزها

تعمل منصة RCS for Business على تحويل ترميز ملفات الوسائط وضغطها تلقائيًا (مثل الصور والفيديوهات) قبل إرسالها لضمان تحميلها بسرعة وعملها بشكل جيد على مختلف الشبكات والأجهزة.

يعتمد الضغط على جودة الوسائط التي يتم إدخالها بدلاً من الاعتماد بشكل صارم على حدود حجم الملف. وهذا يعني أنّه يمكن ضغط الملف حتى إذا كان حجمه أقل بكثير من الحد الأقصى البالغ 100 ميغابايت. تتغيّر معايير تحويل الترميز باستمرار، لذا ليس هناك حدّ أقصى ثابت لحجم الملف يحدّد متى يتم تجاوز تحويل الترميز. جرِّب تنسيقات وسائط وأبعاد ومعدلات ضغط مختلفة للعثور على التوازن الأمثل لحمولاتك.

مواصفات الصور المصغّرة

بالنسبة إلى ملفات الوسائط، يمكنك أيضًا تحديد صورة مصغّرة تتيح للمستخدمين معاينة المحتوى قبل النقر عليه. بالنسبة إلى الملفات الصوتية، يتم استخدام التطبيق المصغّر التلقائي للصوت كعنصر نائب.

  • الحد الأقصى لحجم ملف الصورة المصغّرة هو 100 كيلوبايت. للحصول على أفضل تجربة للمستخدم، ننصح بأن يكون حجمه 50 كيلوبايت أو أقل.
  • يجب أن تتطابق نسبة العرض إلى الارتفاع للصورة المصغّرة مع نسبة الملف الأصلي.

التخزين المؤقت وإدارة عناوين URL

تخزّن منصة RCS for Business الملفات مؤقتًا لمدة 60 يومًا، وتُرجع واجهة برمجة التطبيقات معرّف ملف يمكن لوكيلك تضمينه في الرسائل الموجّهة إلى المستخدمين. وبعد مرور 60 يومًا، يزيل RCS for Business الملفات من ذاكرة التخزين المؤقت.

عند تحديد الملفات حسب عنوان URL، من الأفضل ضبط contentMessage.forceRefresh على false. يؤدي ضبط contentMessage.forceRefresh على true إلى فرض جلب محتوى جديد من عنوان URL المحدّد في RCS for Business، حتى إذا كان محتوى عنوان URL مخزّنًا مؤقتًا، ما يزيد من أوقات تسليم الرسائل للمستخدمين.

مثال على عنوان URL للملف

يرسل الرمز التالي صورة. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة AgentContentMessage.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "contentInfo": {
      "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif",
      "forceRefresh": false
    }
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

let params = {
   fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
   msisdn: '+12223334444',
};

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage;
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage;
import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

   // create media only message
   AgentContentMessage agentContentMessage = new AgentContentMessage();
   agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl));

   // attach content to message
   AgentMessage agentMessage = new AgentMessage();
   agentMessage.setContentMessage(agentContentMessage);

   rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444");
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create media file attachment
file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif')

messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

// Create content info with the file url
ContentInfo contentInfo = new ContentInfo
{
    FileUrl = fileUrl
};

// Attach content info to a message
AgentContentMessage agentContentMessage = new AgentContentMessage
{
    ContentInfo = contentInfo,
};

// Attach content to message
AgentMessage agentMessage = new AgentMessage
{
    ContentMessage = agentContentMessage
};

rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
هذا الرمز هو مقتطف من نموذج وكيل RBM.

يمكنك بدلاً من ذلك تحميل الوسائط قبل إرسالها في رسالة باستخدام files.create.

مثال على تحميل الملفات

يحمّل الرمز التالي ملف فيديو وملف صورة مصغّرة، ثم يرسل الملفين في رسالة. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة files.create وAgentContentMessage.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \
-H "Content-Type: video/mp4" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
--upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"

# Capture server-specified video file name from response body JSON


curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \
-H "Content-Type: image/jpeg" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
--upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"

# Capture server-specified image file name from response body JSON


curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "uploadedRbmFile": {
      "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME",
      "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME"
    }
  }
}'

أنواع الوسائط المتوافقة

تتيح خدمة RCS for Business أنواع الوسائط التالية. بالنسبة إلى الصور المصغّرة، يمكن استخدام التنسيقات التالية فقط: image/jpeg وimage/jpg وimage/gif وimage/png.

نوع الوسائط نوع المستند الإضافة تعمل مع البطاقات التفاعلية
application/ogg ملفات صوتية بتنسيق OGG ‎.ogx لا
application/pdf PDF ‎.pdf نعم (فقط في تطبيق "رسائل Google" في الهند)
audio/aac ملف صوتي بتنسيق AAC ‎.aac لا
audio/mp3 ملفات MP3 الصوتية ‎.mp3 لا
audio/mpeg صوت MPEG ‎.mpeg لا
audio/mpg صوت MPG ‎.mp3 لا
audio/mp4 صوت MP4 ‎.mp4 لا
audio/mp4-latm صوت MP4-latm ‎.mp4 لا
audio/3gpp ملفات صوتية بتنسيق 3GPP ‎.3gp لا
image/jpeg JPEG ‫‎.jpeg و‎.jpg نعم
الصورة/gif GIF ‎.gif نعم
الصورة/png PNG ‎.png نعم
video/h263 فيديو H263 ‎.h263 نعم
video/m4v فيديو M4V ‎.m4v نعم
الفيديو/mp4 فيديو MP4 ‎.mp4 نعم
video/mpeg4 فيديو MPEG-4 ‎.mp4, .m4p نعم
video/mpeg فيديو MPEG ‎.mpeg نعم
video/webm فيديو WEBM ‎.webm نعم

اقتراحات

يرسل وكيلك اقتراحات (ردود مقترَحة وإجراءات مقترَحة) في قوائم شرائح الاقتراحات أو في بطاقات تفاعلية.

الردود المقترَحة

توجّه الردود المقترَحة المستخدمين خلال المحادثات من خلال تقديم ردود يعرف وكيلك كيفية التعامل معها.

عندما ينقر المستخدم على ردّ مقترَح، يتلقّى وكيلك حدثًا يحتوي على نص الردّ وبيانات تسجيل الإحالات الناجحة. يبلغ الحد الأقصى لعدد الأحرف في الحمولة 2048 حرفًا.

مثال

يرسل الرمز التالي نصًا مع ردَّين مقترحَين. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة SuggestedReply.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "reply": {
          "text": "Suggestion #1",
          "postbackData": "suggestion_1"
        }
      },
      {
        "reply": {
          "text": "Suggestion #2",
          "postbackData": "suggestion_2"
        }
      }
    ]
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

let suggestions = [
   {
      reply: {
         'text': 'Suggestion #1',
         'postbackData': 'suggestion_1',
      },
   },
   {
      reply: {
         'text': 'Suggestion #2',
         'postbackData': 'suggestion_2',
      },
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
import com.google.rbm.SuggestionHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();
   suggestions.add(
      new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply());

   suggestions.add(
      new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply());

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggested replies for the message to send to the user
cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'))
cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2'))

# Send a simple message with suggestion chips to the device
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

List<Suggestion> suggestions = new List<Suggestion>
{
   // Create suggestion chips
   new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(),
   new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply()
};

// Send simple text message with suggestions to user
rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
   suggestions
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

الإجراءات المقترَحة

توجّه الإجراءات المقترَحة المستخدمين خلال المحادثات من خلال الاستفادة من الوظائف المضمّنة في أجهزتهم. يمكن لوكيلك أن يقترح على المستخدمين الاتصال برقم أو فتح موقع جغرافي على خريطة أو مشاركة موقع جغرافي أو فتح عنوان URL أو إنشاء حدث في التقويم.

لكل إجراء مقترَح، يمكنك اختياريًا تقديم عنوان URL احتياطي (بحد أقصى 2048 حرفًا). يتم فتح عنوان URL هذا في نافذة متصفّح جديدة إذا كان جهاز المستخدم لا يتيح الإجراء المقترَح.

عندما ينقر المستخدم على إجراء مقترَح، يتلقّى وكيلك حدثًا يحتوي على بيانات تسجيل الإحالات الناجحة للإجراء.

للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة SuggestedAction.

عرض الاقتراحات

هناك طريقتان لعرض الاقتراحات:

  • Persistent: الإجراءات المقترَحة أو الردود التي تظهر داخل فقاعة الرسالة وتظل ثابتة طوال المحادثة.
  • مؤقتة: الاقتراحات التي يتم عرضها خارج فقاعة الرسالة وتختفي عند استمرار المحادثة.

تنسيقات الرسائل المتوافقة

  • الاقتراحات الثابتة: تعمل مع الرسائل النصية المستقلة والبطاقات التفاعلية.
  • الاقتراحات المؤقتة: تعمل مع الرسائل النصية المستقلة ورسائل الوسائط والبطاقات التفاعلية.

دمج الاقتراحات

يمكنك الجمع بين الاقتراحات الثابتة والمؤقتة في الرسالة نفسها أو البطاقة التفاعلية نفسها.

  • الرسائل النصية: تكون الاقتراحات مؤقتة تلقائيًا. ولإبقائها داخل الفقاعة، يجب ضبطها على أنّها دائمة.
  • البطاقات التفاعلية: تتيح هذه البطاقات ما يصل إلى أربعة اقتراحات ثابتة تلقائيًا. يمكنك بعد ذلك إضافة اقتراحات مؤقتة على شكل "قائمة شرائح" أسفل البطاقة.

الحدود القصوى المقترَحة

يمكن أن تتضمّن الرسالة النصية الواحدة 11 اقتراحًا كحدّ أقصى في المجمل. يتم احتساب أي اقتراحات ثابتة تُدرجها ضمن هذا الحد الإجمالي. على سبيل المثال، إذا أضفت 4 اقتراحات ثابتة، يمكنك إضافة ما يصل إلى 7 اقتراحات مؤقتة.

نوع الاقتراح الحدّ الأقصى أماكن ظهورها
ثابتة ما يصل إلى 4 داخل فقاعة الرسالة
مؤقتة ما يصل إلى 11 خارج الفقاعة (كشرائح)

الحد الأقصى لعدد الأحرف

يبلغ الحدّ الأقصى لعدد الأحرف في كل اقتراح 25 حرفًا.

شفافية عنوان URL في الإجراءات المقترَحة

لبناء ثقة المستخدمين، يتم عرض عنوان URL الأساسي كسطر ثانٍ من النص داخل زر الاقتراح للإجراءات المقترَحة الخاصة بـ "فتح عنوان URL". ينطبق هذا السلوك المتّسق على الرسائل النصية المستقلة والبطاقات التفاعلية ولوحات العرض الدوّارة.

البرامج المتوافقة مع الاقتراحات الثابتة

  • متوافق: تطبيق "رسائل Google" (الإصدار 20260225.00 أو إصدار أحدث)
  • غير متوافقة: إصدارات "رسائل Google" الأقدم من 20260225.00، وأجهزة iOS، وتطبيق Samsung Messages.

اقتراحات في إشعارات النظام

عندما يتلقّى المستخدم رسالة، يعرض تطبيق &quot;رسائل Google&quot; الاقتراح الأول المؤهَّل مباشرةً في إشعار نظام Android. يمكن للمستخدمين النقر على هذا الاقتراح لإرسال ردّ أو بدء إجراء بدون الحاجة إلى فتح التطبيق.

عند تصميم رسائلك، يجب مراعاة السلوك التالي:

  • الترتيب مهم: يتم عرض اقتراح واحد فقط لكل إشعار. لزيادة التفاعل إلى أقصى حد، ضع الرد أو الإجراء المقترح ذي الأولوية القصوى أولاً في قائمة الاقتراحات.
  • الإجراءات المستبعَدة: لا يظهر الإجراء مشاركة الموقع الجغرافي في إشعارات النظام، بل يجب على المستخدمين فتح المحادثة لمشاركة موقعهم الجغرافي.

طلب رقم

يوجّه إجراء "الاتصال" المستخدم إلى الاتصال برقم هاتف يحدّده وكيلك. يمكن أن تتضمّن أرقام الهواتف أرقامًا (0-9) وعلامة الجمع (+) وعلامة النجمة (*) وعلامة الرقم (#) فقط. يُسمح باستخدام التنسيق الدولي E.164 (على سبيل المثال، +14155555555)، ولكنّه ليس مطلوبًا. أي أنّ كلاً من +14155555555 و1011 هما إدخالان صالحان.

مثال

يرسل الرمز التالي إجراء اتصال. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة DialAction.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Call",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/contact/",
          "dialAction": {
            "phoneNumber": "+15556667777"
          }
        }
      }
    ]
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Define a dial suggested action
let suggestions = [
   {
      action: {
         text: 'Call',
         postbackData: 'postback_data_1234',
         dialAction: {
            phoneNumber: '+15556667777'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with a dial suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a dial suggested action
   DialAction dialAction = new DialAction();
   dialAction.setPhoneNumber("+15556667777");

   // creating a suggested action based on a dial action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Call");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setDialAction(dialAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create a dial suggested action
suggestions = [
      messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Create a dial an agent suggested action
DialAction dialAction = new DialAction
{
    PhoneNumber = "+15556667777"
};

// Creating a suggested action based on a dial action
SuggestedAction suggestedAction = new SuggestedAction
{
    Text = "Call",
    PostbackData = "postback_data_1234",
    DialAction = dialAction
};

// Attach action to a suggestion
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

عرض موقع جغرافي

يعرض إجراء "عرض الموقع الجغرافي" موقعًا جغرافيًا في تطبيق الخرائط التلقائي للمستخدم. يمكنك تحديد الموقع الجغرافي إما عن طريق خط العرض وخط الطول أو باستخدام طلب بحث يستند إلى الموقع الجغرافي الحالي للمستخدم. يمكنك أيضًا ضبط تصنيف مخصّص للدبوس الذي يظهر في تطبيق الخريطة.

مثال

يرسل الرمز التالي إجراءً لعرض الموقع الجغرافي. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة ViewLocationAction.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "View map",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z",
          "viewLocationAction": {
            "latLong": {
              "latitude": "37.4220188",
              "longitude": "-122.0844786"
            },
            "label": "Googleplex"
          }
        }
      }
    ]
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Define a view location suggested action
let suggestions = [
   {
      action: {
         text: 'View map',
         postbackData: 'postback_data_1234',
         viewLocationAction: {
            latLong: {
               latitude: 37.4220188,
               longitude: -122.0844786
            },
            label: 'Googleplex'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with a view location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a view location suggested action
   ViewLocationAction viewLocationAction = new ViewLocationAction();
   viewLocationAction.setQuery("Googleplex, Mountain View, CA");

   // creating a suggested action based on a view location action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("View map");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setViewLocationAction(viewLocationAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create a view location suggested action
suggestions = [
      messages.ViewLocationAction('View map',
            'reply:postback_data_1234',
            query='Googleplex, Mountain View, CA')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// create an view location action
ViewLocationAction viewLocationAction = new ViewLocationAction
{
    Query = "Googleplex Mountain View, CA"
};

// Attach the view location action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    ViewLocationAction = viewLocationAction,
    Text = "View map",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

مشاركة موقع

يتيح إجراء "مشاركة الموقع الجغرافي" للمستخدم مشاركة موقع جغرافي مع وكيلك. يمكن للمستخدم مشاركة موقعه الجغرافي الحالي أو موقع جغرافي يختاره يدويًا من تطبيق "خرائط Google".

مثال

يرسل الرمز التالي إجراءً لمشاركة الموقع الجغرافي. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة ShareLocationAction.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Share your location",
          "postbackData": "postback_data_1234",
          "shareLocationAction": {}
        }
      }
    ]
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Define a share location suggested action
let suggestions = [
   {
      action: {
         text: 'Share your location',
         postbackData: 'postback_data_1234',
         shareLocationAction: {
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with a share location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a share location suggested action
   ShareLocationAction shareLocationAction = new ShareLocationAction();

   // creating a suggested action based on a share location action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Share location");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setShareLocationAction(shareLocationAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create a share location suggested action
suggestions = [
      messages.ShareLocationAction('Share location',
            'reply:postback_data_1234')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Create a share location action
ShareLocationAction shareLocationAction = new ShareLocationAction();

// Attach the share location action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    ShareLocationAction = shareLocationAction,
    Text = "Share location",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

فتح عنوان URL

يتيح لك إجراء "فتح عنوان URL" توجيه المستخدمين إلى صفحة ويب يحدّدها وكيلك. يتم فتح صفحة الويب تلقائيًا في متصفّح المستخدم. يمكنك أيضًا ضبط صفحة الويب لتفتح في عرض ويب. لمزيد من التفاصيل، يُرجى الاطّلاع على فتح عنوان URL باستخدام WebView.

متاحة فقط في "رسائل Google"

عرض عنوان URL الأساسي: لتحسين الشفافية في المراسلات من التطبيقات إلى الأشخاص، يعرض تطبيق "رسائل Google" عنوان URL الأساسي ضمن الإجراءات المقترَحة لـ "فتح عنوان URL". يؤثّر هذا التغيير في الإجراءات المقترَحة في البطاقات التفاعلية العادية ولوحات العرض الدوّارة للبطاقات التفاعلية.

بطاقة تفاعلية تعرض اقتراح &quot;عرض الموقع الإلكتروني&quot; مع عنوان URL أسفله
عنوان URL الأساسي المرئي

عرض رمز التطبيق لروابط الويب: إذا كان لدى المستخدم تطبيق تلقائي تم ضبطه لصفحة الويب، فسيتم فتح هذا التطبيق بدلاً من المتصفّح أو WebView، وسيعرض زر الاقتراح رمز التطبيق. ليظهر رمز التطبيق في "رسائل Google"، عليك تقديم عنوان URL الكامل والمباشر. إذا كنت تستخدم عنوان URL مختصرًا، سيظهر رمز "فتح عنوان URL" التلقائي بدلاً من ذلك.

رمز التطبيق في زر اقتراح
رمز التطبيق في زر اقتراح
مثال

يرسل الرمز التالي إجراءً لفتح عنوان URL. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة OpenUrlAction.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Open Google",
          "postbackData": "postback_data_1234",
          "openUrlAction": {
            "url": "https://www.google.com"
          }
        }
      }
    ]
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Define an open URL suggested action
let suggestions = [
   {
      action: {
         text: 'Open Google',
         postbackData: 'postback_data_1234',
         openUrlAction: {
            url: 'https://www.google.com'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating an open url suggested action
   OpenUrlAction openUrlAction = new OpenUrlAction();
   openUrlAction.setUrl("https://www.google.com");

   // creating a suggested action based on an open url action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Open Google");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setOpenUrlAction(openUrlAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create an open url suggested action
suggestions = [
      messages.OpenUrlAction('Open Google',
            'reply:postback_data_1234',
            'https://www.google.com')
]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Create an open url action
OpenUrlAction openUrlAction = new OpenUrlAction
{
    Url = "https://www.google.com"
};

// Attach the open url action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    OpenUrlAction = openUrlAction,
    Text = "Open Google",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

فتح عنوان URL باستخدام WebView

يؤدي إجراء "فتح عنوان URL باستخدام WebView" إلى تحميل صفحة الويب المحدّدة داخل تطبيق المراسلة باستخدام محرّك العرض في المتصفّح التلقائي. يتيح ذلك للمستخدم التفاعل مع صفحة الويب بدون مغادرة محادثة RCS for Business. إذا كان جهاز المستخدم لا يتيح استخدام WebView، سيتم فتح صفحة الويب في متصفّح المستخدم بدلاً من ذلك. لتفعيل طرق عرض الويب، يُرجى الاطّلاع على OpenURLApplication.

تتوفّر ثلاثة أوضاع عرض لـ Webview. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة WebviewViewMode.

  • كاملة: تشغل صفحة الويب الشاشة بأكملها
  • نصف الشاشة: تشغل صفحة الويب نصف الشاشة
  • طويل: تشغل صفحة الويب ثلاثة أرباع الشاشة
مثال

يرسل الرمز التالي إجراء "فتح عنوان URL باستخدام WebView". للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة OpenURLAction.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
 "contentMessage": {
   "text": "Hello, world!",
   "suggestions": [
     {
       "action": {
         "text": "Open Google",
         "postbackData": "postback_data_1234",
         "openUrlAction": {
           "url": "https://www.google.com",
           "application": "WEBVIEW",
           "webviewViewMode": "FULL",
           "description": "Accessibility description"
         }
       }
     }
   ]
 }
}'

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…
  
try {
  
   String URL = "https://www.google.com";
  
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();
  
   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // Create suggestion to view webpage in full mode
   Suggestion viewInFullMode =  getUrlActionInWebview(URL, "FULL")
   suggestions.add(viewInFullMode);
  
   // create suggestion to view webpage in half mode
   Suggestion viewInHalfMode =  getUrlActionInWebview(URL, "HALF")
   suggestions.add(viewInHalfMode);
     
   // create suggestion to view webpage in tall mode
   Suggestion viewInTallMode =  getUrlActionInWebview(URL, "TALL")
   suggestions.add(viewInTallMode);
     
   // Send simple text message with the suggested action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

  /**
    * Creates a suggested action to open URL in webview.
    *
    * @return a suggestion object for an open URL in webview action .
    */
    private Suggestion getUrlActionInWebview(String url,
                                             String viewMode) {
      // create an open url action
      OpenUrlAction openUrlAction = new OpenUrlAction();
      openUrlAction.setUrl(url);
      openUrlAction.setApplication("WEBVIEW");
      openUrlAction.setWebviewViewMode(viewMode);
      openUrlAction.setDescription("Accessibility description");
     
      // attach the open url action to a suggested action
      SuggestedAction suggestedAction = new SuggestedAction();
      suggestedAction.setOpenUrlAction(openUrlAction);
      suggestedAction.setText('display_text');
      suggestedAction.setPostbackData('postback_data_123');
     
      // attach the action to a suggestion object
      Suggestion suggestion = new Suggestion();
      suggestion.setAction(suggestedAction);
     
      return suggestion;
    }

إنشاء حدث في التقويم

يؤدي إجراء "إنشاء حدث في التقويم" إلى فتح تطبيق التقويم الخاص بالمستخدم والبدء في إنشاء حدث جديد بالمعلومات المحدّدة.

يجب إدخال عنوان للحدث في التقويم. ويبلغ الحد الأقصى لعدد الأحرف 100 حرف. وصف الحدث في التقويم اختياري ويمكن أن يتضمّن 500 حرف كحدّ أقصى.

مثال

يرسل الرمز التالي إجراءً لإنشاء حدث في التقويم. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة CreateCalendarEventAction.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Save to calendar",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/calendar",
          "createCalendarEventAction": {
            "startTime": "2020-06-30T19:00:00Z",
            "endTime": "2020-06-30T20:00:00Z",
            "title": "My calendar event",
            "description": "Description of the calendar event"
          }
        }
      }
    ]
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Define a create calendar event suggested action
let suggestions = [
   {
      action: {
         text: 'Save to calendar',
         postbackData: 'postback_data_1234',
         createCalendarEventAction: {
            startTime: '2020-06-30T19:00:00Z',
            endTime: '2020-06-30T20:00:00Z',
            title: 'My calendar event',
            description: 'Description of the calendar event',
         },
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // creating a create calendar event suggested action
   CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction();
   calendarEventAction.setTitle("My calendar event");
   calendarEventAction.setDescription("Description of the calendar event");
   calendarEventAction.setStartTime("2020-06-30T19:00:00Z");
   calendarEventAction.setEndTime("2020-06-30T20:00:00Z");

   // creating a suggested action based on a create calendar event action
   SuggestedAction suggestedAction = new SuggestedAction();
   suggestedAction.setText("Save to calendar");
   suggestedAction.setPostbackData("postback_data_1234");
   suggestedAction.setCreateCalendarEventAction(createCalendarEventAction);

   // attaching action to a suggestion
   Suggestion suggestion = new Suggestion();
   suggestion.setAction(suggestedAction);

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Create a calendar event suggested action
suggestions = [
      messages.CreateCalendarEventAction('Save to Calendar',
                             'reply:postback_data_1234',
                             '2020-06-30T19:00:00Z',
                             '2020-06-30T20:00:00Z',
                             'My calendar event',
                             'Description of the calendar event')

]

# Create text message to send to user
text_msg = messages.TextMessage('Hello, world!')
cluster = messages.MessageCluster().append_message(text_msg)

# Append suggestions for the message to send to the user
for suggestion in suggestions:
    cluster.append_suggestion_chip(suggestion)

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Create a calendar event action
CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction
{
    Title = "My calendar event",
    Description = "Description of the calendar event",
    StartTime = "2020-06-30T19:00:00Z",
    EndTime = "2020-06-30T20:00:00Z"
};

// Attach the calendar event action to a suggested action
SuggestedAction suggestedAction = new SuggestedAction
{
    CreateCalendarEventAction = calendarEventAction,
    Text = "Save to calendar",
    PostbackData = "postback_data_1234"
};

// Attach the action to a suggestion object
Suggestion suggestion = new Suggestion
{
    Action = suggestedAction
};

List<Suggestion> suggestions = new List<Suggestion>
{
    suggestion
};

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
هذا الرمز هو مقتطف من نموذج وكيل RBM.

قائمة شرائح الاقتراحات

يرسل وكيلك قوائم شرائح الاقتراحات مع الرسائل لتوجيه إجراءات المستخدمين اللاحقة. لا تظهر قائمة الشرائح إلا عندما تكون الرسالة المرتبطة بها في أسفل المحادثة. وأي رسائل لاحقة في المحادثة (سواء من المستخدم أو الوكيل) تستبدل قائمة الشرائح.

الشرائح في القائمة هي الردود المقترَحة والإجراءات المقترَحة.

تحتوي قوائم الشرائح على 11 شريحة اقتراح كحدّ أقصى، ويمكن أن يحتوي كل تصنيف شريحة على 25 حرفًا كحدّ أقصى.

للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة AgentContentMessage.

البطاقات التفاعلية

تجمع البطاقات التفاعلية بين الوسائط والنصوص والاقتراحات التفاعلية في رسالة واحدة. وهي مثالية لعرض المعلومات ذات الصلة (على سبيل المثال، منتج مع صورته واسمه وسعره) وتوجيه المستخدمين بخطوة تالية واضحة مثل اقتراح "عرض التفاصيل".

يمكن أن تحتوي البطاقة التفاعلية على ما يلي:

كل حقل من هذه الحقول اختياري، ولكن يجب تضمين حقل واحد على الأقل من الحقول من 1 إلى 3 في البطاقة التفاعلية.

يمكن إرسال بطاقات متعددة معًا في لوحة عرض دوّارة قابلة للتمرير أفقيًا.

يُرجى العِلم أنّ إجمالي الحمولة للبطاقة التفاعلية هو 250 كيلوبايت.

للحصول على التفاصيل الفنية الكاملة، يُرجى الاطّلاع على مستندات البطاقات التفاعلية.

ارتفاع البطاقة

تتوسّع البطاقات التفاعلية عموديًا لتناسب محتواها. الحد الأدنى لارتفاعها هو 112 وحدة بكسل مستقلة الكثافة، والحد الأقصى هو 344 وحدة بكسل مستقلة الكثافة. إذا لم يكن محتوى البطاقة كبيرًا بما يكفي لملء الحد الأدنى لطول البطاقة، يتم توسيع البطاقة وملء الطول الإضافي بمسافة بيضاء.

يجب أن تتناسب الوسائط في البطاقات التفاعلية مع أحد الارتفاعات الثلاثة التالية:

  • فيديو Short: 112 dp
  • متوسطة: 168 وحدة بكسل مستقلة الكثافة
  • طويلة: 264 وحدة بكسل مستقلة الكثافة

إذا لم تكن الوسائط مناسبة لأبعاد البطاقة وفقًا للارتفاع المحدّد، يتم اختيار معاينة الوسائط من خلال تكبير الوسائط واقتصاصها.

مثال

يرسل الرمز التالي بطاقة تفاعلية تحتوي على صورة وردود مقترَحة. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة RichCard.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "richCard": {
      "standaloneCard": {
        "thumbnailImageAlignment": "RIGHT",
        "cardOrientation": "VERTICAL",
        "cardContent": {
          "title": "Hello, world!",
          "description": "RBM is awesome!",
          "media": {
            "height": "TALL",
            "contentInfo":{
              "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif",
              "forceRefresh": false
            }
          },
          "suggestions": [
            {
              "reply": {
                "text": "Suggestion #1",
                "postbackData": "suggestion_1"
              }
            },
            {
              "reply": {
                "text": "Suggestion #2",
                "postbackData": "suggestion_2"
              }
            }
          ]
        }
      }
    }
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Suggested replies to be used in the card
let suggestions = [
   {
      reply: {
         'text': 'Suggestion #1',
         'postbackData': 'suggestion_1',
      },
   },
   {
      reply: {
         'text': 'Suggestion #2',
         'postbackData': 'suggestion_2',
      },
   },
];

// Image to be displayed by the card
let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif';

// Definition of the card parameters
let params = {
   messageText: 'Hello, world!',
   messageDescription: 'RBM is awesome!',
   msisdn: '+12223334444',
   suggestions: suggestions,
   imageUrl: imageUrl,
   height: 'TALL',
};

// Send rich card to device
rbmApiHelper.sendRichCard(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.cards.CardOrientation;
import com.google.rbm.cards.MediaHeight;
import com.google.rbm.RbmApiHelper;
import com.google.rbm.SuggestionHelper;
…

try {
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();

   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();
   suggestions.add(
      new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply());

   suggestions.add(
      new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply());

   String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

   // Create a standalone rich card to send to the user
   StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard(
       "Hello, world!",
       "RBM is awesome!",
       imageUrl,
       MediaHeight.MEDIUM,
       CardOrientation.VERTICAL,
       suggestions
   );

   rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444");
} catch(Exception e) {
   e.printStackTrace();
}
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Suggested replies to be used in the card
suggestions = [
      messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'),
      messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')
]

# Image to be displayed by the card
image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif';

# Define rich card structure
rich_card = messages.StandaloneCard('VERTICAL',
                                    'Hello, world!',
                                    'RBM is awesome!',
                                    suggestions,
                                    image_url,
                                    None,
                                    None,
                                    'MEDIUM')

# Append rich card and send to the user
cluster = messages.MessageCluster().append_message(rich_card)
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
using RCSBusinessMessaging.Cards;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

List<Suggestion> suggestions = new List<Suggestion>
{
   // Create suggestion chips
   new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(),
   new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply()
};

string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif";

// Create rich card with suggestions
StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard(
   "Hello, world!",
   "RBM is awesome",
   imageUrl,
   MediaHeight.TALL,
   CardOrientation.VERTICAL,
   suggestions
);

// Send rich card to user
rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
هذا الرمز هو مقتطف من نموذج وكيل RBM.

لوحات العرض الدوّارة للبطاقات التفاعلية

تجمع لوحات العرض الدوّارة بين عدة بطاقات تفاعلية، ما يتيح للمستخدمين مقارنة العناصر والتفاعل مع كل منها على حدة.

يمكن أن تحتوي لوحات العرض الدوّارة على بطاقتَين تفاعليتَين كحدّ أدنى وعشر بطاقات كحدّ أقصى. يجب أن تتوافق البطاقات التفاعلية ضمن لوحات العرض الدوّارة مع المتطلبات العامة للبطاقات التفاعلية في ما يتعلق بالمحتوى والارتفاع، كما هو موضّح في مستندات البطاقات التفاعلية. لمزيد من المعلومات حول تصميم لوحة العرض الدوّارة ومواصفاتها، يُرجى الاطّلاع على مستندات لوحة العرض الدوّارة.

مثال

يرسل الرمز التالي لوحة عرض دوّارة لبطاقات تفاعلية. للاطّلاع على خيارات التنسيق والقيم، يُرجى مراجعة RichCard.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "richCard": {
      "carouselCard": {
        "cardWidth": "MEDIUM",
        "cardContents": [
          {
            "title": "Card #1",
            "description": "The description for card #1",
            "suggestions": [
              {
                "reply": {
                  "text": "Card #1",
                  "postbackData": "card_1"
                }
              }
            ],
            "media": {
              "height": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg",
                "forceRefresh": false
              }
            }
          },
          {
            "title": "Card #2",
            "description": "The description for card #2",
            "suggestions": [
              {
                "reply": {
                  "text": "Card #2",
                  "postbackData": "card_2"
                }
              }
            ],
            "media": {
              "height": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg",
                "forceRefresh": false
              }
            }
          }
        ]
      }
    }
  }
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Images for the carousel cards
let card1Image = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg';
let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg';

// Define the card contents for a carousel with two cards, each with one suggested reply
let cardContents = [
   {
      title: 'Card #1',
      description: 'The description for card #1',
      suggestions: [
         {
            reply: {
               text: 'Card #1',
               postbackData: 'card_1',
            }
         }
      ],
      media: {
         height: 'MEDIUM',
         contentInfo: {
            fileUrl: card1Image,
            forceRefresh: false,
         },
      },
   },
   {
      title: 'Card #2',
      description: 'The description for card #2',
      suggestions: [
         {
            reply: {
               text: 'Card #2',
               postbackData: 'card_2',
            }
         }
      ],
      media: {
         height: 'MEDIUM',
         contentInfo: {
            fileUrl: card2Image,
            forceRefresh: false,
         },
      },
   },
];

// Definition of carousel card
let params = {
   msisdn: '+12223334444',
   cardContents: cardContents,
};

// Send the device the carousel card defined above
rbmApiHelper.sendCarouselCard(params, function(response) {
   console.log(response);
});
هذا الرمز هو مقتطف من نموذج وكيل RBM.

جافا

import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.cards.CardOrientation;
import com.google.rbm.cards.CardWidth;
import com.google.rbm.cards.MediaHeight;
import com.google.rbm.RbmApiHelper;
import com.google.rbm.SuggestionHelper;
…

try {
            // Create an instance of the RBM API helper
            RbmApiHelper rbmApiHelper = new RbmApiHelper();

            List cardContents = new ArrayList();

            // Images for the carousel cards
            String card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg";

            // Create suggestions for first carousel card
            List card1Suggestions = new ArrayList();
            card1Suggestions.add(
                new SuggestionHelper("Card #1", "card_1"));

            cardContents.add(
                new StandaloneCardHelper(
                    "Card #1",
                    "The description for card #1",
                    card1Image,
                    card1Suggestions)
                    .getCardContent(MediaHeight.SHORT)
            );

            // Images for the carousel cards
            String card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg";

            // Create suggestions for second carousel card
            List card2Suggestions = new ArrayList();
            card2Suggestions.add(
                new SuggestionHelper("Card #2", "card_2"));

            cardContents.add(
                new StandaloneCardHelper(
                    "Card #2",
                    "The description for card #2",
                    card2Image,
                    card2Suggestions)
                    .getCardContent(MediaHeight.SHORT)
            );

            // Send the carousel to the user
            rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444");
        } catch(Exception e) {
            e.printStackTrace();
        }
هذا الرمز هو مقتطف من نموذج وكيل RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service
from rcs_business_messaging import messages

# Images for the carousel cards
card_image_1 = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg';
card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg';

# Suggested replies to be used in the cards
suggestions1 = [
      messages.SuggestedReply('Card #1', 'reply:card_1')
]

suggestions2 = [
      messages.SuggestedReply('Card #2', 'reply:card_2')
]

# Define the card contents for a carousel with two cards,
# each with one suggested reply
card_contents = []
card_contents.append(messages.CardContent('Card #1',
                                          'The description for card #1',
                                          card_image_1,
                                          'MEDIUM',
                                          suggestions1))

card_contents.append(messages.CardContent('Card #2',
                                          'The description for card #2',
                                          card_image_2,
                                          'MEDIUM',
                                          suggestions2))

# Send the device the carousel card defined above
carousel_card = messages.CarouselCard('MEDIUM', card_contents)
cluster = messages.MessageCluster().append_message(carousel_card)
cluster.send_to_msisdn('+12223334444')
هذا الرمز هو مقتطف من نموذج وكيل RBM.

#C

using Google.Apis.RCSBusinessMessaging.v1.Data;
using RCSBusinessMessaging;
using RCSBusinessMessaging.Cards;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

// Image references to be used in the carousel cards
string card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg";
string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg";

// Suggestion chip lists to be used in carousel cards
List<Suggestion> suggestions1 = new List<Suggestion>
{
   new SuggestionHelper("Card #1", "card_1").SuggestedReply()
};

List<Suggestion> suggestions2 = new List<Suggestion>
{
   new SuggestionHelper("Card #2", "card_2").SuggestedReply()
};

// Create the card content for the carousel
List<CardContent> cardContents = new List<CardContent>
{
   // Add items as card content
   new StandaloneCardHelper(
                    "Card #1",
                    "The description for card #1",
                    card1Image,
                    suggestions1).GetCardContent(),
   new StandaloneCardHelper(
                    "Card #2",
                    "The description for card #2",
                    card2Image,
                    suggestions2).GetCardContent()
};

// Send the carousel to the user
rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);
هذا الرمز هو مقتطف من نموذج وكيل RBM.