שליחת הודעות

נציגי RCS for Business מתקשרים עם המשתמשים באמצעות שליחה וקבלה של הודעות. כדי לשלוח הודעות למשתמשים, הנציג שולח בקשות להודעות ל-RCS Business Messaging API. בקשה אחת יכולה לכלול טקסט, צ'אטים אינטראקטיביים, קובצי מדיה ו-PDF, הצעות לתשובות והצעות לפעולות.

במצבים מסוימים, פלטפורמת RCS for Business מחזירה שגיאות כדי לעזור לכם לנהל את מסירת ההודעות:

  • אם אתם שולחים הודעה למשתמש שהמכשיר שלו לא תומך ב-RCS או ש-RCS לא מופעל בו, פלטפורמת RCS for Business מחזירה שגיאת 404 NOT_FOUND. במקרה כזה, אתם יכולים לנסות להגיע למשתמש באמצעות שיטות הגיבוי שהוגדרו בתשתית שלכם.
  • אם תשלחו הודעה למשתמש RCS ברשת שבה הנציג שלכם עדיין לא הושק, או ברשת שלא הפעילה תנועת RCS, פלטפורמת RCS for Business תחזיר שגיאה מסוג 404 NOT_FOUND.
  • אם תשלחו הודעה עם תכונות שהמכשיר של המשתמש לא תומך בהן, פלטפורמת RCS for Business תחזיר את השגיאה 400 INVALID_ARGUMENT ולא תעביר את ההודעה.

כחלק מאסטרטגיית ההודעות בכמה ערוצים, מומלץ לבטל הודעות שלא נמסרו אחרי פרק זמן סביר ולשלוח אותן דרך ערוץ אחר. כדי לבטל הודעות באופן אוטומטי בזמן מוגדר מראש, מגדירים תפוגת הודעה.

הנמען לא מחובר

פלטפורמת RCS for Business עדיין מקבלת הודעה למסירה אם הנמען במצב אופליין. תקבלו תשובה 200 OK, והפלטפורמה של RCS for Business תשמור את ההודעה ותנסה לשלוח אותה שוב במשך 30 יום. אין צורך לבקש מ-RCS for Business לשלוח את ההודעה שוב.

הודעות שלא נמסרו נמחקות מ-RCS for Business אחרי 30 יום.

בהתאם לתרחיש לדוגמה של הנציג, יכול להיות שתרצו לבטל הודעה שלא נמסרה לפני תום הזמן הקצוב לתפוגה של 30 יום. ביטול השליחה יכול למנוע ממשתמשים במצב אופליין לקבל הודעה לא עדכנית כשהם חוזרים למצב אונליין. יש כמה דרכים לבטל הודעה:

הגדרת תאריך תפוגה להודעה

האם ההודעה של הסוכן דחופה? לדוגמה, סיסמאות חד-פעמיות תקפות רק לפרק זמן קצר. מבצעים לזמן מוגבל מסתיימים. ותזכורות לפגישות לא רלוונטיות אחרי שהפגישה כבר התקיימה. כדי שההודעות יהיו עדכניות ורלוונטיות, כדאי להגדיר תאריך תפוגה להודעה. כך אפשר למנוע ממשתמשים במצב אופליין לקבל תוכן מיושן כשהם חוזרים למצב אונליין. תפוגת התוקף היא גם סימן טוב להפעלת אסטרטגיית ההודעות החלופיות, כדי שהמשתמשים יקבלו את המידע שהם צריכים בזמן.

כדי להגדיר תפוגה להודעה, מציינים את אחד מהשדות הבאים בהודעת הנציג:

  • expireTime: השעה המדויקת לפי שעון UTC שבה פג התוקף של ההודעה.
  • ‫ttl (זמן חיים): משך הזמן עד שההודעה תפוג.

אפשרויות העיצוב והערכים מפורטות במאמר AgentMessage.

הערך המקסימלי של ttl ו-expireTime הוא 15 ימים אחרי שליחת ההודעה.

הערך המינימלי של ttl ו-expireTime הוא שש שניות אחרי שליחת ההודעה.

