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

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

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

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

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

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

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

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

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

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

• أرسِل طلب إبطال لبدء عملية الإبطال.
• ضبط تاريخ انتهاء صلاحية الرسالة لإبطال الرسالة تلقائيًا في الوقت المناسب

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

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

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

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

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

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

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

النص

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

مثال

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

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!'
  }
}"

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

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

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

using RCSBusinessMessaging;
…

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

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

محتوى الرسالة الأساسي - تحويل الرسائل القصيرة 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) وتجزئة تُحدِّد التطبيق. وبعد مطابقة التجزئة مع التطبيق، يتم استخراج كلمة المرور لمرة واحدة (OTP) وإعادة توجيهها إلى التطبيق للتحقّق تلقائيًا من المستخدم.

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

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

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

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

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

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

مثال على عنوان URL الخاص بالملف

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

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'
    }
  }
}"

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

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

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

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 -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 مع أنواع الوسائط التالية:

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

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

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

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

مثال

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

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'
        }
      }
    ]
  }
}"

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

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

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

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

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

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

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

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

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

طلب رقم

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

مثال

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

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'
          }
        }
      }
    ]
  }
}"

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

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

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

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

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

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

مثال

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

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'
          }
        }
      }
    ]
  }
}"

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

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

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

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 -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': {}
        }
      }
    ]
  }
}"

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

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

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

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

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

مثال

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

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'
          }
        }
      }
    ]
  }
}"

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

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

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

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

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

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

مثال

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

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'
          }
        }
      }
    ]
  }
}"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• تنسيق قصير: 112 DP
• متوسط: 168 DP
• طويل: 264 DP

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

مثال

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

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'
              }
            }
          ]
        }
      }
    }
  }
}"

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

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

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

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 البطاقة حتى يمكن عرضها على الجهاز، وذلك باستخدام المنطق التالي:

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

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

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

مثال

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

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'
              }
            }
          }
        ]
      }
    }
  }
}"

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

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

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

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 هو 256 كيلوبايت. ويشمل ذلك النص الذي يتألف من حمولة JSON عند إرسال الرسائل المنظَّمة.

الحد الأقصى لحجم الملف الذي يمكن إرساله من خلال ميزة RBM هو 200 ميغابايت.

يمكن إرفاق ملف وسائط واحد فقط برسالة RBM واحدة.