אירועים

אירועים הם התראות שהסוכן יכול לשלוח ולקבל. יש שלושה סוגים של אירועים:

אירועים שנוצרו בשרת

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

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

סטטוס ההפעלה של הנציג השתנה

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

הגדרת webhook

אתם יכולים להשתמש בwebhook ברמת השותף או ברמת הנציג כדי לקבל את ההתראות האלה.

דרישות מוקדמות

המבנה של המטען הייעודי של האירוע

ההתראה AgentLaunchEvent נמסרת כהודעת Pub/Sub. לדוגמה:

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

השדה AgentLaunchEvent.LaunchState במטען הייעודי (payload) של האירוע מציין את מצב ההפעלה החדש של הסוכן. אלה הערכים האפשריים:

ערך מצב הפעלת הנציג פרטים
UNLAUNCHED לא הושק אפשר לערוך.
PENDING בהמתנה הבקשה נשלחה לחברת התקשורת לבדיקה.
LAUNCHED הופעל הודעות מותרות בספק מסוים.
REJECTED נדחה על ידי ספק מסוים סיבת הדחייה מצוינת בתגובה.
SUSPENDED הושעו בחברת תובלה מסוימת סיבת ההשעיה מפורטת בתגובה.

שדה הנתונים מכיל אובייקט JSON בקידוד Base64 עם פרטי מצב ההשקה. דוגמה ל-JSON מפוענח:

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

בטבלה הבאה מוצגים מצבי ההפעלה של הסוכן והפעולות שמפעילות אותם:

מצב הפעלה ישן מצב השקה חדש טריגר לשינוי
PENDING LAUNCHED הנציג בהמתנה אושר.
PENDING REJECTED הבקשה של הנציג בהמתנה נדחתה.
LAUNCHED SUSPENDED הנציג שהופעל הושעה.
SUSPENDED LAUNCHED הנציג שהושעה הופעל מחדש.
SUSPENDED TERMINATED הנציג שהושעה נמחק.
TERMINATED LAUNCHED הופעל נציג שהשימוש בו הופסק.

ההודעה פג תוקף; הביטול הצליח

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

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

תוקף ההודעה פג; הביטול נכשל

התוקף של ההודעה פג, אבל היא לא בוטלה.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

אין ערובה לכך שההודעה תימסר.

  • אם ההודעה נמסרה, תקבלו אירוע DELIVERED ב-webhook.
  • אם ההודעה לא נמסרה, אפשר להשתמש ב-API לביטול כדי לשלוח בקשה לביטול.

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

אירועים שנוצרו על ידי משתמשים

בדומה להודעות משתמשים ולבדיקות יכולות, הסוכן מקבל אירועי משתמשים בפורמט JSON.

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

המשתמש מקבל הודעה מהנציג

האירוע הזה מציין שהודעה נמסרה.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

המשתמש קורא את ההודעה של נציג התמיכה

האירוע הזה מציין שהודעה נפתחה או אושרה.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

המשתמש מתחיל להקליד

האירוע הזה מציין שמשתמש מקליד.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

משתמש שולח הודעת טקסט

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

משתמש שולח קובץ

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

המשתמש מקיש על הצעה לתשובה

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

המשתמש מקיש על פעולה מוצעת

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

המשתמש ביטל את ההרשמה לשיחה

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

האירוע UNSUBSCRIBE מציין שהמשתמש ביטל את ההרשמה לשיחה עם הנציג ועם העסק שהוא מייצג. דוגמה למטען ייעודי (payload) של JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

איך זה עובד

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

  • כשלוחצים על הסרה, מתבצעות שתי פעולות בו-זמנית: אפליקציית Google Messages שולחת מילת מפתח ספציפית למדינה (לדוגמה, "STOP") לסוכן שלכם, ופלטפורמת RBM שולחת אירוע UNSUBSCRIBE ל-webhook.

    מילת המפתח נקבעת לפי קוד המדינה בן שתי האותיות של מספר הטלפון של המשתמש. בטבלה הבאה מפורטות מילות המפתח לכל מדינה נתמכת.

    מדינה (קוד מדינה) מילת מפתח לביטול הרשמה
    ארצות הברית (US), הודו (IN), בריטניה (GB), גרמניה (DE) עצירה
    ספרד (ES), מקסיקו (MX) BAJA
    צרפת (FR) עצירה
    ברזיל (BR) parar

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

  • כדי לזהות הפרות של מדיניות וכללים עסקיים, Google עוקבת אחרי דפוסי הודעות אחרי שמשתמש מבטל את ההרשמה.

כללים עסקיים

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

דוגמה

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

סיבות להסרה מרשימת התפוצה

כשמשתמש מבטל את המינוי שלו לסוכן, הוא יכול לבחור סיבה מבין האפשרויות הבאות:

  • לא ביקשתי לקבל את ההודעות האלה
  • יותר מדי הודעות
  • איבדתי עניין
  • ספאם
  • אחר

בשלב הזה, הסיבות להסרת ההרשמה לא משותפות עם שותפים או ספקי סלולר.

המשתמש נרשם מחדש לשיחה

המשתמשים יכולים להירשם מחדש לשיחה שהם ביטלו את ההרשמה שלהם אליה ב-Google Messages.

האירוע SUBSCRIBE מציין שמשתמש רוצה לקבל הודעות מהסוכן שלכם, כולל תוכן לא חיוני כמו מבצעים. דוגמה למטען ייעודי (payload) של JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

איך זה עובד

  • האפשרות הרשמה, שזמינה בתפריט הצ'אט ובקישור בתוך הצ'אט, מאפשרת למשתמשים להירשם מחדש לשיחה שהם ביטלו את ההרשמה אליה.

  • כשלוחצים על הרשמה מופעלות שתי פעולות בו-זמנית: Google Messages שולח מילת מפתח ספציפית למדינה (לדוגמה, 'התחלה') לסוכן שלכם, ופלטפורמת RBM שולחת אירוע הרשמה ל-webhook שלכם.

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

    מדינה (קוד מדינה) מילת מפתח להרשמה
    ארצות הברית (US), הודו (IN), בריטניה (GB), גרמניה (DE) התחל
    ספרד (ES), מקסיקו (MX) ALTA
    צרפת (FR) Démarrer
    ברזיל (BR) começar

כללים עסקיים

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

אירועים שנוצרו על ידי נציגים

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

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

הנציג שולח אירוע READ

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

הקוד הבא שולח אירוע READ עבור הודעה עם messageId תואם.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_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 "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

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

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

Java

import com.google.rbm.RbmApiHelper;
…

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

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

Python

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

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

C#‎

using RCSBusinessMessaging;
…

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

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

הנציג שולח אירוע IS_TYPING

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

הקוד הבא שולח אירוע IS_TYPING.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_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 "{
  'eventType': 'IS_TYPING',
}"

Node.js

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

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

Java

import com.google.rbm.RbmApiHelper;
…

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

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

Python

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

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.

C#‎

using RCSBusinessMessaging;
…

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

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 הקוד הזה הוא קטע מנציג לדוגמה של RBM.
הקודם
קבלת הודעות
הבא
בדיקת יכולות