המלצות להגדרת תפוגת הודעות

  • להודעות אימות (OTP): מגדירים את ttl לערך של 15 שניות או יותר אחרי שליחת ההודעה, כדי לצמצם משמעותית את הסיכוי למרוץ תהליכים של מסירה וביטול.

  • להודעות שיווקיות וטרנזקציונליות: הגדירו תפוגה ארוכה יותר (לפחות 60 שניות, או דקות עד שעות, בהתאם לתרחיש לדוגמה) כי המכשירים צריכים זמן נוסף כדי לסרוק הודעות ולהוריד או לעבד תוכן מדיה עשירה, וייתכן שהמשתמשים יחוו ניתוקים קצרים (לדוגמה, במעלית או במנהרה).

אורך חיים (TTL) של הודעה

כשמגדירים TTL להודעה ב-RCS for Business, מציינים כמה זמן ההודעה נחשבת לתקפה וניתנת למסירה. אם ההודעה לא נמסרת למכשיר של המשתמש במהלך תקופת ה-TTL, פלטפורמת RCS for Business מנסה לבטל אותה באופן אוטומטי.

כשאתם מבטלים הודעה, אתם מבקשים מפלטפורמת RCS for Business להפסיק לנסות לשלוח את ההודעה הספציפית הזו. עם זאת, הפעולה הזו משפיעה רק על ניסיונות מסירה עתידיים. אם המכשיר של המשתמש כבר אחזר את ההודעה, ההודעה מעובדת ופלטפורמת RCS for Business לא יכולה לבטל את ההודעה במכשיר של המשתמש.

מה קורה עם ההתראות:

  • ההודעה נמסרה במסגרת ה-TTL: אם המכשיר של המשתמש מתחבר לאינטרנט ומקבל את ההודעה לפני שפג תוקף ה-TTL, אתם מקבלים התראה מסוג DELIVERED. לא תישלח הודעה על ביטול, כי ההודעה נמסרה בהצלחה. זה התרחיש הכי נפוץ וצפוי.

  • ההודעה לא נמסרה לפני שפג תוקף ה-TTL: אם תוקף ה-TTL פג לפני שההודעה הגיעה למכשיר של המשתמש (לדוגמה, המכשיר במצב אופליין), פלטפורמת RCS for Business מנסה לבטל את ההודעה. תקבלו התראה מ-TTL_EXPIRATION_REVOKED על כך שההודעה הוסרה בהצלחה מתור המסירה. במקרה כזה, המשתמש לא יקבל את ההודעה.

המלצות לטיפול במקרי קצה

המערכת שלנו מעבדת את מסירת ההודעות ב-RCS for Business ואת פקיעת התוקף של ה-TTL במקביל. לכן, במקרים נדירים מאוד, יכול להיות שתראו מקרים חריגים שבהם ההתראות נשלחות בזמן לא צפוי. לדוגמה, יכול להיות שתקבלו גם התראה על מסירה וגם התראה על TTL, או שלא תקבלו אף אחת מהן.

אלה ההמלצות שלנו לטיפול בהתראות על הודעות ב-RCS for Business:

  • התראה מסוג DELIVERED: אם קיבלתם התראה מסוג DELIVERED על הודעה, זה אומר שההודעה הגיעה למשתמש. אתם יכולים להתעלם מכל התראות ה-TTL הבאות לגבי ההודעה הספציפית הזו.

  • התראה על TTL_EXPIRATION_REVOKED: אם קיבלתם התראה על TTL עם הסטטוס TTL_EXPIRATION_REVOKED, זה אומר שמערכת RCS for Business הפסיקה לנסות לשלוח את ההודעה הספציפית הזו. צריך להתייחס להודעה הזו כאל הודעה שלא נמסרה, ולהמשיך עם אסטרטגיית הגיבוי במקרה הצורך.

  • התראת TTL עם כל סטטוס אחר: אם קיבלתם התראת TTL עם כל סטטוס אחר, זה מצביע על ניסיון ביטול לא חד-משמעי.

    • בהודעות קריטיות, כמו סיסמאות חד-פעמיות (OTP), צריך להפעיל את שיטת הגיבוי.
    • בהודעות לא קריטיות, מחליטים אם להפעיל את החלופה או לא.
  • אין התראות: במקרים נדירים, יכול להיות שהמערכת לא תשלח התראת TTL ושהלקוח לא ייצור התראת מסירה. זה מקרה נדיר מאוד.

