Hello, World

  • Agents and users communicate through messages and events, with agents sending via the Business Messages API and receiving user input at webhooks as JSON.

  • A typical conversation flow involves the user initiating contact, sending typing events, and exchanging messages with the agent.

  • The example conversation demonstrates a simple "Hello, I'm World!" from the user and a "Hello, World" response from the agent.

  • Messages and events are represented by JSON structures containing details like agent and conversation IDs, message content, and timestamps.

  • Delivery receipts are sent back to the agent when messages are successfully delivered to the user's device.

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