G Suite

Creating asynchronous bot requests in Hangouts Chat

Hangouts Chat bots can do many things, including providing alerts or notifications—messages that are not dependent on users initiating the conversation. In our previous DevByte, we explained the Hangouts Chat bot framework, as well as how to build a bot that responds synchronously to a user message. Today, we walk you through how to build a bot that uses asynchronous requests to notify a user.

An asynchronous request is where a bot acts based on information from another application. This enables an internal service to message you when your long-running job completes, or when a server has just gone down. 

In this video, we demonstrate how alerts and notifications are "out-of-band" messages, which means they can come in at any time (and not only as a response to a user message). The Hangouts Chat bot framework provides two ways to send asynchronous messages to a room or as a direct message (DM): the HTTP-based REST API and “incoming webhooks.”

1. Using the HTTP-based REST API to deliver asynchronous messages

First, you’ll need a bot. Then, to enable that bot to send asynchronous messages, you’ll need to use the REST API. First, you have to create a Google service account, which essentially creates a special sort of account that allows the bot to perform special actions, like initiating messages.

Now that you’re set up, putting the pieces together is pretty easy. Here’s a brief example using Python that uses the API to asynchronously send a message to a space. To start, you setup the service account with your credentials. Then, initialize the bot, provide a space and message, and send it off.

  from apiclient import discovery
from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials

SCOPES = 'https://www.googleapis.com/auth/chat.bot'
creds = ServiceAccountCredentials.from_json_keyfile_name(
        'svc_acct.json', SCOPES)
CHAT = discovery.build('chat', 'v1', http=creds.authorize(Http()))

room = 'spaces/<ROOM-or-DM>'
message = {'text': 'Hello world!'}
CHAT.spaces().messages().create(parent=room, body=message).execute()

2. Using webhooks to create quick entry points for asynchronous messages

If you have an existing application, such as a monitoring service or your Customer Relationship Management (CRM) system, that you want to enable to send alerts or notifications as Chat messages, you can also use incoming webhooks. This approach allows you to send messages into any space without configuring a full bot. Webhooks also allow you to integrate your custom workflows, so that your team, for example, can receive a message when a new customer is added to the CRM.

Incoming webhooks are simply endpoints that you send an HTTP POST request to, you can send messages to the space using whatever method you like.. To show you how, here are two examples.

First, a Python snippet that uses an incoming webhook to communicate into a space asynchronously. You’ll notice the message creation is simple, and all you need is the URL of that webhook to POST a request to.

  import requests
import json

URL = <INCOMING-WEBHOOK>
message = {'text': 'Hello world!'}
requests.post(URL, data = json.dumps(message))

Second, you can even use curl to send a message to a Hangouts Chat space from the command-line, which can improve a batch script you might have:

curl \
    -X POST \
    -H 'Content-Type: application/json' \
    'https://chat.googleapis.com/...&thread_key=T12345' \
    -d '{"text": "Hello!"}'

To get started with asynchronous messages, take a look at the Hangouts Chat developer documentation, especially the specific pages linked to above. Or read more in this post. Happy botting!