קבלת הודעות

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

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

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

טיפול בהודעות נכנסות

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

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

אישור ההודעה

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

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

בודקים שההודעה היא מ-Google

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

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

1. ינתח את הכותרת X-Goog-Signature של ההודעה. הערך הזה מגובב (hashed), עותק בקידוד base64 של המטען הייעודי (payload) של גוף ההודעה.

2. שימוש באסימון הלקוח (שהופיע כשהגדרתם את תגובה לפעולה מאתר אחר (webhook)) בתור מפתח, ליצור SHA512 HMAC של הבייטים של המטען הייעודי של ההודעות מקודדים את התוצאה ב-base64.

   הערה: אם קיבלתם מפתח שותף במהלך ההרשמה ל-Business הודעות, משתמשים בהן כמפתח ל-SHA512 HMAC במקום ללקוח ב-Assistant. אם מעדכנים את ה-webhook, צריך להשתמש באסימון הלקוח לשליחת ההודעה אימות באמצעות ההגדרה החדשה של ה-webhook.

3. משווים בין הגיבוב X-Goog-Signature לבין הגיבוב שיצרתם.

   • אם הגיבובים תואמים, סימן שאישרתם ש-Google שלחה את ההודעה.
   • אם הגיבובים לא תואמים, בדקו את תהליך הגיבוב (hashing) הודעה. אם תהליך הגיבוב פועל כראוי ומקבלים הודעה שלדעתכם נשלחה אליכם במרמה צור איתנו קשר (עליך לחתום באמצעות חשבון Google ב-Business Messages).

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

זיהוי המיקום

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

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

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

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

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

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

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

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

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

מעבדים את תוכן ההודעה.

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

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

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

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

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

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

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

הערה: אם מפעילים את האפשרות של תשובות אוטומטיות ב-Dialogflow אינטגרציה, Business Messages ו-Dialogflow לשלוח למשתמשים את התשובה הטובה ביותר נמצאה התאמה לתשובה.

סוגי הודעות

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

למידע על עיצוב וערכים: 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 והוא כולל את כתובות ה-URL האלה בשדה text של המטען הייעודי של ההודעות.

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

הצעה

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

הודעות עם הצעות נראות בפורמט הבא.

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

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

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