Build a Google Chat app as a webhook (original) (raw)

This page describes how to set up a webhook to send asynchronous messages into a Chat space using external triggers. For example, you can configure a monitoring application to notify on-call personnel on Chat when a server goes down. To send a synchronous message with a Chat app, seeSend a message.

With this type of architecture design, users can't interact with the webhook or the connected external application because communication is one-way. Webhooks aren't conversational. They can't respond to or receive messages from users orChat app interaction events. To respond to messages,build a Chat appinstead of a webhook.

While a webhook isn't technically a Chat app—webhooks connect applications using standard HTTP requests—this page refers to it as a Chat app for simplification. Each webhook only works in the Chat space in which it's registered. Incoming webhooks work in direct messages, but only when all users haveChat apps enabled. You can't publish webhooks to the Google Workspace Marketplace.

The following diagram shows the architecture of a webhook connected to Chat:

Architecture for incoming webhooks to send asynchronous messages to Chat.

In the preceding diagram, a Chat app has the following flow of information:

  1. The Chat app logic receives information from external third-party services, such as a project management system or a ticketing tool.
  2. The Chat app logic is hosted in either a cloud or on-premises system that can send messages by using a webhook URL to a specific Chat space.
  3. Users can receive messages from the Chat app in that specific Chat space, but are unable to interact with the Chat app.

Prerequisites

Node.js

Python

pip install httplib2

Java

Apps Script

Create a webhook

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

Register the incoming webhook

  1. In a browser, openChat. Webhooks aren't configurable from the Chat mobile app.
  2. Go to the space where you want to add a webhook.
  3. Next to the space title, click the expand more arrow, and then click Apps & integrations.
  4. Click Add webhooks.
  5. In the Name field, enter Quickstart Webhook.
  6. In the Avatar URL field, enterhttps://developers.google.com/chat/images/chat-product-icon.png.
  7. Click Save.
  8. To copy the webhook URL, clickMore, and then clickCopy link.
    The webhook URL contains two parameters: key, a common value shared between webhooks, and token which is a unique value that must be kept secret to preserve the security of your webhook.

Write the webhook script

The example webhook script sends a message to the space in which the webhook is registered by sending a POST request to the webhook URL. The Chat API responds with an instance ofMessage.

Select a language to learn how to create a webhook script:

Node.js

  1. In your working directory, create a file named index.js.
  2. In index.js, paste the following code:
  3. Replace the value for the url variable with the webhook URL that you copied when you registered the webhook.

Python

  1. In your working directory, create a file named quickstart.py.
  2. In quickstart.py, paste the following code:
  3. Replace the value for the url variable with the webhook URL that you copied when you registered the webhook.

Java

  1. In your working directory, create a file named pom.xml.
  2. In pom.xml, copy and paste the following:
  3. In your working directory, create the following directory structuresrc/main/java.
  4. In the src/main/java directory, create a file named App.java.
  5. In App.java, paste the following code:
  6. Replace the value for the URL variable with the webhook URL that you copied when you registered the webhook.

Apps Script

  1. In a browser, go toApps Script.
  2. Click New Project
  3. Paste the following code:
  4. Replace the value for the url variable with the webhook URL that you copied when you registered the webhook.

Run the webhook script

In a CLI, run the script:

Node.js

  node index.js

Python

  python3 quickstart.py

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script

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

Start or reply to a message thread

  1. Specifyspaces.messages.thread.threadKeyas part of the message request body. Depending on whether you're starting or replying to a thread, use the following values for threadKey:
    • If starting a thread, set the threadKey to an arbitrary string, but make a note of this value to post a reply to the thread.
    • If replying to a thread, specify the threadKey that was set when the thread was started. For example, to post a reply to the thread where the initial message used MY-THREAD, set MY-THREAD.
  2. Define the thread behavior if the specified threadKey isn't found:
    • Reply to a thread or start a new thread. Add themessageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD parameter to the webhook URL. Passing this URL parameter causes Chat to look for an existing thread using the specified threadKey. If one is found, then the message posts as a reply to that thread. If none is found, then the message starts a new thread corresponding to thatthreadKey.
    • Reply to a thread or do nothing. Add themessageReplyOption=REPLY_MESSAGE_OR_FAIL parameter to the webhook URL. Passing this URL parameter causes Chat to look for an existing thread using the specified threadKey. If one is found, then the message posts as a reply to that thread. If none is found, then the message isn't sent.
      To learn more, see messageReplyOption.

The following code sample starts or replies to a message thread:

Node.js

Python

Java

Apps Script

Handle errors

Webhook requests can fail for a variety of reasons, including:

When building your webhook, you should appropriately handle errors by:

The Google Chat API returns errors as agoogle.rpc.Status, which includes an HTTP error code that indicates the type of error that was encountered: a client error (400 series) or a server error (500 series). To review all HTTP mappings, seegoogle.rpc.Code.

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

To learn how to interpret HTTP status codes and handle errors, seeErrors.

Limitations and considerations