ارسال کردن پیام‌ها

نمایندگان «RCS ویژه کسب‌وکارها» با ارسال و دریافت پیام با کاربران ارتباط برقرار می‌کنند. برای ارسال پیام به کاربران، نماینده شما درخواست‌های پیام را به میانای برنامه‌سازی کاربردی «پیام‌رسانی کسب‌وکاری RCS» ارسال می‌کند. یک درخواست می‌تواند شامل نوشتار، کارت‌های غنی، رسانه و فایل‌های PDF، پاسخ‌های پیشنهادی، و کنش‌های پیشنهادی باشد.

پلاتفرم ‹RCS ویژه «کسب‌وکارها»› در شرایط خاصی خطا برمی‌گرداند تا به شما کمک کند ارسال پیام را مدیریت کنید:

  • اگر پیامی به کاربری ارسال کنید که دستگاهش از «سرویس‌های ارتباطی غنی» پشتیبانی نمی‌کند یا «سرویس‌های ارتباطی غنی» در آن فعال نیست، پلاتفرم «RCS ویژه کسب‌وکارها» خطای 404 NOT_FOUND را برمی‌گرداند. دراین‌صورت، می‌توانید ازطریق روش‌های جایگزین تعریف‌شده در زیرساختتان با کاربر تماس بگیرید.
  • اگر پیامی به کاربر «سرویس‌های ارتباطی غنی» در شبکه‌ای ارسال کنید که نماینده شما هنوز در آن راه‌اندازی نشده است، یا در شبکه‌ای که ترافیک «سرویس‌های ارتباطی غنی» را فعال نکرده است، پلاتفرم «سرویس‌های ارتباطی غنی» ویژه «کسب‌وکارها» خطای 404 NOT_FOUND را برمی‌گرداند.
  • اگر پیامی با ویژگی‌هایی ارسال کنید که دستگاه کاربر از آن‌ها پشتیبانی نمی‌کند، پلاتفرم «RCS ویژه کسب‌وکارها» خطای 400 INVALID_ARGUMENT را برمی‌گرداند و پیامتان را تحویل نمی‌دهد.

به‌عنوان بخشی از استراتژی پیام‌رسانی چندکاناله، بهتر است پیام‌هایی را که پس‌از مدت زمان معقولی تحویل داده نشده‌اند لغو کنید و آن‌ها را ازطریق کانال دیگری ارسال کنید. برای لغو خودکار پیام‌ها در زمانی ازپیش‌تعریف‌شده، انقضای پیام را تنظیم کنید.

گیرنده آفلاین است

اگر گیرنده آفلاین باشد، پلاتفرم ‹RCS ویژه «کسب‌وکارها»› همچنان پیام را برای ارسال می‌پذیرد. پاسخ 200 OK دریافت می‌کنید و پلاتفرم «RCS ویژه کسب‌وکارها» پیام را نگه می‌دارد و به‌مدت ۳۰ روز برای تحویل دوباره تلاش می‌کند. نیازی نیست از RCS ویژه «کسب‌وکارها» بخواهید پیام را دوباره ارسال کند.

‫‹RCS ویژه «کسب‌وکارها»› هر پیام تحویل‌نشده‌ای را ۳۰ روز پس‌از ارسال حذف می‌کند.

بسته به مورد استفاده نماینده‌تان، ممکن است بخواهید پیام تحویل‌نشده را قبل‌از این مهلت ۳۰ روزه لغو کنید. لغو کردن می‌تواند از دریافت پیام قدیمی توسط کاربران آفلاین هنگام آنلاین شدن مجدد جلوگیری کند. چندین روش برای لغو پیام وجود دارد:

تنظیم زمان انقضای پیام

آیا پیام عامل شما حساس به زمان است؟ برای مثال، گذرواژه‌های یک‌بارمصرف فقط برای مدت کوتاهی معتبر هستند. عرضه‌های موقت منقضی می‌شوند. و یادآوری‌های قرار بعداز تاریخ قرار دیگر مربوط نیستند. برای اینکه پیام‌ها به‌موقع و مرتبط باشند، انقضای پیام تنظیم کنید. این کار می‌تواند از دریافت محتوای قدیمی توسط کاربران آفلاین هنگام بازگشت به حالت آنلاین جلوگیری کند. انقضا همچنین نشانه خوبی برای فراخوانی استراتژی پیام‌رسانی جایگزین شما است تا کاربران اطلاعات موردنیاز خود را به‌موقع دریافت کنند.

برای تنظیم انقضای پیام، یکی از فیلدهای زیر را در پیام نماینده مشخص کنید:

  • ‫expireTime: زمان دقیق انقضای پیام به ساعت هماهنگ جهانی.
  • ttl(زمان زنده): مدت زمان قبل‌از منقضی شدن پیام.

برای گزینه‌های قالب‌بندی و مقدار، AgentMessage را ببینید.

حداکثر مقدار برای ttl و expireTime ۱۵ روز پس‌از ارسال پیام است.

حداقل مقدار برای ttl و expireTime شش ثانیه پس‌از ارسال پیام است.

