Using incoming webhooks

Incoming webhooks let you send asynchronous messages into Hangouts Chat from applications that aren't bots themselves. For example, you can configure a monitoring application to notify oncall personnel on Hangouts Chat when a server goes down. Incoming webhooks serve as a quick and easy way to integrate with existing workflows such as these without the overhead of writing entire bot applications.

Applications 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.

Setting up an incoming webhook

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
Need help? Visit our support page.