הגדרת סוג התנועה של ההודעה

ב-RBM API יש שדה messageTrafficType לסיווג הודעות. תרחישי השימוש של הנציג עדיין מגדירים את ההתנהגות של הנציג ואת הכללים העסקיים שחלים עליו, אבל messageTrafficType מאפשר לסווג את תוכן ההודעות בצורה מפורטת יותר. בסופו של דבר, זה מאפשר לנציג אחד לטפל בכמה תרחישים לדוגמה. כרגע אין השפעה על תרחישי שימוש קיימים של נציגים או על כללים עסקיים.

השדה הזה הוא אופציונלי, אבל מומלץ להגדיר אותו עכשיו כדי שלא תתקבל שגיאה כשהשדה יהפוך לשדה חובה.

כדי להגדיר את סוג התנועה של ההודעות, מקצים את הערך המתאים של messageTrafficType לכל הודעה על סמך התוכן שלה. בטבלה הבאה מפורטים סוגי התנועה הנתמכים ותרחישי השימוש הצפויים של הנציגים. המיפוי הזה הוא המלצה לשימוש צפוי, ולא הגבלה שנאכפת על ידי ה-API בשלב הזה.

סוג תנועה תוכן ההודעה תרחיש לדוגמה לשימוש בנציג מומלץ
AUTHENTICATION הודעות אימות. OTP
TRANSACTION הודעות על שירותים או מוצרים קיימים של משתמש. לדוגמה: אישורים, קבלות על תשלום או פרטי הזמנה. עסקאות או רב-שימושי
PROMOTION הודעות שיווקיות כמו מבצעים, הנחות, הודעות או תוכן שיווקי אחר. לקידום מכירות או לשימוש חוזר
SERVICEREQUEST הודעות על שירותים שהמשתמש ביקש באופן מפורש. OTP, עסקאות, קידום מכירות או שימוש מרובה
ACKNOWLEDGEMENT הודעות שמשמשות לאישור פעולה של משתמש – במיוחד בקשה לביטול הרשמה. זהו אישור לכך שהבקשה של המשתמש התקבלה ונמצאת בטיפול. OTP, עסקאות, קידום מכירות או שימוש מרובה

אם לא מוגדר סוג תנועה, המערכת מקצה את סוג ברירת המחדל לתרחיש לדוגמה של הנציג.

תרחיש לדוגמה לשימוש בנציג סוג התנועה שמוגדר כברירת מחדל
OTP AUTHENTICATION
עסקאות TRANSACTION
קידום מכירות PROMOTION
שימוש חוזר MESSAGE_TRAFFIC_TYPE_UNSPECIFIED

לסוכנים רב-תכליתיים אין סוג תנועה שמוגדר כברירת מחדל. צריך להגדיר את סוג התנועה באופן מפורש לכל הודעה על סמך התוכן שלה. אם לא מחליפים את הערך של MESSAGE_TRAFFIC_TYPE_UNSPECIFIED, ההודעה עדיין מתקבלת ונשלחת בלי סיווג ספציפי של סוג התנועה.

מגבלות הגודל של ההודעות

הגודל המקסימלי של כל ה-AgentMessage כמחרוזת הוא 250KB. לחלק של הטקסט בהודעה יש מגבלה משלו של 3,072 תווים.

כדי למנוע צריכת נתונים בלתי צפויה למשתמשים, הגודל המקסימלי של קובץ שאפשר לשלוח באמצעות RCS for Business הוא 100MiB, והגודל הכולל של כל קובצי המדיה וה-PDF המצורפים להודעה אחת ב-RCS for Business לא יכול לחרוג מ-100MiB. ‫(1MiB‏ = 1,048,576 בייטים). מידע נוסף זמין במאמר בנושא קובצי מדיה ו-PDF.

טקסט

ההודעות הכי פשוטות מורכבות מטקסט. הודעות SMS מתאימות במיוחד להעברת מידע שלא מצריך רכיבים חזותיים, אינטראקציה מורכבת או תגובה.

דוגמה

הקוד הבא שולח הודעת טקסט פשוט. אפשרויות הפורמט והערכים מפורטות במאמר 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 לדוגמה.

Java

import com.google.rbm.RbmApiHelper;
…

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

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444"
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

# Send text message to the device
messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

