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

يتواصل وكلاء RBM مع المستخدمين من خلال إرسال الرسائل واستلامها. لإرسال الرسائل إلى المستخدمين، يرسل موظّف الدعم طلبات الرسائل إلى واجهة برمجة التطبيقات RCS Business Messaging API. يمكن أن يتضمّن طلب واحد نصًا أو بطاقة غنية أو صورة أو فيديو بالإضافة إلى الردود المقترَحة والإجراءات المقترَحة.

إذا أرسلت رسالة إلى مستخدم لا يتيح جهازه ميزة RCS أو لم يتم تفعيل ميزة RCS عليه، ستظهر رسالة الخطأ 404 على منصة RBM. في هذه الحالة، يمكنك محاولة التواصل مع المستخدم من خلال طُرق النسخ الاحتياطي المحدّدة في بنيتك الأساسية.

إذا أرسلت رسالة إلى مستخدم RCS على شبكة لم يتم إطلاق وكيلك عليها بعد، أو على شبكة لم تفعِّل حركة RCS، ستُظهر منصة RBM خطأ 403.

إذا أرسلت رسالة تتضمّن ميزات لا يتوافق معها جهاز المستخدم، تعرِض منصّة RBM رسالة خطأ ولا تسليم رسالتك.

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

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

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

تحذف ميزة "إدارة الرسائل التلقائية" أي رسائل لم يتم تسليمها بعد 30 يومًا من إرسالها.

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

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

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

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

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

لمعرفة خيارات التنسيق والقيمة، راجِع AgentMessage.

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

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

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

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

الحد الأقصى لحجم الملف الذي يمكن إرساله من خلال ميزة "الاستجابة السريعة للإعلانات" هو 100 ميغابايت. يمكن إرفاق ملف PDF أو ملف وسائط واحد فقط في رسالة RBM واحدة. يُرجى الرجوع إلى الوسائط وملفات 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!'
  }
}"

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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java

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();
}
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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')
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

#C

using RCSBusinessMessaging;
…

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
);
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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

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

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

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

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

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

أثناء عملية التحقّق، تنتظر واجهة برمجة التطبيقات SMS Retriever API رسالة إعادة توجيه البريد الإلكتروني (RBM). يجب أن تحتوي هذه الرسالة على مفتاح مرور صالح لمدة ساعة وقيمة تجزئة تحدّد التطبيق. بعد مطابقة القيمة التجزئة مع التطبيق، يتم استخراج مفتاح المرور الصالح لمدة ساعة وإعادة توجيهه إلى التطبيق للتحقّق من المستخدم تلقائيًا.

في ما يلي نموذج رسالة نصية من RBM لإثبات هوية المستخدم: رمزك هو <OTP> <hash app>.

على سبيل المثال، Your code is 123456 M8tue43FGT.

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

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

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

عند تحديد الملفات حسب عنوان URL، من أفضل الممارسات ضبط contentMessage.forceRefresh على false. يؤدي ضبط القيمة contentMessage.forceRefresh على true إلى إجبار ميزة "الاستجابة السريعة للرسائل" على جلب محتوى جديد من عنوان URL المحدّد، حتى إذا كان محتوى عنوان 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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java

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();
}
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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')
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

#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");
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

بدلاً من ذلك، يمكنك تحميل الوسائط قبل إرسالها في رسالة باستخدام رمز 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'
   }
  }
}"

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

تتيح ميزة "الاستهداف بالاستناد إلى الجمهور المستهدَف" أنواع الوسائط التالية:

نوع الوسائط نوع المستند الإضافة التوافق مع البطاقات التفاعلية
application/ogg ملف صوتي بتنسيق OGG ‎.ogx لا
application/pdf PDF ‎.pdf لا
audio/aac صوت بترميز AAC ‎.aac لا
audio/mp3 ملف صوتي بتنسيق MP3 ‎.mp3 لا
audio/mpeg صوت MPEG ‎.mpeg لا
audio/mpg MPG audio ‎.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 نعم

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

ترشِد الردود المقترَحة المستخدمين خلال المحادثات من خلال تقديم ردود يعرف موظّف الدعم كيفية الردّ عليها. يرسل موظّف الدعم الردود المقترَحة في قوائم شرائح الاقتراحات أو في بطاقات البحث الذكية.

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

يجب ألا يزيد عدد الأحرف في الردود المقترَحة عن 25 حرفًا.

مثال

يُرسِل الرمز التالي نصًا يتضمّن ردّين مقترَحين. للحصول على خيارات التنسيق والقيمة، يُرجى الاطّلاع على 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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java

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();
}
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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، أو إنشاء حدث تقويمي. يرسل موظّف الدعم الإجراءات المقترَحة في قوائم شرائح الاقتراحات أو في بطاقات البحث الذكية.

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

يجب أن تتألف الإجراءات المقترَحة من 25 حرفًا كحدّ أقصى.

لمعرفة خيارات التنسيق والقيمة، راجِع SuggestedAction.

طلب رقم

