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

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

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

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

إذا أرسلت رسالة تحتوي على ميزات لا يدعمها جهاز المستخدم، سيعرض النظام الأساسي RBM رسالة خطأ ولا ينقل رسالتك.

الحد الأقصى لحجم رسالة AgentMessage السلسلة الكاملة هو 250 كيلوبايت.

جارٍ الإرسال إلى مستخدم غير متصل بالإنترنت

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

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

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

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

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

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

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

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

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

النص

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

مثال

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

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();
}
هذا الرمز مقتطف من نموذج وكيل 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 إلى RBM. تُسمى رسالة RBM التي تحتوي على ما يصل إلى 160 حرفًا بترميز UTF-8 بالرسالة الأساسية.

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

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

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

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

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

في ما يلي نموذج لرسالة نصية من نوع RBM بهدف التأكّد من المستخدم: رمزك هو <OTP> <appشق>.

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

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

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

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

راجِع أفضل الممارسات للاطّلاع على اقتراحات وحدود حجم الملفات.

مثال على عنوان 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.

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();
}
هذا الرمز مقتطف من نموذج وكيل 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'
   }
  }
}"

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

تتوافق ميزة RBM مع أنواع الوسائط التالية:

نوع الوسائط نوع المستند الإضافة إمكانية الاستخدام مع البطاقات التفاعلية
تطبيق/pdf ملف PDF .pdf لا
image/jpeg JPEG .jpeg و .jpg نعم
الصورة/gif GIF .gif نعم
image/png PNG .png نعم
فيديو/h263 فيديو H263 .h263 نعم
فيديو/m4v فيديو M4V .m4v نعم
الفيديو/mp4 فيديو MP4 ‎.mp4 نعم
فيديو/mpeg4 فيديو MPEG-4 .mp4 و .m4p نعم
فيديو/mpeg فيديو MPEG .mpeg نعم
فيديو/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);
});
هذا الرمز مقتطف من نموذج وكيل RBM.

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

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

الحد الأقصى لعدد الأحرف في الإجراءات المقترَحة هو 25 حرفًا.

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

طلب رقم

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

مثال

يرسل الرمز التالي إجراء اتصال. للاطّلاع على خيارات التنسيق والقيمة، يُرجى الاطّلاع على القسم 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')
هذا الرمز مقتطف من نموذج وكيل 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.

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();
}
هذا الرمز مقتطف من نموذج وكيل 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.

مشاركة موقع

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

مثال

يرسل الرمز التالي إجراء مشاركة الموقع. للاطّلاع على خيارات التنسيق والقيمة، راجِع القسم 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.

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

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.

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

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

مثال

يرسل الرمز التالي إجراء إنشاء حدث في التقويم. لمعرفة خيارات التنسيق والقيمة، يُرجى الاطّلاع على 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.

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
);
هذا الرمز مقتطف من نموذج وكيل RBM.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • قصيرة: 112 نقطة بكسل
  • متوسطة: 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.

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();
}
هذا الرمز مقتطف من نموذج وكيل 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.

منصّات العرض بعناصر متغيّرة للبطاقات التفاعلية

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

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

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

إذا لم يتمكن الجهاز من عرض جميع عناصر البطاقة بسبب قيود العرض أو ارتفاع البطاقة، سيقتطع 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);
});
هذا الرمز مقتطف من نموذج وكيل RBM.

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);
هذا الرمز مقتطف من نموذج وكيل RBM.