Setting up an incoming webhook

Incoming webhooks let you quickly define a one-off bot that injects messages into a room.

Bots using incoming webhooks have several restrictions:

  • They cannot be published, so they can't be installed in other chat rooms.

  • They are not conversational, since the webhook mechanism only works for inbound messages.

To set up and use a webhook is straightforward:

  1. Define the incoming webhook in Hangouts Chat, provide a name and optionally an avatar for the bot.
  2. Copy the system-generated URL and save it for your bot to use
  3. Your bot can send messages to that URL, using the message format elements.

These steps are described in more detail below.

Define an incoming webhook

From the chat room menu, select Configure Webhooks. A dialog appears that lists any incoming webhooks already defined for the room:

Click on ADD WEBHOOK, then fill in the name field and optionally the avatar URL field, then click SAVE.

Copy and save the webhook URL

In the Configure Webhooks screen shown above, find your webhook in the list and click the copy icon to copy the webhook URL.

Save this URL in your bot's source code or configuration so that it can be used as a message destination.

Send messages to the chat room

Construct an HTTP message and send it to the saved URL as shown below:

http_obj.request(
  uri=THE_SAVED_URL,
  method='POST',
  headers=message_headers,
  body=dumps(bot_message),
)

For a more complete code example, see the Incoming Webhooks quickstart.

Limitations

If only select organizational units (OUs) in your domain have bots enabled, incoming webhooks created in a room will fail with the following error:

{
  "error": {
    "code": 403,
    "message": "The caller does not have permission",
    "status": "PERMISSION_DENIED"
  }
}

Incoming webhooks do work in direct messages, but only when all users have bots enabled.

Send feedback about...

Hangouts Chat API
Hangouts Chat API