يوجّه الإجراء Dial المستخدم إلى طلب رقم هاتف يحدّده موظّف الدعم. يمكن أن تتضمّن أرقام الهواتف الأرقام (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.

Java

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')
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

#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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java

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();
}
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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')
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

#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
);
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

مشاركة موقع

يتيح إجراء "مشاركة الموقع الجغرافي" للمستخدم إرسال موقع جغرافي إلى موظّف الدعم. لا يشير الموقع الجغرافي الذي يحدّده المستخدم بالضرورة إلى موقعه الجغرافي.

مثال

تُرسِل التعليمة البرمجية التالية إجراء مشاركة الموقع الجغرافي. للاطّلاع على خيارات التنسيق والقيمة، يُرجى الاطّلاع على 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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java

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();
}
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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
);
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

فتح عنوان URL

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

يتيح إجراء OpenURL أيضًا استخدام WebViews المدمجة. راجِع فتح عنوان URL باستخدام WebView.

مثال

تُرسِل التعليمة البرمجية التالية إجراء فتح عنوان 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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java


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" صفحة الويب المحدّدة داخل تطبيق المراسلة باستخدام محرّك العرض في المتصفّح التلقائي. يتيح ذلك للمستخدم التفاعل مع صفحة الويب بدون مغادرة محادثة RBM. لتفعيل عروض الويب، يُرجى الاطّلاع على OpenURLApplication.

تتضمّن عروض الويب ثلاثة أوضاع عرض. لمعرفة خيارات التنسيق والقيمة، راجِع 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"
         }
       }
     }
   ]
 }
}'

Java

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;
    }

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

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

مثال

تُرسِل التعليمة البرمجية التالية إجراءً لإنشاء حدث في التقويم. للحصول على خيارات التنسيق والقيمة، يُرجى الاطّلاع على 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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java


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
);
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

إنشاء رسائل

يؤدي الإجراء "إنشاء" إلى فتح تطبيق المراسلة لدى المستخدم حتى يتمكّن من إرسال رسائل إلى رقم هاتف محدّد مسبقًا، مثل رقم خدمة دعم العملاء.

هناك ثلاثة أنواع من إجراءات الإنشاء. للاطّلاع على أمثلة مرئية، يُرجى الاطّلاع على مقالة إنشاء رسالة نصية أو صوتية أو رسالة فيديو.

  • إنشاء رسالة نصية: يؤدي هذا الإجراء إلى فتح تطبيق المراسلة مع نص مملوء مسبقًا ليتم إرساله من قِبل المستخدم.
  • إنشاء رسالة صوتية: يؤدي هذا الإجراء إلى فتح تطبيق المراسلة وتشغيل الميكروفون حتى يتمكّن المستخدم من تسجيل الصوت.
  • إنشاء رسالة فيديو: يؤدي هذا الإجراء إلى فتح تطبيق المراسلة وتشغيل الكاميرا حتى يتمكّن المستخدم من تسجيل فيديو.

مثال

تُرسِل التعليمة البرمجية التالية إجراء كتابة. لمعرفة خيارات التنسيق والقيمة، راجِع ComposeAction.

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': 'Compose a text message',
          'postbackData': 'postback_data_123',
          'composeAction': {
            'composeTextMessage': {
              'phoneNumber': '+15556667777'
              'text': 'Draft to go into the send message text field.'
            }
          }
        }
      },{
        'action': {
          'text': 'Compose an audio message',
          'postbackData': 'postback_data_456',
          'composeAction': {
            'composeRecordingMessage': {
              'phoneNumber': '+15556667777'
              'type': 'ACTION_TYPE_AUDIO'
            }
          }
        }
      },{
        'action': {
          'text': 'Compose a video message',
          'postbackData': 'postback_data_789',
          'composeAction': {
            'composeRecordingMessage': {
              'phoneNumber': '+15556667777'
              'type': 'ACTION_TYPE_VIDEO'
            }
          }
        }
      }
    ]
  }
}"

Node.js

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

