דף זה תורגם על ידי Cloud Translation API.

קבלת הודעות

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

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

בדף היומנים של Communications Developer Console אפשר לנפות באגים בבעיות של שליחת הודעות.

ניהול הודעות נכנסות

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

אישור ההודעה

כדי לאשר הודעה שהתקבלה מה-webhook, צריך להחזיר תגובת HTTP חוקית להודעות שנשלחות ל-webhook שלכם.

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

איך לוודא שההודעה נשלחה מ-Google

עליכם לוודא ש-Google שלחה את ההודעה לפני שעבדה את תוכן ההודעה.

כדי לוודא ש-Google שלחה הודעה שקיבלתם,

יש לנתח את הכותרת X-Goog-Signature של ההודעה. זהו עותק מגובב (hashed) של ההודעות המקודדות base64 של גוף המטען.
באמצעות אסימון הלקוח (שמוצג כשהגדרתם את ה-webhook) כמפתח, יוצרים SHA512 HMAC של הבייטים של המטען הייעודי (payload) של ההודעה ומקודדים את הבסיס664.

הערה: אם קיבלתם מפתח שותף במהלך ההרשמה ל-Business Messages, השתמשו בו כמפתח ל-HMAC של SHA512 במקום לאסימון הלקוח. אם אתם מעדכנים את ה-webhook, השתמשו באסימון הלקוח לאימות ההודעה עם ההגדרה החדשה של ה-webhook.
משווים בין הגיבוב X-Goog-Signature לבין הגיבוב שיצרתם.
- אם הגיבובים תואמים, וידאתם ש-Google שלחה את ההודעה.
- אם הגיבובים לא תואמים, בדקו את תהליך הגיבוב בהודעה טובה. אם תהליך הגיבוב פועל כמו שצריך ומופיעה הודעה שאתם סבורים שנשלחה אליכם במרמה, אפשר ליצור איתנו קשר (יש להיכנס באמצעות חשבון Business Messages ב-Google).

עיינו בדוגמה לאימות הודעות במאגרים של GitHub עבור הבוטים של Echo ב-Java, ב-Node.js וב-Python.

זיהוי הלוקאל

המשתמשים מתקשרים ממספר מיקומים בשפות רבות. הודעות עסקיות מייצגות את העדפות השפה של המשתמשים בשדות resolvedLocale ו-userDeviceLocale, שמבוססים על הגדרות הלוקאל של המכשירים שלהם. ראו לוקליזציה ולוקאלים.

כשהדבר מתאפשר, יש לנתב הודעות ולכתוב תגובות על סמך העדפות השפה של המשתמשים.

ניתוב ההודעה על סמך ההקשר שלה

ההקשר של ההודעה מציין איזה סוג של מידע המשתמש עשוי לחפש. לדוגמה, אם משתמש שולח הודעה עם ערך של placeId, הוא שלח הודעה על מיקום ספציפי (המזוהה לפי placeId) וסביר להניח שהוא ישאל שאלות ספציפיות למיקום. באופן דומה, אם בהודעה יש ערך של nearPlaceId, שמזהה מיקום בקרבת המשתמש, סביר להניח שהמשתמש ירצה לדעת מידע ספציפי על המיקום, אבל הנציג צריך לאשר את המיקום שהמשתמש רוצה לשוחח איתו לפני התחלת השיחה.

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

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

זיהוי סוג ההודעה שהמשתמש שלח

המשתמשים יכולים לשלוח שלושה סוגים של הודעות:

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

עיבוד תוכן ההודעה

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

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

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

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

שליחת תגובה למשתמש

כשהנציג מזהה את התגובה הנכונה – באמצעות אוטומציה או דרך נציג תמיכה – הוא שולח הודעה וממשיך את השיחה עם המשתמש.

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

סוגי הודעות

הקוד הבא מראה איך הנציג מקבל הודעות.

מידע על הפורמט והערך זמין UserMessage.