توصیه‌هایی برای تنظیم انقضای پیام

  • برای پیام‌های اصالت‌سنجی (گذرواژه یک‌بارمصرف): ttl را روی ۱۵ ثانیه یا بیشتر بعداز ارسال پیام تنظیم کنید تا احتمال شرایط رقابتی تحویل و لغو به‌طور قابل‌توجهی کاهش یابد.

  • برای پیام‌های تراکنشی و تبلیغاتی: زمان انقضای طولانی‌تری تنظیم کنید (حداقل ۶۰ ثانیه، یا بسته به مورد استفاده، چند دقیقه تا چند ساعت) زیرا دستگاه‌ها برای اسکن کردن پیام‌ها و بارگیری یا پردازش محتوای رسانه غنی به زمان بیشتری نیاز دارند و ممکن است کاربران با قطعی‌های کوتاه اتصال مواجه شوند (برای مثال، در آسانسور یا تونل).

زمان بقا (TTL) برای پیام

وقتی TTL را برای پیام «RCS ویژه کسب‌وکارها» تنظیم می‌کنید، مشخص می‌کنید که پیام تا چه مدت باید معتبر و قابل‌تحویل درنظر گرفته شود. اگر پیام در این دوره TTL با موفقیت به دستگاه کاربر ارسال نشود، پلاتفرم «RCS ویژه کسب‌وکارها» به‌طور خودکار تلاش می‌کند آن را لغو کند.

وقتی لغو پیام را شروع می‌کنید، از پلاتفرم ‹RCS ویژه «کسب‌وکارها»› درخواست می‌کنید که تلاش برای ارسال آن پیام خاص را متوقف کند. بااین‌حال، این اقدام فقط بر تلاش‌های تحویل در آینده تأثیر می‌گذارد. اگر دستگاه کاربر قبلاً پیام را با موفقیت بازیابی کرده باشد، پیام درحال پردازش است و پلاتفرم «RCS ویژه کسب‌وکارها» نمی‌تواند پیام را از دستگاه کاربر لغو کند.

آنچه باید درباره اعلان‌ها انتظار داشته باشید:

  • پیام درطول TTL تحویل داده شده است: اگر دستگاه کاربر آنلاین شود و پیام را قبل‌از منقضی شدن TTL دریافت کند، اعلان DELIVERED را دریافت می‌کنید. هیچ اعلان لغوی ارسال نخواهد شد، زیرا پیام با موفقیت تحویل داده شده است. این رایج‌ترین و موردانتظارترین سناریو است.

  • پیام قبل‌از انقضای TTL تحویل داده نشده است: اگر TTL قبل‌از رسیدن پیام به دستگاه کاربر منقضی شود (برای مثال، دستگاه آفلاین باشد)، پلاتفرم «RCS ویژه کسب‌وکارها» تلاش می‌کند پیام را لغو کند. اعلان TTL_EXPIRATION_REVOKED را دریافت می‌کنید که نشان می‌دهد پیام باموفقیت از صف تحویل برداشته شده است. در این صورت، کاربر پیام را دریافت نخواهد کرد.

توصیه‌هایی برای رسیدگی به موارد حاشیه‌ای

سیستم ما تحویل پیام «سرویس‌های ارتباطی غنی ویژه کسب‌وکارها» و انقضای TTL را به‌طور موازی پردازش می‌کند. به‌همین دلیل، به‌ندرت ممکن است با موارد خاصی مواجه شوید که زمان‌بندی اعلان‌ها غیرمنتظره باشد. برای مثال، ممکن است هم اعلان تحویل و هم اعلان TTL را دریافت کنید یا هیچ‌کدام را دریافت نکنید.

توصیه‌های ما برای مدیریت اعلان‌های پیام ‹RCS ویژه «کسب‌وکارها»› در اینجا آمده است:

  • اعلان DELIVERED: اگر اعلان DELIVERED برای پیامی دریافت کنید، تأیید می‌کند که پیام به کاربر رسیده است. می‌توانید با خیال راحت هرگونه اعلان TTL بعدی را برای آن پیام خاص نادیده بگیرید.

  • اعلان TTL_EXPIRATION_REVOKED: اگر اعلان TTL با وضعیت TTL_EXPIRATION_REVOKED دریافت کنید، به این معنی است که سیستم «RCS ویژه کسب‌وکارها» تلاش برای تحویل آن پیام خاص را متوقف می‌کند. باید این پیام را به‌عنوان پیام تحویل‌نشده درنظر بگیرید و درصورت نیاز، استراتژی بازگشت به حالت قبلی را اجرا کنید.

  • اعلان TTL با هر وضعیت دیگری: اگر اعلان TTL با هر وضعیت دیگری دریافت کردید، این نشان‌دهنده تلاش ناموفق برای لغو است.

    • برای پیام‌های مهم، مثل گذرواژه‌های یک‌بارمصرف (OTP)، روش جایگزین خود را راه‌اندازی کنید.
    • برای پیام‌های غیربحرانی، تصمیم بگیرید که آیا می‌خواهید بازگشت را آغاز کنید یا نه.
  • بدون اعلان: در موارد نادر، ممکن است سیستم نتواند اعلان TTL را ارسال کند و کارخواه نیز ممکن است نتواند اعلان تحویل را تولید کند. این مورد بسیار نادر است.

تنظیم نوع ترافیک پیام

RBM API شامل فیلد messageTrafficType برای دسته‌بندی پیام‌ها است. درحالی‌که موارد استفاده نماینده همچنان رفتار نماینده و اینکه کدام قوانین کسب‌وکار اعمال می‌شود را تعریف می‌کند، messageTrafficType امکان دسته‌بندی دقیق‌تر محتوای پیام را فراهم می‌کند. درنهایت، این امر باعث می‌شود که یک عامل بتواند چندین مورد استفاده را مدیریت کند. درحال‌حاضر، این تغییر تأثیری بر موارد استفاده از عامل یا قوانین کسب‌وکار ندارد.

