We will be winding down Google Business Messages on July 31, 2024. Read more
here.
Handoff from bot to live agent
Stay organized with collections
Save and categorize content based on your preferences.
When users communicate with agents, their expectations are set by how the agent
presents itself and who composes the messages they receive. Each time an agent
sends a message, it can identify whether an automated (BOT
) or live agent
(HUMAN
)
representative
composed the message. Users see this information within the conversation, and it
helps users understand what sorts of interactions they might expect at any given
point in time.
If an agent supports both BOT
and HUMAN
representatives, it's important to
provide context when switching between the two. When switching from a BOT
to a
HUMAN
representative, send a REPRESENTATIVE_JOINED
event before
sending messages from the HUMAN
representative, and properly label all
following messages from live agents as from HUMAN
representatives. When the
live agent leaves the conversation, send a REPRESENTATIVE_LEFT
event. These
framing events inform users that they can ask more complicated questions and can
expect more freeform responses.
In this conversation flow, the user's first interactions are with an automated
responder that sends messages as a BOT
representative, but a live agent joins
the conversation and sends messages as a HUMAN
representative. The live
agent's messages are framed by REPRESENTATIVE_JOINED
and REPRESENTATIVE_LEFT
events.

- The user begins the conversation with the agent.
Once the user begins typing a response, they send a typing event to the
agent.
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "live-agent-handoff",
"requestId": "1234567890",
"userStatus": {
"isTyping": "true",
"createTime": "2020-10-02T15:01:23.045123456Z",
},
"sendTime": "2020-10-02T15:01:24.045123456Z",
}
The user sends "Hi, I have a problem" as a message.
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "live-agent-handoff",
"requestId": "123123123",
"message": {
"messageId": "4444",
"name": "conversations/12345/messages/67890",
"text": "Hi, I have a problem",
"createTime": "2020-10-02T15:05:23.045123456Z",
},
"context": {
"entryPoint": "PLACESHEET",
"userInfo": {
"displayName": "Michael",
"userDeviceLocale": "en",
},
"resolvedLocale": "en",
}
"sendTime": "2020-10-02T15:05:24.045123456Z",
}
The agent sends "Thanks for contacting us. I'll pass this along when a live
agent is available to chat with you." as a message from a BOT
representative.
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/3333/messages" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json path/to/service/account/key.json businessmessages`" \
-d "{
'messageId': '5555',
'text': 'Thanks for contacting us. I'll pass this along when a live agent is available to chat with you.',
'representative': {
'avatarImage': 'https://live.agent/bot-avatar.jpg',
'displayName': 'Hello World Agent',
'representativeType': 'BOT'
}
}"
A live agent becomes available.
The agent sends a REPRESENTATIVE_JOINED
event before sending the first
message from the live agent.
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/12345/events?eventId=6666" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json /path/to/service/account/key.json businessmessages`" \
-d "{
'eventType': 'REPRESENTATIVE_JOINED',
'representative': {
'avatarImage': 'https://live.agent/human-avatar.jpg',
'displayName': 'Jane Doe',
'representativeType': 'HUMAN',
},
}"
The agent sends "I see you have a problem. How can I help?" as a message
from a HUMAN
representative.
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/3333/messages" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json path/to/service/account/key.json businessmessages`" \
-d "{
'messageId': '7777',
'text': 'I see you have a problem. How can I help?',
'representative': {
'avatarImage': 'https://live.agent/human-avatar.jpg',
'displayName': 'Jane Doe',
'representativeType': 'HUMAN'
}
}"
The live agent and the user exchange messages until the user's request is
fulfilled. All messages composed by the live agent are sent from a
HUMAN
representative.
The agent sends a REPRESENTATIVE_LEFT
event when the live agent leaves the
conversation.
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/12345/events?eventId=6666" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json /path/to/service/account/key.json businessmessages`" \
-d "{
'eventType': 'REPRESENTATIVE_LEFT',
'representative': {
'avatarImage': 'https://live.agent/human-avatar.jpg',
'displayName': 'Jane Doe',
'representativeType': 'HUMAN',
},
}"
The agent sends all subsequent messages with BOT
representatives unless
another live agent joins the conversation.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-14 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-14 UTC."],[[["\u003cp\u003eBusiness Messages allows agents to specify whether a message is composed by a bot (\u003ccode\u003eBOT\u003c/code\u003e) or a human agent (\u003ccode\u003eHUMAN\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003eWhen switching between bot and human representatives, agents should use \u003ccode\u003eREPRESENTATIVE_JOINED\u003c/code\u003e and \u003ccode\u003eREPRESENTATIVE_LEFT\u003c/code\u003e events to provide context to the user.\u003c/p\u003e\n"],["\u003cp\u003eThese events signal to users that a live agent is available and they can expect more complex interactions and freeform responses.\u003c/p\u003e\n"],["\u003cp\u003eUsing \u003ccode\u003eBOT\u003c/code\u003e and \u003ccode\u003eHUMAN\u003c/code\u003e representative types and framing events enhances user experience by setting clear expectations for the conversation flow.\u003c/p\u003e\n"]]],[],null,["# Handoff from bot to live agent\n\nWhen users communicate with agents, their expectations are set by how the agent\npresents itself and who composes the messages they receive. Each time an agent\nsends a message, it can identify whether an automated (`BOT`) or live agent\n(`HUMAN`)\n[representative](/business-communications/business-messages/guides/how-to/message/send#representatives)\ncomposed the message. Users see this information within the conversation, and it\nhelps users understand what sorts of interactions they might expect at any given\npoint in time.\n\nIf an agent supports both `BOT` and `HUMAN` representatives, it's important to\nprovide context when switching between the two. When switching from a `BOT` to a\n`HUMAN` representative, send a `REPRESENTATIVE_JOINED`\n[event](/business-communications/business-messages/guides/how-to/message/events) before\nsending messages from the `HUMAN` representative, and properly label all\nfollowing messages from live agents as from `HUMAN` representatives. When the\nlive agent leaves the conversation, send a `REPRESENTATIVE_LEFT` event. These\nframing events inform users that they can ask more complicated questions and can\nexpect more freeform responses.\n\nIn this conversation flow, the user's first interactions are with an automated\nresponder that sends messages as a `BOT` representative, but a live agent joins\nthe conversation and sends messages as a `HUMAN` representative. The live\nagent's messages are framed by `REPRESENTATIVE_JOINED` and `REPRESENTATIVE_LEFT`\nevents.\n\n1. The user begins the conversation with the agent.\n2. Once the user begins typing a response, they send a typing event to the\n agent.\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"live-agent-handoff\",\n \"requestId\": \"1234567890\",\n \"userStatus\": {\n \"isTyping\": \"true\",\n \"createTime\": \"2020-10-02T15:01:23.045123456Z\",\n },\n \"sendTime\": \"2020-10-02T15:01:24.045123456Z\",\n }\n\n3. The user sends \"Hi, I have a problem\" as a message.\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"live-agent-handoff\",\n \"requestId\": \"123123123\",\n \"message\": {\n \"messageId\": \"4444\",\n \"name\": \"conversations/12345/messages/67890\",\n \"text\": \"Hi, I have a problem\",\n \"createTime\": \"2020-10-02T15:05:23.045123456Z\",\n },\n \"context\": {\n \"entryPoint\": \"PLACESHEET\",\n \"userInfo\": {\n \"displayName\": \"Michael\",\n \"userDeviceLocale\": \"en\",\n },\n \"resolvedLocale\": \"en\",\n }\n \"sendTime\": \"2020-10-02T15:05:24.045123456Z\",\n }\n\n4. The agent sends \"Thanks for contacting us. I'll pass this along when a live\n agent is available to chat with you.\" as a message from a `BOT`\n representative.\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/3333/messages\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'messageId': '5555',\n 'text': 'Thanks for contacting us. I'll pass this along when a live agent is available to chat with you.',\n 'representative': {\n 'avatarImage': 'https://live.agent/bot-avatar.jpg',\n 'displayName': 'Hello World Agent',\n 'representativeType': 'BOT'\n }\n }\"\n\n5. A live agent becomes available.\n\n6. The agent sends a `REPRESENTATIVE_JOINED` event before sending the first\n message from the live agent.\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/12345/events?eventId=6666\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json /path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'eventType': 'REPRESENTATIVE_JOINED',\n 'representative': {\n 'avatarImage': 'https://live.agent/human-avatar.jpg',\n 'displayName': 'Jane Doe',\n 'representativeType': 'HUMAN',\n },\n }\"\n\n7. The agent sends \"I see you have a problem. How can I help?\" as a message\n from a `HUMAN` representative.\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/3333/messages\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'messageId': '7777',\n 'text': 'I see you have a problem. How can I help?',\n 'representative': {\n 'avatarImage': 'https://live.agent/human-avatar.jpg',\n 'displayName': 'Jane Doe',\n 'representativeType': 'HUMAN'\n }\n }\"\n\n8. The live agent and the user exchange messages until the user's request is\n fulfilled. All messages composed by the live agent are sent from a\n `HUMAN` representative.\n\n9. The agent sends a `REPRESENTATIVE_LEFT` event when the live agent leaves the\n conversation.\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/12345/events?eventId=6666\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json /path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'eventType': 'REPRESENTATIVE_LEFT',\n 'representative': {\n 'avatarImage': 'https://live.agent/human-avatar.jpg',\n 'displayName': 'Jane Doe',\n 'representativeType': 'HUMAN',\n },\n }\"\n\n10. The agent sends all subsequent messages with `BOT` representatives unless\n another live agent joins the conversation."]]