using RCSBusinessMessaging;
…

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

תוכן של הודעה בסיסית – המרה של SMS

ספקי הסלולר הציגו מודלים של חיוב כדי לתמוך במעבר של הודעות SMS ל-RCS for Business. הודעה ב-RCS for Business שמכילה עד 160 תווים בקידוד UTF-8 נקראת "הודעה בסיסית".

כשיוצרים בקשה לשליחת הודעה בסיסית, חשוב לזכור שכל תו נספר כבייט אחד (UTF-8). אם שולחים הודעה שמכילה תווים מיוחדים כמו אמוג'י או קבוצת תווים של כמה בייטים, כל תו נספר בתור 2-4 תווים בקידוד UTF-8 או יותר.

כדי לבדוק את אורך הטקסט, מזינים אותו בתיבה:

לקוחות RCS יכולים להטמיע תצוגות מקדימות של קישורים. אם הודעת טקסט בלבד ב-RCS for Business כוללת כתובת URL של אתר עם תגי openGraph, הלקוח יכול ליצור תצוגה מקדימה (תמונה, כותרת וכו') כדי לספק חוויה עשירה יותר. לדוגמה, ראו הודעה בסיסית עם תצוגה מקדימה של כתובת URL.

חשוב לזכור שלקוח ה-RCS יכול לאפשר למשתמש להשבית את התצוגות המקדימות של הקישורים.

סיסמאות חד-פעמיות לאימות משתמשים

אתם יכולים להשתמש ב-RCS for Business כדי לשלוח סיסמאות חד-פעמיות (OTP) לאימות משתמשים אוטומטי באמצעות SMS Retriever API. אין API ייעודי לקריאת סיסמאות חד-פעמיות שמגיעות דרך RCS for Business.

איך זה עובד ב-Android

באפליקציות ל-Android שנרשמו ל-SMS Retriever API, ה-API מאזין להודעות RCS for Business בפורמט תקין. ההודעה הזו צריכה להכיל גם את ה-OTP וגם גיבוב (hash) ייחודי שמזהה את האפליקציה.

כשמתקבלת הודעת RCS for Business בפורמט הנכון, ה-SMS Retriever API מעבד אותה בדיוק כמו שהוא מעבד OTP ב-SMS. אחרי שהגיבוב מותאם לאפליקציה, ה-OTP מחולץ ומועבר לאפליקציה לצורך אימות משתמש אוטומטי.

  • דוגמה להודעת SMS ב-RCS for Business לאימות משתמש: Your code is <OTP><app hash>.
  • לדוגמה: Your code is 123456 M8tue43FGT.

מידע נוסף על SMS Retriever וממשקי API קשורים זמין במסמכי התיעוד של SMS Retriever. לפרטים על אימות משתמשים אוטומטי באפליקציות שרשומות ב-SMS Retriever API, עיינו בתרשים הזרימה הזה.

איך זה עובד ב-iOS

ב-iOS, המערכת המובנית לטיפול ב-OTP מזהה באופן אוטומטי את ה-OTP של RCS for Business ומציעה אותו למילוי אוטומטי, בדיוק כמו ה-OTP של SMS. לא נדרש שילוב API ספציפי כדי שהאפליקציה ל-iOS תקרא את ה-OTP.

קובצי מדיה ו-PDF

כששולחים הודעה עם תמונה, סרטון, קובץ אודיו או קובץ PDF, הנציג צריך לספק כתובת URL ציבורית לתוכן או להעלות את הקובץ ישירות.

הגודל המקסימלי של קובץ שאפשר לשלוח הוא 100MiB, והגודל הכולל של כל קובצי המדיה וקובצי ה-PDF המצורפים להודעה אחת לא יכול לחרוג מ-100MiB.

דחיסה והמרת קידוד של מדיה

פלטפורמת RCS for Business ממירה ודוחסת באופן אוטומטי קובצי מדיה (כמו תמונות וסרטונים) לפני שהיא שולחת אותם, כדי לוודא שהם נטענים במהירות ופועלים כמו שצריך ברשתות ובמכשירים שונים.

הדחיסה מבוססת על איכות המדיה שהועלתה ולא רק על מגבלות גודל הקובץ. זה אומר שאפשר לדחוס קובץ גם אם הגודל שלו קטן בהרבה מהמגבלה המקסימלית של 100MiB. התקנים של המרת קידוד משתנים כל הזמן, ולכן אין מגבלה קבועה של גודל קובץ שקובעת מתי המערכת תדלג על המרת הקידוד. כדאי לנסות פורמטים, ממדים ושיעורי דחיסה שונים של מדיה כדי למצוא את האיזון האופטימלי למטענים הייעודיים (payloads).

מפרט לתמונות ממוזערות

בקובצי מדיה, אפשר גם לציין תמונה ממוזערת שמאפשרת למשתמשים לראות תצוגה מקדימה של התוכן לפני שהם לוחצים עליו. בקובצי אודיו, הווידג'ט של האודיו שמוגדר כברירת מחדל משמש כפלייסהולדר.

  • גודל הקובץ המקסימלי של תמונה ממוזערת הוא 100KB. כדי לספק חוויית משתמש אופטימלית, מומלץ שהגודל יהיה 50KB או פחות.
  • יחס הגובה-רוחב של התמונה הממוזערת צריך להיות זהה ליחס של הקובץ המקורי.

שמירה במטמון וניהול כתובות URL

פלטפורמת RCS for Business שומרת קבצים במטמון למשך 60 ימים, וה-API מחזיר מזהה קובץ שהנציג יכול לכלול בהודעות למשתמשים. אחרי 60 יום, הקבצים נמחקים מהמטמון של RCS for Business.

כשמציינים קבצים לפי כתובת URL, מומלץ להגדיר את contentMessage.forceRefresh לערך false. הגדרה של contentMessage.forceRefresh לערך true מאלצת את RCS for Business לאחזר תוכן חדש מכתובת ה-URL שצוינה, גם אם התוכן של כתובת ה-URL נשמר במטמון, מה שמאריך את זמני שליחת ההודעות למשתמשים.

דוגמה לכתובת URL של קובץ

הקוד הבא שולח תמונה. אפשרויות העיצוב והערכים מפורטות במאמר AgentContentMessage.

cURL

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

Node.js

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

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

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Java

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

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

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

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

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

   rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444");
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
הקוד הזה הוא קטע מנציג RBM לדוגמה.

אפשר גם להעלות מדיה לפני ששולחים אותה בהודעה באמצעות files.create.

דוגמה להעלאת קובץ

הקוד הבא מעלה קובץ וידאו וקובץ של תמונה ממוזערת, ואז שולח את שני הקבצים בהודעה. אפשרויות העיצוב והערכים מפורטות במאמרים files.create ו-AgentContentMessage.

cURL

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

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


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

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


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

סוגי המדיה הנתמכים

אלה סוגי המדיה שנתמכים ב-RCS for Business. לתמונות ממוזערות, יש תמיכה רק ב-image/jpeg,‏ image/jpg,‏ image/gif ו-image/png.

סוג מדיה סוג המסמך Extension תמיכה בצ'אטים אינטראקטיביים
application/ogg אודיו בפורמט OGG ‎.ogx לא
application/pdf PDF pdf. כן (רק ב-Google Messages בהודו)
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 כן

הצעות

הנציג שולח הצעות (הצעות לתשובות והצעות לפעולות) ברשימות של הצעות קשורות או בצ'אטים אינטראקטיביים.

הצעות לתשובות

הצעות לתשובות עוזרות למשתמשים להתקדם בשיחה, כי הן מספקות תשובות שהנציג יודע איך להגיב להן.

כשהמשתמש מקיש על הצעה לתשובה, הנציג מקבל אירוע שמכיל את הטקסט של התשובה ואת נתוני ה-postback. המטען הייעודי (payload) יכול להכיל עד 2,048 תווים.

דוגמה

הקוד הבא שולח טקסט עם שתי הצעות לתשובות. אפשרויות העיצוב והערכים מפורטות במאמר SuggestedReply.

cURL

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

Node.js

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

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

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

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Java

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

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

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

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

   // Send simple text message to user
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

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

# Send a simple message with suggestion chips to the device
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

// Send simple text message with suggestions to user
rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
   suggestions
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

הצעות לפעולות

הצעות לפעולות עוזרות למשתמשים להתקדם בשיחות באמצעות הפונקציונליות המובנית של המכשירים שלהם. הנציג יכול להציע למשתמשים לחייג למספר, לפתוח מיקום במפה, לשתף מיקום, לפתוח כתובת URL או ליצור אירוע ביומן.

לכל הצעה לפעולה, אתם יכולים לספק כתובת URL חלופית (עד 2,048 תווים). כתובת ה-URL הזו נפתחת בחלון דפדפן חדש אם המכשיר של המשתמש לא תומך בהצעה לפעולה.

כשמשתמש לוחץ על הצעה לפעולה, הנציג מקבל אירוע שמכיל את נתוני הדיווח החוזר (postback) של הפעולה.

אפשרויות העיצוב והערכים מפורטות במאמר SuggestedAction.

הצגת הצעות

יש שתי דרכים להציג הצעות:

  • Persistent: הצעות לפעולות או לתשובות שמוצגות בתוך בועת ההודעה ונשארות קבועות לאורך כל השיחה.
  • זמניות: הצעות שמוצגות מחוץ לבועת ההודעה ונעלמות כשהשיחה נמשכת.

פורמטים נתמכים של הודעות

  • הצעות קבועות: פועלות עם הודעות טקסט עצמאיות וצ'אטים אינטראקטיביים.
  • הצעות זמניות: פועלות עם הודעות טקסט, הודעות מדיה וצ'אטים אינטראקטיביים עצמאיים.

שילוב הצעות

אפשר לשלב הצעות קבועות וזמניות באותה הודעה או באותו צ'אט אינטראקטיבי.

  • הודעות SMS: ההצעות הן זמניות כברירת מחדל. כדי שהם יישארו בתוך הבועה, צריך להגדיר אותם כקבועים.
  • צ'אטים אינטראקטיביים: תומכים בעד ארבע הצעות קבועות כברירת מחדל. אחר כך אפשר להוסיף הצעות זמניות בתור "רשימת צ'יפים" מתחת לכרטיס.

האילוצים על ההצעה

הודעת SMS אחת יכולה להכיל עד 11 הצעות בסך הכול. כל הצעה קבועה שתוסיפו נכללת במגבלה הכוללת הזו. לדוגמה, אם אתם כוללים 4 הצעות קבועות, אתם יכולים להוסיף עד 7 הצעות זמניות.

סוג ההצעה מגבלה איפה הם מופיעים
קבוע עד 4 בתוך בועת ההודעה
ארעי עד 11 מחוץ לבועה (כצ'יפים)

מגבלת תווים

כל הצעה יכולה לכלול עד 25 תווים.

שקיפות ה-URL בהצעות לפעולות

כדי לבנות אמון בקרב המשתמשים, כתובת ה-URL הבסיסית מוצגת כשורה שנייה של טקסט בתוך לחצן ההצעה לפעולות מסוג "פתיחת כתובת URL". ההתנהגות העקבית הזו חלה על הודעות טקסט עצמאיות, על צ'אטים אינטראקטיביים ועל קרוסלות.

לקוחות נתמכים להצעות קבועות

  • אפליקציות נתמכות: Google Messages (גרסה 20260225.00 ואילך).
  • לא נתמך: גרסאות של Google Messages שקודמות ל-20260225.00, ‏iOS ו-Samsung Messages.

הצעות בהתראות המערכת

כשמשתמש מקבל הודעה, ההצעה הראשונה שרלוונטית מוצגת ב-Google Messages ישירות בהתראה של מערכת 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 לדוגמה.

Java

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

הצגת מיקום

הפעולה "הצגת מיקום" מציגה מיקום באפליקציית המפות שמוגדרת כברירת מחדל אצל המשתמש. אפשר לציין את המיקום לפי קו רוחב וקו אורך או באמצעות שאילתה שמבוססת על המיקום הנוכחי של המשתמש. אפשר גם להגדיר תווית בהתאמה אישית לסיכה שמוצגת באפליקציית המפות.

דוגמה

הקוד הבא שולח פעולה של צפייה במיקום. אפשרויות הפורמט והערכים מפורטות במאמר ViewLocationAction.

cURL

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

Node.js

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

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

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

// Send a simple message with a view location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Java

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

שיתוף מיקום

הפעולה "שיתוף מיקום" מאפשרת למשתמש לשתף מיקום עם הנציג שלכם. המשתמשים יכולים לשתף את המיקום הנוכחי שלהם או מיקום שהם בוחרים באופן ידני באפליקציית מפות Google.

דוגמה

הקוד הבא שולח פעולה של שיתוף מיקום. אפשרויות הפורמט והערכים מפורטות במאמר ShareLocationAction.

cURL

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

Node.js

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

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

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

// Send a simple message with a share location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Java

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

פתיחת כתובת URL

הפעולה "פתיחת כתובת URL" מאפשרת לכם להפנות משתמשים לדף אינטרנט שהסוכן מציין. כברירת מחדל, דף האינטרנט נפתח בדפדפן של המשתמש. אפשר גם להגדיר שדף האינטרנט ייפתח ב-WebView. פרטים נוספים זמינים במאמר פתיחת כתובת URL באמצעות WebView.

רק ב-Google Messages

הצגת כתובת ה-URL הבסיסית: כדי לשפר את השקיפות בהודעות A2P, אפליקציית Google Messages מציגה את כתובת ה-URL הבסיסית בהצעות לפעולות מסוג "פתיחת כתובת URL". השינוי הזה משפיע על הצעות לפעולות בצ'אטים אינטראקטיביים רגילים ובקרוסלות של צ'אטים אינטראקטיביים.

צ'אט אינטראקטיבי עם ההצעה &quot;לצפייה באתר&quot; וכתובת ה-URL שמוצגת מתחתיה.
כתובת ה-URL הבסיסית גלויה

הצגת סמל האפליקציה בקישורים לדפי אינטרנט: אם המשתמש הגדיר אפליקציית ברירת מחדל לדף האינטרנט, האפליקציה הזו תיפתח במקום הדפדפן או ה-WebView, וסמל האפליקציה יוצג בלחצן ההצעה. כדי שסמל האפליקציה יופיע ב-Google Messages, צריך לספק את כתובת ה-URL המלאה והישירה. אם משתמשים בכתובת URL מקוצרת, מוצג במקומו סמל ברירת המחדל לפתיחת כתובת URL.

סמל האפליקציה בכפתור הצעה.
סמל האפליקציה בלחצן הצעה
דוגמה

הקוד הבא שולח פעולה של פתיחת כתובת URL. אפשרויות העיצוב והערכים מפורטות במאמר OpenUrlAction.

cURL

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

Node.js

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

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

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

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Java

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

פתיחת כתובת URL באמצעות WebView

הפעולה "פתיחת כתובת URL באמצעות WebView" טוענת את דף האינטרנט שצוין בתוך אפליקציית ההודעות באמצעות מנוע הרינדור של דפדפן ברירת המחדל. כך המשתמש יכול לבצע פעולות בדף האינטרנט בלי לצאת מהשיחה ב-RCS for Business. אם המכשיר של המשתמש לא תומך בתצוגות WebView, דף האינטרנט ייפתח בדפדפן של המשתמש. כדי להפעיל תצוגות WebView, עיינו במאמר OpenURLApplication.

יש שלושה מצבי תצוגה של Webview. אפשרויות העיצוב והערכים מפורטות במאמר WebviewViewMode.

  • מלא: דף האינטרנט תופס את כל המסך
  • חצי: דף האינטרנט תופס חצי מהמסך
  • גבוה: דף האינטרנט תופס שלושה רבעים מהמסך
דוגמה

הקוד הבא שולח פעולה של פתיחת כתובת URL עם WebView. אפשרויות העיצוב והערכים מפורטות במאמר OpenURLAction.

cURL

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

Java

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

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

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

יצירת אירוע ביומן

הפעולה "יצירת אירוע ביומן" פותחת את אפליקציית היומן של המשתמש ומתחילה ליצור אירוע חדש עם המידע שצוין.

חובה לתת שם לאירוע ביומן. האורך המקסימלי הוא 100 תווים. התיאור של האירוע ביומן הוא אופציונלי ויכול להכיל עד 500 תווים.

דוגמה

הקוד הבא שולח פעולה ליצירת אירוע ביומן. אפשרויות העיצוב והערכים מפורטות במאמר CreateCalendarEventAction.

cURL

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

Node.js

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

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

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

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Java

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

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

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

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

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

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

   suggestions.add(suggestion);

   // Send simple text message with the suggestion action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

]

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

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

# Send a simple message with suggested action to the device
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
    suggestions
);
הקוד הזה הוא קטע מנציג RBM לדוגמה.