این فیلد اختیاری است، اما توصیه می‌شود آن را اکنون تنظیم کنید تا وقتی فیلد الزامی شد، خطایی دریافت نکنید.

برای تنظیم نوع ترافیک پیام، messageTrafficType مناسب را براساس محتوای هر پیام به آن اختصاص دهید. جدول زیر انواع ترافیک پشتیبانی‌شده و موارد استفاده موردانتظار از نماینده را فهرست می‌کند. این نگاشت راهنمایی توصیه‌شده برای استفاده موردانتظار است و درحال‌حاضر محدودیتی نیست که توسط میانای برنامه‌سازی کاربردی اعمال شود.

نوع ترافیک محتوای پیام مورد استفاده توصیه‌شده برای نماینده
AUTHENTICATION برای پیام‌های اصالت‌سنجی. OTP
TRANSACTION برای پیام‌های مربوط به خدمات یا محصولات موجود کاربر. برای مثال: تأییدیه‌ها، رسیدهای پرداخت، یا جزئیات رزرو. تراکنشی یا چندمنظوره
PROMOTION برای پیام‌های تبلیغاتی مانند پیشنهادها، تخفیف‌ها، اعلامیه‌ها، یا سایر محتواهای تبلیغاتی. تبلیغاتی یا چندمنظوره
SERVICEREQUEST برای پیام‌های مربوط به سرویس‌هایی که کاربر صراحتاً درخواست کرده است. گذرواژه یک‌بارمصرف، تراکنشی، تبلیغاتی، یا چندمنظوره
ACKNOWLEDGEMENT برای پیام‌هایی که برای تأیید اقدام کاربر استفاده می‌شوند – به‌ویژه درخواست لغو اشتراک. این ایمیل تأیید می‌کند که درخواست کاربر دریافت شده و درحال پردازش است. گذرواژه یک‌بارمصرف، تراکنشی، تبلیغاتی، یا چندمنظوره

اگر نوع ترافیک تنظیم نشده باشد، سیستم نوع پیش‌فرض را برای مورد استفاده نماینده اختصاص می‌دهد.

مورد استفاده عامل نوع ترافیک پیش‌فرض
OTP AUTHENTICATION
تراکنشی TRANSACTION
تبلیغاتی PROMOTION
چندمنظوره MESSAGE_TRAFFIC_TYPE_UNSPECIFIED

عوامل چندکاربردی نوع ترافیک پیش‌فرض ندارند. باید نوع ترافیک را به‌طور صریح برای هر پیام براساس محتوای آن تنظیم کنید. اگر مقدار MESSAGE_TRAFFIC_TYPE_UNSPECIFIED را جایگزین نکنید، پیام همچنان پذیرفته می‌شود و بدون طبقه‌بندی خاصی برای نوع ترافیک ارسال می‌شود.

حد مجاز اندازه پیام

حداکثر اندازه کل AgentMessage رشته‌ای‌شده ۲۵۰ کیلوبایت است. بخش نوشتاری پیام حد مجاز خودش را دارد که ۳۰۷۲ نویسه است.

برای جلوگیری از مصرف غیرمنتظره داده برای کاربران، حداکثر اندازه فایلی که می‌توان ازطریق «RCS ویژه کسب‌وکارها» ارسال کرد ۱۰۰ مبی‌بایت است و مجموع اندازه همه رسانه‌ها و پیوست‌های PDF در یک پیام «RCS ویژه کسب‌وکارها» نباید از ۱۰۰ مبی‌بایت بیشتر شود. (۱ مبی‌بایت = ۱٬۰۴۸٬۵۷۶ بایت). برای اطلاعات بیشتر، به فایل‌های رسانه و PDF مراجعه کنید.

نوشتار

ساده‌ترین پیام‌ها از نوشتار ساخته شده‌اند. پیامک‌ها برای انتقال اطلاعات بدون نیاز به عناصر دیداری، تعامل پیچیده، یا پاسخ مناسب‌ترند.

مثال

کد زیر پیام نوشتار ساده‌ای ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، phones.agentMessages.create را ببینید.

cURL

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

Node.js

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

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

// Send a simple message to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

import com.google.rbm.RbmApiHelper;
…

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

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444"
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

# Send text message to the device
messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

using RCSBusinessMessaging;
…

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
);
این کد گزیده‌ای از عامل نمونه RBM است.

محتوای پیام پایه - تبدیل پیامک

شرکت‌های مخابراتی مدل‌های صورت‌حساب را برای پشتیبانی از انتقال پیام‌های پیامکی به «سرویس‌های ارتباطی غنی» ویژه «کسب‌وکارها» معرفی کرده‌اند. پیام «RCS ویژه کسب‌وکارها» که حداکثر ۱۶۰ نویسه UTF-8 داشته باشد «پیام پایه» نامیده می‌شود.

هنگام ساختن درخواست برای ارسال «پیام ساده»، به‌خاطر داشته باشید که نویسه‌ها به‌عنوان ۱ بایت (UTF-8) شمرده می‌شوند. اگر پیامی ارسال کنید که حاوی نویسه‌های خاصی مانند اموجی یا مجموعه نویسه‌های چندبایتی باشد، هر نویسه به‌عنوان ۲ تا ۴ نویسه UTF-8 یا بیشتر محسوب می‌شود.

