לשלוח ולקבל אירועים כדי להעשיר את השיחות

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

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

סוגי אירועים.

כל אירוע שייך לסוג מסוים:

  • אירועים של בקשת נציג תמיכה מציינים שהמשתמש רוצה לדבר ישירות עם נציג.

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

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

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

    הנציג הצטרף/עזב

  • אירועי הקלדה מציינים שהמשתמש או הנציג מקלידים.

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

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

    אינדיקטור להקלדה

שליחת אירוע

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

  • CONVERSATION_ID עם מזהה השיחה שרוצים לשלוח את הסקר
  • EVENT_ID עם מזהה ייחודי לאירוע
  • PATH_TO_SERVICE_ACCOUNT_KEY עם הנתיב למפתח של חשבון השירות במחשב
  • EVENT_TYPE עם ערך של EventType
  • REPRESENTATIVE_NAME עם שם המשתמש הפעיל של הסוכן הפעיל או האוטומציה שבה נוצר האירוע
  • REPRESENTATIVE_TYPE עם ערך של RepresentativeType
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/CONVERSATION_ID/events?eventId=EVENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-messages" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businessmessages`" \
-d "{
  'eventType': 'EVENT_TYPE',
  'representative': {
    'avatarImage': 'REPRESENTATIVE_AVATAR_URL',
    'displayName': 'REPRESENTATIVE_NAME',
    'representativeType': 'REPRESENTATIVE_TYPE',
  },
}"

לעיון באפשרויות הפורמט והערך, אפשר לעיין במאמר conversations.events.

דוגמה: שליחת אירוע מייצג של הצטרפות

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     https://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This code sends a REPRESENTATIVE_JOINED event to the user.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/events#send

# Replace the __CONVERSATION_ID__ with a conversation id that you can send messages to
# Make sure a service account key file exists at ./service_account_key.json

curl -X POST "https://businessmessages.googleapis.com/v1/conversations/__CONVERSATION_ID__/events?eventId=6a0af2c6-787d-4097-870d-93fe20351747" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-messages" \
-H "$(oauth2l header --json ./service_account_key.json businessmessages)" \
-d "{
  'eventType': 'REPRESENTATIVE_JOINED',
  'representative': {
    'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
    'displayName': 'Chatbot',
    'representativeType': 'HUMAN'
  }
}"
send-event-representative-joined.sh

קבלת אירוע

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

אירועים ביוזמת המשתמש מופיעים בפורמט הבא.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "requestId": "REQUEST_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "sendTime": "SEND_TIME",
  "userStatus": {
    "isTyping": "BOOLEAN",
    "requestedLiveAgent": "BOOLEAN",
    "createTime": "CREATION_TIME",
  }
}

לעיון באפשרויות הפורמט והערך, אפשר לעיין במאמר UserMessage.