קבלת אירועים

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

האירועים האלה מסווגים לפי המקור שלהם:

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

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

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

אירועי משתמש

אירועים של משתמשים הם התראות מהמכשיר של המשתמש שמדווחות על סטטוס ההודעה או על שינויים במינוי (כלומר, המשתמש ביטל את המינוי או חידש את המינוי ב-Google Messages).

אפשרויות העיצוב והערכים המלאות מפורטות במאמר בנושא 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"
}

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

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

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

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

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

דוגמה למטען ייעודי (payload) בפורמט JSON:

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

איך עובד ביטול המינוי

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

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

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

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

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

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

כללים עסקיים

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

דוגמה

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

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

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

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

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

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

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

דוגמה למטען ייעודי (payload) בפורמט JSON:

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

איך מתבצעת הרשמה מחדש

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

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

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

כללים עסקיים

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

אירועים בפלטפורמה

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

מצב ההפעלה של הנציג השתנה

פלטפורמת RBM שולחת AgentLaunchEvent בכל פעם שחל שינוי בסטטוס ההשקה של הנציג. לדוגמה, כשמצב הסוכן משתנה מ-PENDING ל-LAUNCHED. האירוע מועבר כהודעת Pub/Sub. כדי להבדיל בין האירוע הזה לבין אירועים אחרים, בודקים את הנתיב message.attributes.type לערך agent_launch_event.

הגדרת webhook

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

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

  • מגדירים webhook להעברת הודעות ב-RBM (זו דרישה לקבלת הודעות ממשתמשים ואירועים שקשורים למשתמשים).
  • כדי להבחין בין אירועי משתמשים לבין אירועים של מצב ההפעלה של הסוכן, בודקים את הנתיב message.attributes.type לערך agent_launch_event.

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

ההודעה 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) של האירוע מציין את מצב ההפעלה החדש של הסוכן. אלה הערכים האפשריים:

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

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

שינויים במצב ההפעלה שמתבצעים על ידי שותף

אלה מעברים מותרים שבדרך כלל מטופלים על ידי שותפים:

מצב ההפעלה הקודם מצב השקה חדש פעולת טריגר
UNSPECIFIED PENDING שליחה לבדיקה.
PENDING UNLAUNCHED ביטול בקשת הפעלה בהמתנה.
UNLAUNCHED PENDING שליחה לבדיקה.
REJECTED PENDING שולחים מחדש לבדיקה.

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

האירוע הזה מציין שתוקף ההודעה פג (TTL) וההודעה בוטלה בהצלחה. זוהי נקודת התחלה טובה לאסטרטגיית הודעות הגיבוי.

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

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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

האירוע הזה מציין שתוקף ה-TTL של ההודעה פג, אבל היא לא בוטלה בהצלחה.

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

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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

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

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

הקודם
שליחת אירועים
הבא
בדיקת יכולות