Send messages to Google Chat with incoming webhooks

Incoming webhooks let you send asynchronous messages into Google Chat from applications that aren't Chat apps. For example, you can configure a monitoring application to notify on-call personnel on Google Chat when a server goes down.

Prerequisites

To run the example in this guide, you need:

Python

• Python 2.6 or greater.
• Access to the internet and a web browser.
• A Google Workspace account with access to Google Chat.
• An existing Google Chat space.

• The httplib2 library. If necessary, run the following command-line interface (CLI) command to install the library using pip:

  pip install httplib2
  

Node.js

• Node.js & npm installed.
• Access to the internet and a web browser.
• A Google Workspace account with access to Google Chat.
• An existing Google Chat space.

Create a webhook

To create a webhook, register it in the Google Chat space you want to receive messages, then write a script that sends messages.

Step 1: Register the incoming webhook

1. Open Google Chat in a web browser.
2. Go to the space to which you want to add a webhook.
3. At the top, next to space title, click Down Arrow > Manage webhooks.
4. If this space already has other webhooks, click Add another. Otherwise, skip this step.
5. For Name, enter "Quickstart Webhook".
6. For Avatar URL, enter https://developers.google.com/chat/images/chat-product-icon.png.
7. Click SAVE.
8. Click Copy to copy the full webhook URL.
9. Click outside the box to close the Incoming webhooks dialog.

Step 2: Write the webhook script

The example webhook script creates a message and sends it to the webhook URL with a POST request.

Choose a language below for specific instructions about how to create the webhook script:

Python

1. In your working directory, create a file named quickstart.py.

2. In quickstart.py, copy-and-paste the following code:

   python/webhook/quickstart.py

   View on GitHub

   from json import dumps
   
   from httplib2 import Http
   
   
   def main():
       """Hangouts Chat incoming webhook quickstart."""
       url = 'https://chat.googleapis.com/v1/spaces/7D8la4AAAAE/messages?key=' \
             'AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI&token=' \
             'HulDviWFMz6R5FW-GwlO4INCW1cZGDDExuWVaEbbr_g%3D'
       bot_message = {
           'text': 'Hello from a Python script!'}
       message_headers = {'Content-Type': 'application/json; charset=UTF-8'}
       http_obj = Http()
       response = http_obj.request(
           uri=url,
           method='POST',
           headers=message_headers,
           body=dumps(bot_message),
       )
       print(response)
   
   
   if __name__ == '__main__':
       main()

3. Replace the value for the url variable with the webhook URL you copied in Step 1: Register the incoming webhook.

Node.js

1. In your working directory, create a file named index.js.

2. In index.js, copy-and-paste the following code:

   node/webhook/index.js

   View on GitHub

   /**
    * Sends asynchronous message into Google Chat
    * @return{obj} response
    */
   function webhook() {
     const fetch = require('node-fetch');
     const webhookURL = 'https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages?key=AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI&token=u9IG_MuTBXw-tnqupPrPNinY2spKFcRBDp6dSldGUAw%3D';
   
     const data = JSON.stringify({
       'text': 'Hello from a Node script!',
     });
     let resp;
     fetch(webhookURL, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json; charset=UTF-8',
       },
       body: data,
     }).then((response) => {
       resp = response;
       console.log(response);
     });
     return resp;
   }
   

3. Replace the value for the webhookURL variable with the webhook URL you copied in Step 1: Register the incoming webhook.

Step 3: Run the webhook script

Run the sample by running the following command from your working directory in your CLI:

Python

  python3 quickstart.py

Node.js

  node index.js

When you run the sample code, the webhook sends a message to the space in which you registered it.

Start or reply to a message thread

You can start a message thread or reply to one by adding the threadKey parameter to the webhook URL.

Note: Each threadKey is unique to the app that sets it. If two different Chat apps or webhooks set the same threadKey, the messages do not thread. It is not possible to retrieve a threadKey from Chat API. The spaces.messages.thread.name field is the resource name of a thread in Chat API, not the threadKey.

Start a message thread

To post the first message of a thread with a webhook, append the threadKey parameter to the webhook URL. Set the threadKey to an arbitrary string, but remember what it is; you'll need to specify it again to post a reply to the thread.

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=ARBITRARY_STRING

Reply to a message thread

To send a message to an existing message thread, append the threadKey parameter to the webhook URL set to the value used to start the thread. For example, sending a message to following URL posts a reply to the thread where threadKey is MY-THREAD:

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=MY-THREAD

Limits and considerations

As you configure webhooks, take note of these limits and considerations:

• Each webhook only works in the Chat space in which it's registered.

• You can't publish webhooks on the Google Workspace Marketplace.

• Webhooks aren't conversational. They can't respond to or receive messages from users or events from Google Chat.

• If only select organizational units (OUs) in your domain have Chat apps enabled, incoming webhooks return the following error:

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

• Incoming webhooks work in direct messages, but only when all users have Chat apps enabled.

• Because Manage webhooks is only available from a web browser, webhooks must be set up from the Chat web app. Webhooks are not configurable from the Chat mobile app.