Envie e receba eventos para enriquecer conversas

Nas conversas do Business Messages, os eventos informam e enriquecem a experiência de conversa de usuários e agentes ao comunicar conteúdo que não é de mensagem. Para usuários, os eventos são exibidos como notificações nas conversas e acionados com base em várias ações que os usuários podem realizar. Os agentes recebem eventos nos webhooks e os enviam com chamadas de API.

Os agentes precisam estar cientes dos eventos iniciados pelo usuário e capazes de responder de acordo. Por exemplo, se um usuário solicita um agente em tempo real, mas o agente não consegue responder positiva ou negativamente à solicitação, isso resulta em uma experiência do usuário ruim.

Tipos de evento

Cada evento pertence a um tipo específico:

  • Os eventos de agente em tempo real solicitado indicam que o usuário quer falar diretamente com um agente em tempo real.

    Se o agente puder fazer a transição da conversa para um representante humano, envie um evento Representante representativo e envie mensagens subsequentes de um representante humano.

    Se o agente não conseguir transferir a conversa para um representante humano, envie uma mensagem para notificar o usuário e informar quando um agente em tempo real estará disponível.

  • Os eventos de representação de que entrou/saiu informam os usuários quando agentes ativos entram ou saem de uma conversa. Esses eventos exibem notificações na conversa e ajudam a definir as expectativas do usuário sobre a capacidade de resposta e os tipos de perguntas que podem ser feitas.

    Representante participante/à esquerda

  • Os eventos de digitação indicam que o usuário ou o agente está digitando.

    Para os usuários, o booleano isTyping indica o status de digitação. Cada mudança de status aciona um novo evento.

    Os agentes podem enviar eventos TYPING_STARTED e TYPING_STOPPED para exibir indicadores de digitação na conversa. Digitar eventos de agentes informa aos usuários que um representante humano está escrevendo uma resposta ou que a automação de back-end está processando a pergunta ou solicitação.

    Indicador de digitação

Enviar um evento

Para enviar um evento, execute o comando a seguir. Substitua os seguintes itens:

  • CONVERSATION_ID pelo identificador da conversa para a qual você quer enviar a pesquisa.
  • EVENT_ID com um identificador exclusivo para o evento
  • PATH_TO_SERVICE_ACCOUNT_KEY pelo caminho para a chave da conta de serviço na sua máquina
  • EVENT_TYPE com um valor de EventType
  • REPRESENTATIVE_NAME pelo nome voltado ao usuário do agente ao vivo ou automação que cria o evento;
  • REPRESENTATIVE_TYPE com um 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 opções de formatação e valor, consulte conversations.events.

Exemplo: enviar um evento de participação de um representante.

# 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

Receber um evento

Quando um usuário aciona um evento no próprio dispositivo, seu agente recebe o evento no webhook dele. Receba e processe eventos da mesma forma que recebe mensagens.

Os eventos iniciados pelo usuário têm o seguinte 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 opções de formatação e valor, consulte UserMessage.