برای بررسی طول نوشتار، مقداری نوشتار در چارگوش وارد کنید:

مشتریان RCS ممکن است پیش‌نمایش پیوند را پیاده‌سازی کنند. اگر پیام «RCS ویژه کسب‌وکارها» که فقط نوشتار دارد حاوی نشانی وب برای وب‌سایتی با برچسب‌های openGraph باشد، کارخواه می‌تواند پیش‌نمایشی (تصویر، عنوان، و غیره) تولید کند و تجربه غنی‌تری ارائه دهد. برای مثال، پیام ساده‌ای با پیش‌نمایش نشانی وب را ببینید.

توجه داشته باشید که کارخواه «سرویس‌های ارتباطی غنی» ممکن است به کاربر اجازه دهد پیش‌نمایش پیوند را غیرفعال کند.

گذرواژه‌های یک‌بارمصرف برای درستی‌سنجی کاربر

می‌توانید از «RCS ویژه کسب‌وکارها» برای ارسال گذرواژه‌های یک‌بارمصرف (OTP) برای درستی‌سنجی خودکار کاربر با میانای برنامه‌سازی کاربردی بازیابی پیامک استفاده کنید. ای‌پی‌آی اختصاصی‌ای برای خواندن گذرواژه‌های یک‌بارمصرفی که ازطریق «RCS ویژه کسب‌وکارها» می‌رسند وجود ندارد.

نحوه عملکرد آن برای Android

برای برنامه‌های Android که در SMS Retriever API ثبت شده‌اند، این میانای برنامه‌سازی کاربردی به پیام «RCS ویژه کسب‌وکارها» با قالب‌بندی صحیح گوش می‌دهد. این پیام باید هم حاوی گذرواژه یک‌بارمصرف باشد و هم درهم‌سازی یکتایی که برنامه‌تان را شناسایی می‌کند.

وقتی پیام RCS ویژه «کسب‌وکارها» با قالب صحیح دریافت می‌شود، SMS Retriever API آن را درست مانند گذرواژه یک‌بارمصرف پیامکی پردازش می‌کند. پس‌از اینکه درهم‌سازی با برنامه‌تان مطابقت داده شد، گذرواژه یک‌بارمصرف استخراج می‌شود و برای درستی‌سنجی خودکار کاربر به برنامه‌تان ارسال می‌شود.

  • نمونه پیامک ‹RCS ویژه «کسب‌وکارها»› برای درستی‌سنجی کاربر: Your code is <OTP><app hash>.
  • مثال: Your code is 123456 M8tue43FGT.

برای کسب اطلاعات بیشتر درباره SMS Retriever و میاناهای برنامه‌سازی کاربردی مرتبط، اسناد SMS Retriever را ببینید. برای جزئیات درباره درستی‌سنجی خودکار کاربر در برنامه‌هایی که با SMS Retriever API ثبت شده‌اند، این نمودار جریان را ببینید.

نحوه عملکرد برای iOS

برای iOS، مدیریت OTP داخلی سیستم به‌طور خودکار OTPهای «RCS ویژه کسب‌وکارها» را برای تکمیل خودکار شناسایی و پیشنهاد می‌کند، درست مانند OTPهای پیامکی. برای اینکه برنامه iOS بتواند گذرواژه یک‌بارمصرف را بخواند، به ادغام API خاصی نیاز نیست.

فایل‌های رسانه‌ای و PDF

وقتی پیامی با تصویر، ویدیو، صدا، یا فایل PDF ارسال می‌کنید، نماینده شما باید نشانی وب با دسترسی عمومی برای محتوا ارائه دهد یا فایل را مستقیماً بارگذاری کند.

حداکثر اندازه فایلی که می‌توان ارسال کرد ۱۰۰ مبی‌بایت است و مجموع اندازه همه پیوست‌های رسانه‌ای و PDF در یک پیام نباید از ۱۰۰ مبی‌بایت بیشتر باشد.

فشرده‌سازی و تراتبدیل رسانه

پلاتفرم «RCS ویژه کسب‌وکارها» به‌طور خودکار فایل‌های رسانه‌ای (مانند تصاویر و ویدیوها) را پیش‌از ارسال تراتبدیل و فشرده می‌کند تا مطمئن شود که به‌سرعت بارگیری می‌شوند و در شبکه‌ها و دستگاه‌های مختلف به‌خوبی کار می‌کنند.

فشرده‌سازی براساس کیفیت رسانه ورودی انجام می‌شود نه صرفاً براساس محدودیت‌های اندازه فایل. این یعنی فایل می‌تواند فشرده شود حتی اگر اندازه آن بسیار کمتر از حد مجاز ۱۰۰ مبی‌بایت باشد. استانداردهای تراتبدیل دائماً تغییر می‌کنند، بنابراین هیچ حد ثابتی برای اندازه فایل وجود ندارد که تعیین کند چه زمانی تراتبدیل دور زده می‌شود. قالب‌های رسانه، ابعاد، و نرخ‌های فشرده‌سازی مختلف را امتحان کنید تا بهترین توازن را برای بار مفیدتان پیدا کنید.

مشخصات ریزعکس

