Envía y recibe eventos para enriquecer las conversaciones

En las conversaciones de Business Messages, los eventos informan y enriquecen la experiencia conversacional de los usuarios y agentes mediante la comunicación del contenido que no es de mensajes. Para los usuarios, los eventos se muestran como notificaciones dentro de sus conversaciones y se activan en función de varias acciones que los usuarios puedan realizar. Los agentes reciben eventos en sus webhooks y envían eventos con llamadas a la API.

Los agentes deben estar al tanto de los eventos iniciados por el usuario y deben poder responder en consecuencia. Por ejemplo, si un usuario solicita un agente en vivo, pero no puede responder de manera positiva o negativa a la solicitud, se genera una mala experiencia para el usuario.

Tipos de eventos

Cada evento pertenece a un tipo en particular:

  • Los eventos de solicitud de agente en vivo indican que el usuario desea hablar directamente con un agente en vivo.

    Si el agente puede realizar la transición de la conversación a un representante humano, envía un evento Representante representado y envía mensajes posteriores de un representante humano.

    Si el agente no puede migrar la conversación a un representante humano, envía un mensaje para notificar al usuario cuando un agente humano esté disponible.

  • Los eventos de unión/izquierda representan a los usuarios cuando un agente humano se une a una conversación o la abandona. Estos eventos muestran notificaciones en la conversación y ayudan a establecer las expectativas del usuario sobre la capacidad de respuesta y los tipos de preguntas que pueden hacer.

    El representante se unió o salió de la reunión

  • Los eventos de escritura indican que el usuario o agente está escribiendo.

    Para los usuarios, el valor booleano isTyping indica su estado de escritura. Cada cambio de estado activa un evento nuevo.

    Los agentes pueden enviar eventos TYPING_STARTED y TYPING_STOPPED para mostrar indicadores de escritura en la conversación. Cuando escribes eventos de agentes, les indicas a los usuarios que un representante humano está redactando una respuesta o que la automatización de backend está procesando su pregunta o solicitud.

    Indicador de escritura

Enviar un evento

Para enviar un evento, ejecute el siguiente comando. Reemplaza los siguientes elementos:

  • CONVERSATION_ID por el identificador de la conversación a la que quieres enviar la encuesta
  • EVENT_ID con un identificador único para el evento
  • PATH_TO_SERVICE_ACCOUNT_KEY por la ruta de acceso a la clave de tu cuenta de servicio en la máquina
  • EVENT_TYPE con un valor de EventType
  • REPRESENTATIVE_NAME por el nombre orientado al usuario del agente en vivo o la automatización que crea el evento
  • REPRESENTATIVE_TYPE con un valor de 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',
  },
}"

Para ver las opciones de formato y valor, consulta conversations.events.

Ejemplo: Envía un evento a un representante representativo

# 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

Recibe un evento

Cuando un usuario activa un evento en su dispositivo, tu agente recibe el evento en su webhook. Recibe y procesa eventos de la misma manera en que recibes mensajes.

Los eventos iniciados por el usuario tienen el siguiente formato.

{
  "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",
  }
}

Para ver las opciones de formato y valor, consulta UserMessage.