קבלת אירועים

הנציג מקבל אירועים של תגובה לפעולה מאתר אחר (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)
    • התראות לגבי שירות ספציפי שהמשתמש ביקש והסכים לקבל
    • אישור על בקשת ההסרה של המשתמש, עם מידע שיעזור לו להגדיר את דרכי התקשורת המועדפות

דוגמה

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

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

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

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

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

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

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

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

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

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

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

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

    מדינה (קוד מדינה) מילת מפתח להרשמה
    ארצות הברית (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 מחיקת הנציג
REJECTED LAUNCHED אישור בקשת הפעלה שנדחתה בעבר.

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

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

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

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

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

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

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

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

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

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

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