برای فایل‌های رسانه‌ای، می‌توانید تصویر ریزعکسی را نیز مشخص کنید که به کاربران امکان می‌دهد قبل‌از کلیک کردن روی محتوا، پیش‌نمایش آن را ببینند. برای فایل‌های صوتی، از ابزاره صوتی پیش‌فرض به‌عنوان جای‌بان استفاده می‌شود.

  • حداکثر اندازه فایل ریزعکس ۱۰۰ کیلوبایت است. برای تجربه کاربری بهینه، توصیه می‌کنیم ۵۰ کیلوبایت یا کمتر باشد.
  • نسبت ابعادی ریزعکس باید با نسبت فایل اصلی مطابقت داشته باشد.

ذخیره در حافظه نهان و مدیریت نشانی وب

پلاتفرم ‹RCS ویژه «کسب‌وکارها»› فایل‌ها را به‌مدت ۶۰ روز ذخیره می‌کند و میانای برنامه‌سازی کاربردی شناسه فایلی را برمی‌گرداند که نماینده شما می‌تواند آن را در پیام‌های ارسالی به کاربران بگنجاند. پس‌از ۶۰ روز، «RCS ویژه کسب‌وکارها» فایل‌ها را از حافظه نهان برمی‌دارد.

هنگام مشخص کردن فایل‌ها با نشانی وب، بهترین روش این است که contentMessage.forceRefresh را روی false تنظیم کنید. تنظیم contentMessage.forceRefresh روی true باعث می‌شود «RCS ویژه کسب‌وکارها» مجبور شود محتوای جدید را از نشانی وب مشخص‌شده واکشی کند، حتی اگر محتوای نشانی وب در حافظه نهان ذخیره شده باشد، که این امر زمان تحویل پیام را برای کاربران افزایش می‌دهد.

نمونه نشانی وب فایل

کد زیر تصویری را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، AgentContentMessage را ببینید.

cURL

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

Node.js

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

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

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

   rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444");
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
این کد گزیده‌ای از عامل نمونه RBM است.

یا می‌توانید رسانه را قبل‌از ارسال در پیام با files.create بارگذاری کنید.

نمونه بارگذاری فایل

کد زیر یک فایل ویدیو و یک فایل ریزعکس را بارگذاری می‌کند، سپس هر دو فایل را در یک پیام ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، files.create و AgentContentMessage را ببینید.

cURL

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

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


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

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


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

انواع رسانه پشتیبانی‌شده

‹RCS ویژه «کسب‌وکارها»› از انواع رسانه زیر پشتیبانی می‌کند. برای تصاویر کوچک، فقط image/jpeg،‏ image/jpg،‏ image/gif، و image/png پشتیبانی می‌شود.

نوع رسانه نوع مدرک افزونه با کارت‌های غنی کار می‌کند
application/ogg صدای OGG ‎.ogx نه
application/pdf PDF pdf. بله (فقط برای «پیام‌نگار Google» در هند)
audio/aac صدای AAC ‎.aac نه
audio/mp3 صدای MP3 ‎.mp3 نه
audio/mpeg صدای MPEG ‎.mpeg نه
audio/mpg صدای MPG ‎.mp3 نه
audio/mp4 صدای MP4 .mp4 نه
audio/mp4-latm صوت MP4-latm .mp4 نه
audio/3gpp صدای 3GPP .3gp نه
image/jpeg JPEG ‎.jpeg،‏ ‎.jpg بله
image/gif GIF gif. بله
image/png PNG ‎.png بله
video/h263 ویدیو H263 ‎.h263 بله
video/m4v ویدیو M4V ‎.m4v بله
video/mp4 ویدیو MP4 .mp4 بله
video/mpeg4 ویدیو MPEG-4 ‎.mp4، .m4p بله
video/mpeg ویدیو MPEG ‎.mpeg بله
video/webm ویدیو WEBM ‎.webm بله

پیشنهادها

نماینده شما پیشنهادها (پاسخ‌های پیشنهادی و کنش‌های پیشنهادی) را در فهرست‌های تراشه پیشنهاد یا در کارت‌های غنی ارسال می‌کند.

پاسخ‌های پیشنهادی

پاسخ‌های پیشنهادی با ارائه پاسخ‌هایی که نماینده شما می‌داند چگونه به آن‌ها واکنش نشان دهد، کاربران را درطول مکالمه راهنمایی می‌کند.

وقتی کاربر روی پاسخ پیشنهادی تک‌ضرب می‌زند، نماینده شما رویدادی را دریافت می‌کند که حاوی نوشتار پاسخ و داده‌های پس‌فرست است. بارداده حداکثر ۲۰۴۸ نویسه دارد.

مثال

کد زیر نوشتاری را با دو پاسخ پیشنهادی ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، SuggestedReply را ببینید.

cURL

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

Node.js

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

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

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

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

# Send a simple message with suggestion chips to the device
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

// Send simple text message with suggestions to user
rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
   suggestions
);
این کد گزیده‌ای از عامل نمونه RBM است.

اقدام‌های پیشنهادی

کنش‌های پیشنهادی با بهره‌گیری از عملکرد داخلی دستگاه‌های کاربران، آن‌ها را در مکالمه‌ها راهنمایی می‌کند. نماینده شما می‌تواند به کاربران پیشنهاد دهد که شماره‌ای را شماره‌گیری کنند، مکانی را در نقشه باز کنند، مکانی را هم‌رسانی کنند، نشانی وبی را باز کنند، یا رویداد تقویمی ایجاد کنند.

