Send and receive events to enrich conversations

In Business Messages conversations, events inform and enrich the conversational experience of both users and agents by communicating non-message content. For users, events display as notifications within their conversations and trigger based on various actions users might make. Agents receive events at their webhooks and send events with API calls.

Agents should be aware of user-initiated events and be able to respond accordingly. For example, if a user requests a live agent, but the agent can't respond positively or negatively to the request, this results in a bad user experience.

Event types

Each event belongs to a particular type:

  • Live agent requested events indicate that the user wants to speak directly to a live agent.

    If the agent can transition the conversation to a human representative, send a Representative joined event, then send subsequent messages from a human representative.

    If the agent can't transition the conversation to a human representative, send a message to notify the user and inform them when a live agent will be available.

  • Representative joined/left events tell users when live agents join or leave a conversation. These events display notifications in the conversation and help set user expectations around responsiveness and the types of questions they can ask.

    Representative joined/left

  • Typing events indicate that the user or agent is typing.

    For users, the boolean isTyping indicates their typing status. Each status change triggers a new event.

    Agents can send TYPING_STARTED and TYPING_STOPPED events to display typing indicators in the conversation. Typing events from agents tells users that a human representative is composing a response or that backend automation is processing their question or request.

    Typing indicator

Send an event

To send an event, run the following command. Replace the following items:

  • CONVERSATION_ID with the identifier of the conversation you want to send the survey
  • EVENT_ID with a unique identifier for the event
  • PATH_TO_SERVICE_ACCOUNT_KEY with the path to your service account key on your machine
  • EVENT_TYPE with a value from EventType
  • REPRESENTATIVE_NAME with the user-facing name of the live agent or automation creating the event
  • REPRESENTATIVE_TYPE with a value from 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',
  },
}"

For formatting and value options, see conversations.events.

Example: Send a representative joined event

# 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

Receive an event

When a user triggers an event on their device, your agent receives the event at its webhook. Receive and process events the same way you receive messages.

User-initiated events have the following format.

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

For formatting and value options, see UserMessage.