Handoff from bot to live agent

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.

1. The user begins the conversation with the agent.

2. 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",
   }
   

3. 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",
   }
   

4. 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'
     }
   }"
   

5. A live agent becomes available.

6. 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',
     },
   }"
   

7. 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'
     }
   }"
   

8. 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.

9. 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',
     },
   }"
   

10. The agent sends all subsequent messages with BOT representatives unless another live agent joins the conversation.