برای هر کنش پیشنهادی، می‌توانید به‌صورت اختیاری یک نشانی وب بازگشتی (حداکثر ۲۰۴۸ نویسه) ارائه دهید. اگر دستگاه کاربر از کنش پیشنهادی پشتیبانی نکند، این نشانی وب در پنجره مرورگر جدیدی باز می‌شود.

وقتی کاربر روی کنش پیشنهادی ضربه می‌زند، نماینده شما رویدادی را دریافت می‌کند که حاوی داده‌های پس‌فرست کنش است.

برای گزینه‌های قالب‌بندی و مقدار، SuggestedAction را ببینید.

نمایش پیشنهاد

دو روش برای نمایش پیشنهادها وجود دارد:

  • Persistent: کنش‌ها یا پاسخ‌های پیشنهادی که در حبابک پیام نمایش داده می‌شوند و در سراسر مکالمه ثابت می‌مانند.
  • گذرا: پیشنهادهایی که خارج از حباب پیام نمایش داده می‌شوند و با ادامه مکالمه ناپدید می‌شوند.

قالب‌های پیام پشتیبانی‌شده

  • پیشنهادهای دائمی: با پیام‌های نوشتاری مستقل و کارت‌های غنی کار می‌کنند.
  • پیشنهادهای گذرا: با پیام‌های نوشتاری مستقل، پیام‌های رسانه‌ای، و کارت‌های غنی کار می‌کنند.

ترکیب کردن پیشنهادها

می‌توانید پیشنهادهای دائمی و گذرا را در یک پیام یا کارت غنی ترکیب کنید.

  • پیام‌های نوشتاری: پیشنهادها به‌طور پیش‌فرض موقتی هستند. برای اینکه آن‌ها را داخل حباب نگه دارید، باید آن‌ها را به‌عنوان پایدار پیکربندی کنید.
  • کارت‌های غنی: این کارت‌ها به‌طور پیش‌فرض تا چهار پیشنهاد ثابت را پشتیبانی می‌کنند. سپس می‌توانید پیشنهادهای گذرا را به‌عنوان «فهرست تراشه» در زیر کارت اضافه کنید.

حدود پیشنهاد

یک پیامک درمجموع حداکثر از ۱۱ پیشنهاد پشتیبانی می‌کند. هر پیشنهاد ثابتی که اضافه می‌کنید در محاسبه این حد کل لحاظ می‌شود. برای مثال، اگر ۴ پیشنهاد دائمی اضافه کنید، می‌توانید حداکثر ۷ پیشنهاد گذرا اضافه کنید.

نوع پیشنهاد محدودیت مکان نشان داده شدن
دائمی حداکثر تا ۴ درون حبابک پیام
گذرا حداکثر تا ۱۱ خارج از حبابک (به‌صورت تراشه)

حد نویسه

هر پیشنهاد حداکثر ۲۵ نویسه دارد.

شفافیت نشانی وب در کنش‌های پیشنهادی

برای جلب اعتماد کاربر، نشانی وب اصلی به‌عنوان خط دوم نوشتار در دکمه پیشنهاد برای کنش‌های پیشنهادی «باز کردن نشانی وب» نمایش داده می‌شود. این رفتار ثابت در پیام‌های نوشتاری مستقل، کارت‌های غنی، و گردونه‌ها اعمال می‌شود.

کارخواه‌های پشتیبانی‌شده برای پیشنهادهای دائمی

  • پشتیبانی‌شده: «پیام‌نگار Google» (نسخه 20260225.00 یا جدیدتر).
  • پشتیبانی نمی‌شود: نسخه‌های «پیام‌نگار Google» قدیمی‌تر از 20260225.00، iOS، و Samsung Messages.

پیشنهادها در اعلان‌های سیستم

وقتی کاربر پیامی دریافت می‌کند، «پیام‌نگار Google» اولین پیشنهاد واجدشرایط را مستقیماً در اعلان سیستم Android او نمایش می‌دهد. کاربران می‌توانند روی این پیشنهاد تک‌ضرب بزنند تا بدون نیاز به باز کردن برنامه، پاسخی ارسال کنند یا کنشی را راه‌اندازی کنند.

هنگام طراحی پیام‌هایتان، رفتار زیر را درنظر داشته باشید:

  • ترتیب مهم است: برای هر اعلان فقط یک پیشنهاد نشان داده می‌شود. برای به‌حداکثر رساندن تعامل، پاسخ یا کنش پیشنهادی با بالاترین اولویت را در ابتدای فهرست پیشنهادهایتان قرار دهید.
  • کنش‌های مستثنی‌شده: کنش هم‌رسانی مکان هرگز در اعلان‌های سیستم نشان داده نمی‌شود - کاربران برای هم‌رسانی مکانشان باید مکالمه را باز کنند.

شماره‌گیری

