הנציג שלכם מקבל אירועי 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 שלכם.מילת המפתח נקבעת לפי קוד המדינה בן שתי האותיות של מספר הטלפון של המשתמש. בטבלה הבאה מפורטות מילות המפתח לכל מדינה נתמכת.
מדינה (קוד מדינה) מילת מפתח לביטול הרשמה ארצות הברית (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"
}איך עובד חידוש המינוי
- האפשרות הרשמה, שזמינה גם בתפריט הצ'אט וגם בקישור בצ'אט, מאפשרת למשתמשים להירשם מחדש לשיחה שהם הסירו את עצמם ממנה.
כשבוחרים באפשרות Subscribe, מתבצעות שתי פעולות בו-זמנית: אפליקציית 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.
מבנה המטען הייעודי (payload) של האירוע
ה-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"
}ההודעה פגה, הביטול נכשל
האירוע הזה מציין שזמן החיים של ההודעה פג, אבל היא לא בוטלה בהצלחה.
אפשרויות מלאות של פורמטים וערכים מפורטות במאמרי העזרה של ServerEvent.
{
"phoneNumber": "PHONE_NUMBER",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID",
"eventType": "TTL_EXPIRATION_REVOKE_FAILED",
"eventId": "EVENT_ID",
"sendTime": "TIMESTAMP"
}אין הבטחה שההודעה תימסר.
- אם ההודעה נמסרה, תקבלו אירוע
DELIVEREDב-webhook. - אם ההודעה לא נמסרה, משתמשים ב-API לביטול כדי לשלוח בקשת ביטול.
אם ההודעה דחופה, כמו סיסמה חד-פעמית או התראה על הונאה, עדיף לשלוח את ההודעה בערוץ חלופי כמו SMS, גם אם זה יגרום לשליחת הודעות כפולות למשתמש.