Hello, World

Sending and receiving messages and events are the core aspects of communication between an agent and a user. Agents send messages, events, and requests to users through the Business Messages API but receive user-created messages and events at their webhooks as JSON.

Below is an example conversation flow that uses sample data to illustrate how messages, events, and requests can create useful and meaningful interactions.

In this example, the user starts a conversation and sends the message "Hello, I'm World!", then the agent responds with "Hello, World".

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": "hello-world-bot",
     "requestId": "1234567890",
     "userStatus": {
       "isTyping": "true",
       "createTime": "2020-10-02T15:01:23.045123456Z",
     },
     "sendTime": "2020-10-02T15:01:24.045123456Z",
   }
   

3. The user sends "Hello, I'm World!" as a message.

   {
     "agent": "brands/1111/agents/2222",
     "conversationId": "3333",
     "customAgentId": "hello-world-bot",
     "requestId": "123123123",
     "message": {
       "messageId": "4444",
       "name": "conversations/12345/messages/67890",
       "text": "Hello! I'm World!",
       "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 "Hello, World" as a message.

   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': 'Hello, World',
       'representative': {
         'avatarImage': 'https://hello.world/avatar.jpg',
         'displayName': 'Hello World Agent',
         'representativeType': 'BOT'
     }
   }"
   

5. Upon message delivery, the user's device returns a delivery receipt.

   {
     "agent": "brands/1111/agents/2222",
     "conversationId": "3333",
     "customAgentId": "hello-world-bot",
     "receipts" : {
       "receipts": [
         {
           "message": "conversations/3333/messages/5555",
           "receiptType": "DELIVERED",
         }
       ],
       "createTime": "2020-10-02T16:01:23.045123456Z",
     },
     "sendTime": "2020-10-02T16:01:24.045123456Z",
   }