רשימת הצעות קשורות

הסוכן שלכם שולח רשימות של הצעות קשורות עם הודעות כדי להנחות את המשתמשים לגבי הפעולות הבאות. רשימת הצ'יפים מוצגת רק כשההודעה המשויכת נמצאת בתחתית השיחה. כל הודעה נוספת בשיחה (ממשתמש או מהנציג) מחליפה את רשימת הצ'יפים.

הצ'יפים ברשימה הם הצעות לתשובות והצעות לפעולות.

רשימות של צ'יפים יכולות להכיל עד 11 הצעות קשורות, וכל תווית של צ'יפ יכולה להכיל עד 25 תווים.

אפשרויות העיצוב והערכים מפורטות במאמר AgentContentMessage.

צ'אטים אינטראקטיביים

צ'אט אינטראקטיבי משלב מדיה, טקסט והצעות אינטראקטיביות בהודעה אחת. הם אידיאליים להצגת מידע קשור (לדוגמה, מוצר עם התמונה, השם והמחיר שלו) ולהנחיית המשתמשים לגבי השלב הבא, כמו הצעה ל"הצגת פרטים".

צ'אט אינטראקטיבי יכול להכיל את הדברים הבאים:

כל אחד מהשדות האלה הוא אופציונלי, אבל לפחות אחד מהשדות 1-3 חייב להיכלל בצ'אט האינטראקטיבי.

