קבלת אירועים

הנציג מקבל אירועי 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"
}

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

{
  "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"
}

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

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

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

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

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

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

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

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

חשוב: כדי לעזור למפתחים לעבור לאירועי ה-webhook החדשים של UNSUBSCRIBE ושל SUBSCRIBE, מערכת Google Messages שולחת גם הודעות STOP ו-START לצד אירועי ה-webhook. אפשר להסתמך על הלוגיקה הקיימת של STOP/START לעכשיו, אבל מומלץ מאוד לעדכן את הלוגיקה כדי לטפל באירועים UNSUBSCRIBE ו-SUBSCRIBE, כי הם יהפכו לחובה בהתאם למפרט של GSMA.

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

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

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

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

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

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

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

חשוב: כדי לעזור למפתחים לעבור לאירועי ה-webhook החדשים של UNSUBSCRIBE ושל SUBSCRIBE, מערכת Google Messages שולחת גם הודעות STOP ו-START לצד אירועי ה-webhook. אפשר להסתמך על הלוגיקה הקיימת של STOP/START לעכשיו, אבל מומלץ מאוד לעדכן את הלוגיקה כדי לטפל באירועים UNSUBSCRIBE ו-SUBSCRIBE, כי הם יהפכו לחובה בהתאם למפרט של GSMA.

דוגמה למטען ייעודי (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)	התחלה
  ברזיל (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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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	הופעל נציג שהשימוש בו הופסק.

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

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

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