Event formats

This section describes the format of events that your bot receives from Hangouts Chat.

Event fields

When your bot receives an event from Hangouts Chat, the event includes a request body: this is the JSON payload that represents the event. This payload contains elements that are common to all event types, as well as elements that are specific to the event type. The following diagram shows the fields that may be present in the payload:

Common event fields

Common fields are always provided in the payload of all events, regardless of type.

Field Type Description
type String The type of the event the bot is receiving.
eventTime String The timestamp (formatted according to RFC 3339) indicating when the event was dispatched.

Type-specific event fields

Additional fields may be present in the request payload, if they are applicable to the event type.

Field Type Description Event type
message Message The message related to the event. Message, added to space.
space Space The room or DM related to the event. Message, added to space, removed from space.
user User The user related to the event. Message, added to space, removed from space.
thread Thread The thread a message belongs to. Message events only.

Event types

This section describes the types of events that your bot may receive, with examples of each type.

ADDED_TO_SPACE

This event indicates that your bot was added to a room or DM. Bots typically respond to this event by posting some kind of welcome message in a new thread in the room.

The following JSON example shows the request body for an ADDED_TO_SPACE event:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Chuck Norris Discussion Room"
    "type": "ROOM"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Chuck Norris",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "chuck@example.com"
  }
}

REMOVED_FROM_SPACE

This event indicates that your bot was removed from a room or DM. Bots don't respond to this event, because they have already been removed.

The following JSON example shows the request body for an REMOVED_FROM_SPACE event:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "type": "DM"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Chuck Norris",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "chuck@example.com"
  }
}

MESSAGE

This event represents a message sent to the bot.

The message details are stored as fields within the message field. Response behavior: posts a message in the same thread as the original user message.

An example payload:

{
  "type": "MESSAGE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Chuck Norris Discussion Room",
    "type": "ROOM"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Chuck Norris",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "chuck@example.com"
    },
    "createTime": "2017-03-02T19:02:59.910959Z",
    "text": "@TestBot Violence is my last option.",
    "argumentText": " Violence is my last option.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Chuck Norris",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "chuck@example.com"
  }
}