Hello, World

  • Agents and users communicate by sending and receiving messages and events through the Business Messages API and webhooks.

  • User interactions, such as typing and sending messages, are sent to the agent as JSON payloads containing relevant information like user details and message content.

  • Agents can respond to users with messages containing text and optional representative details like display name and avatar.

  • The platform provides delivery receipts to the agent, confirming the delivery status of messages sent to the user.

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