کنش «شماره‌گیری» کاربر را راهنمایی می‌کند تا شماره تلفن مشخص‌شده توسط نماینده شما را شماره‌گیری کند. شماره تلفن فقط می‌تواند شامل رقم (0-9)، علامت جمع (+)، ستاره (*)، و علامت عدد (#) باشد. قالب بین‌المللی E.164 (برای مثال، +14155555555) پشتیبانی می‌شود اما الزامی نیست. یعنی هم +14155555555 و هم 1011 ورودی‌های معتبری هستند.

مثال

کد زیر کنش شماره‌گیری را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، DialAction را ببینید.

cURL

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

Node.js

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

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

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

// Send a simple message with a dial suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
این کد گزیده‌ای از عامل نمونه RBM است.

مشاهده مکان

کنش «مشاهده مکان» مکانی را در برنامه نقشه پیش‌فرض کاربر نمایش می‌دهد. می‌توانید مکان را با طول و عرض جغرافیایی یا با پُرسمانی براساس مکان فعلی کاربر مشخص کنید. همچنین می‌توانید برچسب سفارشی برای سنجاق تنظیم کنید که در برنامه نقشه نمایش داده می‌شود.

مثال

کد زیر کنش مشاهده مکان را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، ViewLocationAction را ببینید.

cURL

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

Node.js

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

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

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

// Send a simple message with a view location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
این کد گزیده‌ای از عامل نمونه RBM است.

هم‌رسانی مکان

کنش «هم‌رسانی مکان» به کاربر اجازه می‌دهد مکانی را با نماینده شما هم‌رسانی کند. کاربر می‌تواند مکان فعلی‌اش یا مکانی را که به‌صورت دستی از برنامه Maps انتخاب کرده است هم‌رسانی کند.

مثال

کد زیر کنش هم‌رسانی مکان را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، ShareLocationAction را ببینید.

cURL

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

Node.js

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

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

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

// Send a simple message with a share location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
این کد گزیده‌ای از عامل نمونه RBM است.

باز کردن نشانی وب

کنش «باز کردن نشانی وب» به شما امکان می‌دهد کاربران را به صفحه وبی که نماینده‌تان مشخص کرده است هدایت کنید. به‌طور پیش‌فرض، صفحه وب در مرورگر کاربر باز می‌شود. همچنین می‌توانید صفحه وب را طوری تنظیم کنید که در نمای وب باز شود. برای جزئیات، باز کردن نشانی وب با webview را ببینید.

فقط در «پیام‌نگار Google»

نمایش نشانی وب اصلی: برای بهبود شفافیت در پیام‌رسانی «برنامه به فرد»، «پیام‌نگار Google» نشانی وب اصلی را در کنش‌های پیشنهادی «باز کردن نشانی وب» نمایش می‌دهد. این تغییر بر کنش‌های پیشنهادی در کارت‌های غنی استاندارد و گردونه‌های کارت غنی تأثیر می‌گذارد.

کارت غنی که پیشنهاد «مشاهده وب‌سایت» را با نشانی وب نمایش‌داده‌شده در زیر آن نشان می‌دهد.
نشانی وب اصلی قابل‌مشاهده

نمایش نماد برنامه برای پیوندهای وب: اگر کاربر برنامه پیش‌فرضی را برای صفحه وب پیکربندی کرده باشد، آن برنامه به‌جای مرورگر یا وب‌نما باز می‌شود و دکمه پیشنهاد نماد برنامه را نمایش می‌دهد. برای اینکه نماد برنامه در «پیام‌نگار Google» نشان داده شود، باید نشانی وب کامل و مستقیم را ارائه دهید. اگر از نشانی وب کوتاه استفاده کنید، نماد پیش‌فرض «باز کردن نشانی وب» به‌جای آن نمایش داده می‌شود.

نماد برنامه در دکمه پیشنهاد.
نماد برنامه در دکمه پیشنهاد
مثال

کد زیر کنش باز کردن نشانی وب را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، OpenUrlAction را ببینید.

cURL

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

Node.js

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

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

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

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
این کد گزیده‌ای از عامل نمونه RBM است.

باز کردن نشانی وب با webview

کنش «باز کردن نشانی وب با نمای وب» صفحه وب مشخص‌شده را در برنامه پیام‌رسانی با موتور پردازش مرورگر پیش‌فرض شما بار می‌کند. این به کاربر اجازه می‌دهد بدون ترک مکالمه «RCS ویژه کسب‌وکارها» با صفحه وب تعامل داشته باشد. اگر دستگاه کاربر از webviews پشتیبانی نکند، صفحه وب در مرورگر کاربر باز می‌شود. برای فعال کردن نماهای وب، OpenURLApplication را ببینید.

Webview سه حالت نمایش دارد. برای گزینه‌های قالب‌بندی و مقدار، WebviewViewMode را ببینید.

  • کامل: صفحه وب کل صفحه‌نمایش را اشغال می‌کند
  • نیم‌صفحه: صفحه وب نیمی از صفحه‌نمایش را اشغال می‌کند
  • بلند: صفحه وب سه چهارم صفحه‌نمایش را اشغال می‌کند
مثال

کد زیر یک کنش «باز کردن نشانی وب با نمای وب» را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، OpenURLAction را ببینید.

cURL

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

جاوا

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

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

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

ایجاد کردن رویداد تقویم

کنش «ایجاد رویداد تقویم» برنامه تقویم کاربر را باز می‌کند و رویداد جدیدی با اطلاعات مشخص‌شده ایجاد می‌کند.

عنوان رویداد تقویم الزامی است. حداکثر ۱۰۰ نویسه دارد. شرح رویداد تقویم اختیاری است و حداکثر ۵۰۰ نویسه دارد.

مثال

کد زیر کنش ایجاد رویداد تقویم را ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، CreateCalendarEventAction را ببینید.

cURL

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

Node.js

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

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

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

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

]

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
این کد گزیده‌ای از عامل نمونه RBM است.