אפשר לשלוח כמה כרטיסים ביחד בקרוסלה שאפשר לגלול בה אופקית.

שימו לב שהמטען הייעודי הכולל של צ'אט אינטראקטיבי הוא 250KB.

לפרטים טכניים מלאים, אפשר לעיין במאמרי העזרה של צ'אט אינטראקטיבי.

גובה הכרטיס

צ'אט אינטראקטיבי מתרחב אנכית כדי להתאים לתוכן שלו. הגובה המינימלי שלהם הוא 112DP והגובה המקסימלי הוא 344DP. אם תוכן הכרטיס לא מספיק גדול כדי למלא את הגובה המינימלי של הכרטיס, הכרטיס מתרחב והגובה הנוסף מתמלא ברווח לבן.

המדיה בצ'אט אינטראקטיבי צריכה להתאים לאחד משלושת הגבהים הבאים:

  • Shorts: 112 dp
  • בינוני: 168 DP
  • גבוה: 264 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 לדוגמה.

Java

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

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

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

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

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

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

   rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444");
} catch(Exception e) {
   e.printStackTrace();
}
הקוד הזה הוא קטע מנציג RBM לדוגמה.

Python

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

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

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

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

# Append rich card and send to the user
cluster = messages.MessageCluster().append_message(rich_card)
cluster.send_to_msisdn('+12223334444')
הקוד הזה הוא קטע מנציג RBM לדוגמה.

C#‎

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

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

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

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

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

// Send rich card to user
rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
הקוד הזה הוא קטע מנציג RBM לדוגמה.

קרוסלות של צ'אטים אינטראקטיביים

קרוסלות מחברות יחד כמה צ'אטים אינטראקטיביים, ומאפשרות למשתמשים להשוות בין פריטים ולהגיב לכל אחד מהם בנפרד.

קרוסלות יכולות להכיל בין שניים לעשרה צ'אטים אינטראקטיביים. צ'אטים אינטראקטיביים בקרוסלות חייבים לעמוד בדרישות הכלליות של צ'אטים אינטראקטיביים לגבי תוכן וגובה, כפי שמתואר במסמכי התיעוד של צ'אטים אינטראקטיביים. מידע נוסף על הפריסה והמפרטים של קרוסלה זמין במסמכי התיעוד של קרוסלה.

דוגמה

הקוד הבא שולח קרוסלה של צ'אטים אינטראקטיביים. אפשרויות העיצוב והערכים מפורטות במאמר 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 לדוגמה.

Java

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

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

            List cardContents = new ArrayList();

            // Images for the carousel cards
            String card1Image = "https://storage.googleapis.com/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 לדוגמה.