קבלת אירועים

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

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

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

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

דוגמה

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

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

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

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

הסיבות להסרת הרשמה מוצגות בסקירה הכללית של 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)	comenzar

כללים עסקיים

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

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

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

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

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

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