فهرست تراشه پیشنهاد

نماینده شما فهرست‌های تراشه پیشنهادی را با پیام‌هایی ارسال می‌کند تا اقدامات بعدی کاربران را راهنمایی کند. فهرست تراشه‌ها فقط زمانی نمایش داده می‌شود که پیام مربوطه در پایین مکالمه باشد. هر پیام بعدی در مکالمه (ازسوی کاربر یا نماینده شما) فهرست تراشه را بازنویسی می‌کند.

تراشه‌های موجود در فهرست پاسخ‌های پیشنهادی و کنش‌های پیشنهادی هستند.

فهرست‌های تراشه‌ای حداکثر ۱۱ تراشه پیشنهادی دارند و هر برچسب تراشه می‌تواند حداکثر ۲۵ نویسه داشته باشد.

برای گزینه‌های قالب‌بندی و مقدار، AgentContentMessage را ببینید.

کارت‌های پیشرفته

کارت‌های غنی رسانه، نوشتار، و پیشنهادهای تعاملی را در یک پیام ترکیب می‌کنند. این کارت‌ها برای ارائه اطلاعات مرتبط (برای مثال، محصولی با تصویر، نام، و قیمت آن) و راهنمایی کاربران با گام بعدی واضح مثل پیشنهاد «مشاهده جزئیات» ایده‌آل هستند.

کارت غنی می‌تواند شامل موارد زیر باشد:

هرکدام از این فیلدها اختیاری است، اما حداقل یکی از فیلدهای ۱ تا ۳ باید در کارت غنی گنجانده شود.

چند کارت را می‌توان باهم در یک گردونه با پیمایش افقی ارسال کرد.

توجه داشته باشید که کل بار مفید برای کارت غنی ۲۵۰ کیلوبایت است.

برای جزئیات فنی کامل، به اسناد کارت‌های غنی مراجعه کنید.

ارتفاع کارت

کارت‌های غنی به‌صورت عمودی ازهم باز می‌شوند تا محتوایشان را در خود جای دهند. حداقل ارتفاع آن‌ها ۱۱۲ دی‌پی و حداکثر ارتفاع آن‌ها ۳۴۴ دی‌پی است. اگر محتوای کارت به‌اندازه کافی بزرگ نباشد که حداقل ارتفاع کارت را پر کند، کارت گسترش می‌یابد و ارتفاع اضافی را با فضای خالی پر می‌کند.

رسانه در کارت‌های غنی باید یکی از سه ارتفاع زیر را داشته باشد:

  • کوتاه: ۱۱۲ DP
  • متوسط: ۱۶۸ DP
  • بلند: ۲۶۴ DP

اگر رسانه با ابعاد داخل کارت با توجه به ارتفاع انتخاب‌شده مطابقت نداشته باشد، پیش‌نمایش رسانه با بزرگ‌نمایی و برش رسانه انتخاب می‌شود.

مثال

کد زیر کارت غنی با تصویر و پاسخ‌های پیشنهادی ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، RichCard را ببینید.

cURL

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

Node.js

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

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

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

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

// Send rich card to device
rbmApiHelper.sendRichCard(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

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

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

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

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

   rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444");
} catch(Exception e) {
   e.printStackTrace();
}
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

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

# Append rich card and send to the user
cluster = messages.MessageCluster().append_message(rich_card)
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

// Send rich card to user
rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
این کد گزیده‌ای از عامل نمونه RBM است.

گردونه‌های کارت غنی تعاملی

گردونه‌ها چندین کارت غنی را به‌هم متصل می‌کنند و به کاربران اجازه می‌دهند موارد را مقایسه کنند و به هرکدام به‌طور جداگانه واکنش نشان دهند.

گردونه‌ها می‌توانند حداقل دو و حداکثر ده کارت غنی داشته باشند. کارت‌های غنی در گردونه‌ها باید با الزامات کلی کارت غنی برای محتوا و ارتفاع مطابقت داشته باشند، همان‌طور که در سند کارت‌های غنی شرح داده شده است. برای اطلاعات بیشتر درباره چیدمان و مشخصات گردونه، به اسناد گردونه مراجعه کنید.

مثال

کد زیر گردونه کارت غنی ارسال می‌کند. برای گزینه‌های قالب‌بندی و مقدار، RichCard را ببینید.

cURL

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

Node.js

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

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

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

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

// Send the device the carousel card defined above
rbmApiHelper.sendCarouselCard(params, function(response) {
   console.log(response);
});
این کد گزیده‌ای از عامل نمونه RBM است.

جاوا

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

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

            List cardContents = new ArrayList();

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

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

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

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

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

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

            // Send the carousel to the user
            rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444");
        } catch(Exception e) {
            e.printStackTrace();
        }
این کد گزیده‌ای از عامل نمونه RBM است.

Python

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

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

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

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

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

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

# Send the device the carousel card defined above
carousel_card = messages.CarouselCard('MEDIUM', card_contents)
cluster = messages.MessageCluster().append_message(carousel_card)
cluster.send_to_msisdn('+12223334444')
این کد گزیده‌ای از عامل نمونه RBM است.

C#‎

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

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

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

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

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

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

// Send the carousel to the user
rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);
این کد گزیده‌ای از عامل نمونه RBM است.