טקסט

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

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "message": {
    "messageId": "MESSAGE_ID",
    "name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "text": "MESSAGE_TEXT",
    "createTime": "MESSAGE_CREATE_TIME",
  },
  "dialogflowResponse": {
    "autoResponded": "BOOLEAN",
    "faqResponse": {
      "userQuestion": "USER_QUESTION",
      "answers": [{
        "faqQuestion": "FAQ_QUESTION",
        "faqAnswer": "FAQ_ANSWER",
        "matchConfidenceLevel": "CONFIDENCE_LEVEL",
        "matchConfidence": "CONFIDENCE_NUMERIC",
      }],
    },
  },
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

לגבי אפשרויות עיצוב וערך, אפשר לעיין בMessage.

תמונה

בנוסף לשליחת טקסט, המשתמשים יוכלו לשלוח תמונות לנציג שלכם כהודעות. התכונה Business Messages מאחסנת תמונות למשך 7 ימים בכתובת הכתובות החתומות, וכוללת את כתובות ה-URL האלה בשדה text של המטען הייעודי (payload) של ההודעה.

אם הנציג כולל אוטומציה, צריך לוודא שהאוטומציה יודעת איך להגיב אם משתמש משתף תמונה. כדי ליצור תמונות של נציגים בזמן אמת, חשוב לוודא שהתמונות הועברו או שניתן ללחוץ על כתובות ה-URL בהודעות.

...
"message": {
    "text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
  }
...

לגבי אפשרויות עיצוב וערך, אפשר לעיין בMessage.

הצעה

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

הפורמט של הודעות הצעה.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "suggestionResponse": {
    "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "postbackData": "POSTBACK_DATA",
    "createTime": "RESPONSE_CREATE_TIME",
    "text": "SUGGESTION_TEXT",
    "suggestionType": "SUGGESTION_TYPE",
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

לגבי אפשרויות עיצוב וערך, אפשר לעיין בSuggestionResponse.

בקשת אימות

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

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

הפורמט של הודעות בקשת אימות הוא.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "authenticationResponse": {
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "REDIRECT_URI",
    "errorDetails": {
      "error": "ERROR",
      "errorDescription": "ERROR_DESCRIPTION",
    },
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

לגבי אפשרויות עיצוב וערך, אפשר לעיין בAuthenticationResponse.

הקשר להודעה

כל הודעה מכילה מידע לגבי ההקשר של מקור ההודעה.

...
  "context": {
    "customContext": "CUSTOM_CONTEXT",
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
    "deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
    "widget": {
      "url": "WEBSITE_URL",
      "widgetContext": "WIDGET_CONTEXT",
    },
  },
...

שדה	תיאור
`customContext`	נתוני הקשר שהשותף ציין.
`entryPoint`	משטח ההודעות שדרכו המשתמש התחיל את השיחה, כפי שהוגדר על ידי EntryPoint.
`placeId`	מזהה ייחודי ממסד הנתונים של מקומות Google למיקום שאליו המשתמש שלח הודעה. הוא מופיע רק בהודעות מנקודות כניסה ספציפיות למיקום.
`nearPlaceId`	מזהה ייחודי ממסד הנתונים של מקומות Google למיקום הראשון בחבילה מקומית. לאשר את המיקומים שאיתם המשתמשים רוצים להתכתב בצ'אט כאשר יתקבלו ערכי `nearPlaceId`.
`deflectedPhoneNumber`	מספר הטלפון ש-Business Messages מנע מהמשתמש להתקשר כשהשיחה התחילה.
`resolvedLocale`	ההתאמה המחושבת הטובה ביותר למיקום של המשתמש (דווח ב-`userDeviceLocale`) וללוקאלים הנתמכים של הנציג (נקבע על ידי הגדרות השיחה שצוינו). כדאי לעיין בלוקליזציה ובהתחלת השיחה. ערך הלוקאל הוא תג שפה בפורמט IETF BCP 47 בפורמט תקין.
`userInfo.displayName`	שם המשתמש ששלח את ההודעה. אם המשתמש מבטל את הסכמתו לשיתוף זהות, השדה הזה ריק.
`userInfo.userDeviceLocale`	המיקום של המשתמש, המדווח על ידי המכשיר שלו, כתג שפה בפורמט IETF BCP 47.
`widget.url`	כתובת ה-URL של האתר שבו הושקה משטח השיחה.
`widget.widgetContext`	ערך המאפיין `data-bm-widget-context` של הווידג'ט שבו השתמשת כדי להתחיל את השיחה.

היסטוריית השיחות

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