إرسال الأحداث وتلقّيها لإثراء المحادثات

في محادثات "الرسائل التجارية"، تساعد الأحداث في إثراء تجربة المستخدم والوكلاء من خلال تقديم محتوى غير رسالة. وبالنسبة إلى المستخدمين، يتم عرض الأحداث كإشعارات ضمن المحادثات ويتم تشغيلها بناءً على الإجراءات المختلفة التي يمكن للمستخدمين اتخاذها. يتلقّى موظّفو الدعم أحداثًا على الردّ التلقائي على الويب ويرسلون الأحداث من خلال طلبات البيانات من واجهة برمجة التطبيقات.

يجب أن يكون الوكلاء على علم بالأحداث التي يجريها المستخدم وأن يكونوا قادرين على الاستجابة وفقًا لذلك. على سبيل المثال، إذا طلب أحد المستخدمين وكيلاً مباشرًا، ولكن تعذّر على الوكيل الردّ بالإيجاب أو سلبًا عليه، سيؤدي ذلك إلى تجربة سيئة للمستخدم.

أنواع الأحداث

ينتمي كل حدث إلى نوع معيّن:

  • تشير أحداث تم طلبه من قِبل موظّف دعم مباشر إلى أنّ المستخدم يرغب في التحدّث مباشرةً إلى أحد موظّفي الدعم.

    إذا كان بإمكان الوكيل نقل المحادثة إلى ممثّل عن فريق بشري، أرسِل حدث ممثل ممثّل للانضمام، ثم أرسِل رسائل لاحقة من ممثّل بشري.

    في حال تعذّر على الوكيل نقل المحادثة إلى ممثّل عن فريق فعلي، أرسل رسالة لإعلام المستخدم وإعلامه بتاريخ توفّر موظّف دعم متاح مباشرةً.

  • تُعلِم الأحداث الممثل/المنضمّ إلى الجهة اليسرى المستخدمين عند انضمام موظّفي دعم مباشرين إلى محادثة أو مغادرتها. وتعرض هذه الأحداث الإشعارات في المحادثة، كما تساعد في تحديد توقعات المستخدم بشأن الاستجابة وأنواع الأسئلة التي يمكنهم طرحها.

    تم انضمام/مغادرة الممثل

  • تشير أحداث الكتابة إلى أن المستخدم أو الوكيل يكتب.

    بالنسبة إلى المستخدمين، تشير القيمة المنطقية 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

تلقّي حدث

عندما يشغّل أحد المستخدمين حدثًا على جهازه، يتلقى وكيلك الحدث في الرد التلقائي على الويب. يمكنك تلقي الأحداث ومعالجتها بنفس الطريقة التي تتلقى بها الرسائل.

تكون الأحداث التي يبدأها المستخدم بالتنسيق التالي.

{
  "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.