// Define a compose suggested action
let suggestions = [
   {
      action: {
         text: 'Compose a text message',
         postbackData: 'postback_data_123',
         'composeAction': {
            'composeTextMessage': {
               'phoneNumber': '+15556667777'
               'text': 'Draft to go into the send message text field.'
            }
         }
      }
   },{
      action: {
         text: 'Compose an audio message',
         postbackData: 'postback_data_456',
         'composeAction': {
            'composeRecordingMessage': {
               'phoneNumber': '+15556667777'
               'type': 'ACTION_TYPE_AUDIO'
            }
         }
      }
   },{
      action: {
         text: 'Compose a video message',
         postbackData: 'postback_data_789',
         'composeAction': {
            'composeRecordingMessage': {
               'phoneNumber': '+15556667777'
               'type': 'ACTION_TYPE_VIDEO'
            }
         }
      }
   }
];

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);
});

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.ComposeAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.ComposeRecordingMessage;
import com.google.api.services.rcsbusinessmessaging.v1.model.ComposeTextMessage;
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 compose text suggested action
   Suggestion composeTextSuggestion =  getComposeTextAction()
   suggestions.add(composeTextSuggestion);

   // creating compose audio suggested action
   Suggestion composeAudioSuggestion =  getComposeAudioAction()
   suggestions.add(composeAudioSuggestion);


   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

 /**
   * Creates a compose text suggested action.
   * @return A suggestion object for a compose text action.
 */
 private Suggestion getComposeTextAction() {
        // creating a compose text suggested action
        ComposeTextMessage message = new ComposeTextMessage();
        message.setPhoneNumber("+12223334444");
        message.setText("Draft to go into the send message text field.");
        ComposeAction composeAction = new ComposeAction();
        composeAction.setComposeTextMessage(message);

        // creating a suggested action based on a compose text action
        SuggestedAction suggestedAction = new SuggestedAction();
        suggestedAction.setText("Send a text message");
        suggestedAction.setPostbackData("postback_data_123");
        suggestedAction.setComposeAction(composeAction);

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

        return suggestion;
    }

    /**
     * Creates a compose audio suggested action.
     * @return A suggestion object for a compose audio action.
    */
    private Suggestion getComposeAudioAction() {
        // creating a compose audio suggested action
        ComposeRecordingMessage message = new ComposeRecordingMessage();
        message.setPhoneNumber("+12223334444");
        message.setType("ACTION_TYPE_AUDIO");
        ComposeAction composeAction = new ComposeAction();
        composeAction.setComposeRecordingMessage(message);

        // creating a suggested action based on a compose text action
        SuggestedAction suggestedAction = new SuggestedAction();
        suggestedAction.setText("Send an audio message");
        suggestedAction.setPostbackData("postback_data_456");
        suggestedAction.setComposeAction(composeAction);

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

        return suggestion;
    }

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.ComposeTextMessageAction(
          'Send a text message',
          'postback_data_123',
          '+15556667777',
          '')
      messages.ComposeRecordingMessageAction(
          'Send an audio message',
          'postback_data_456',
          '+15556667777',
          'ACTION_TYPE_AUDIO')
  
  ]

  # 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')

#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 compose text suggested action
  ComposeTextMessage composeTextMessage = new ComposeTextMessage{
      PhoneNumber = "+15556667777"
      Text = "Draft to go into the send message text field."
  };

  ComposeAction composeAction = new ComposeAction
  {
      ComposeTextMessage = composeTextMessage
  };

  // Creating a suggested action based on a compose action
  SuggestedAction suggestedAction = new SuggestedAction
  {
      Text = "Send a text message",
      PostbackData = "postback_data_123",
      ComposeAction = composeAction
  };

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

  List suggestions = new List
  {
      suggestion
  };

  rbmApiHelper.SendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
  );

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

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

تتضمّن القائمة الردود المقترَحة و الإجراءات المقترَحة.

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

لمعرفة خيارات التنسيق والقيمة، راجِع AgentContentMessage.

بطاقات البحث الذكية

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

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

  • صورة أو فيديو
  • نص العنوان
  • نص الوصف
  • قائمة بالردود المقترَحة والإجراءات المقترَحة (4 إجراءات كحد أقصى)

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

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

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

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

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

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

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

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

مثال

تُرسِل التعليمة البرمجية التالية بطاقة تفاعلية تتضمّن صورة وreplies مقترَحة. لمعرفة خيارات التنسيق والقيمة، راجِع 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.

Java

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();
}
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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')
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

#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");
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

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

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

يمكن أن تحتوي لوحات العرض الدوّارة على بطاقتَين بحدّ أدنى وعشر بطاقات بحدّ أقصى. يجب أن تكون البطاقات الغنية بصريًا ضمن لوحات العرض الدوّارة متوافقة مع متطلبات البطاقة الغنية بصريًا العامة المتعلّقة بالمحتوى والارتفاع.

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

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

إذا تعذّر على أحد الأجهزة عرض جميع عناصر البطاقة بسبب قيود الشاشة أو ارتفاع البطاقة، تقتطع ميزة RBM البطاقة إلى أن تصبح قابلة للعرض على الجهاز، وذلك باستخدام المنطق التالي:

  1. اختصر الوصف إلى سطر واحد.
  2. اختصر العنوان إلى سطر واحد.
  3. إزالة الاقتراحات التي لا تتناسب مع البطاقة، بدءًا من نهاية القائمة المحدّدة
  4. إزالة الوصف
  5. إزالة العنوان

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

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

مثال

تُرسِل التعليمة البرمجية التالية لوحة عرض دوّارة لبطاقة تفاعلية. للحصول على خيارات التنسيق والقيمة، راجِع 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/kitchen-sink-sample-images/cute-dog.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/kitchen-sink-sample-images/elephant.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/kitchen-sink-sample-images/cute-dog.jpg';
let card2Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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);
});
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.

Java

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/kitchen-sink-sample-images/cute-dog.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/kitchen-sink-sample-images/elephant.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/kitchen-sink-sample-images/cute-dog.jpg';
card_image_2 = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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/kitchen-sink-sample-images/cute-dog.jpg";
string card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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);
هذه التعليمات البرمجية هي مقتطف من نموذج وكيل نموذج تحسين الأداء من خلال الربط.
السابق
أجهزة الاختبار
التالي
إلغاء الرسائل