Choosing a bot style

There are a number of different approaches to creating a bot for Hangouts Chat. Which is the most appropriate for your bot depends on what your bot will do, along with some technical constraints that might apply to your situation.

Interaction pattern

Start by identifying a suitable interaction pattern for your bot. Here's a set of interaction patterns, in increasing order of complexity:

Pattern Description
Notifications only Bots in this category are not conversational; they simply inject messages (alarms, state change notifications, etc.) into a space.
Fetching data with simple commands These bots typically have a one-in, one-out message pattern. A message to the bot triggers some kind of lookup and a response to send the resulting data into the space.
Starting external processes with simple commands The conversational complexity of these bots depend on the nature of the process they initiate. Typically these respond synchronously to a command, but also inject asynchronous updates as a result of process execution.
Smart agents that combine internal systems together These are the most complex of bots, often involving NLP and integration with multiple external systems.

Endpoint type

Depending on the usage pattern and your deployment needs, you also need to decide on an endpoint type. Here's a summary of endpoint types and their suggested uses:

Endpoint type Pub? Application Authentication
Incoming webhook Not a true endpoint, but a simple way to build one-off notifiers that are "hardwired" to a specific chat room. None
Apps Script Straightforward way to build a simple bot for yourself, team, or domain. None
Synchronous HTTP Easy way to build a bot that you want the world to use, if the bot never needs to respond asynchronously. None
Asynchronous HTTP Standard way to build a bot that you want the world to use. Service account
Cloud Pub/sub Best for connecting to an internal system that is behind a firewall. Service account

Additional considerations

This section lists the main things you should consider when defining how your bot will work with Hangouts Chat. These are described in detail in following sections.


There may be security mechanisms you need to accommodate when connecting your bot implementation to Hangouts Chat:

  • Is your bot's implementation behind a firewall? Use a Cloud Pub/Sub endpoint.
  • Does your bot's HTTP endpoint use OAuth?
  • Does your bot's implementation need to access protected resources? You'll need to set up third-party authentication.
  • Will your bot send unsolicited messages? Your bot will need a service account.


If you want to publish your bot in the G Suite Marketplace, you will need to use an HTTP or Cloud Pub/Sub endpoint.

If you just want a quick bot for you or your workgroup to use, and you're not using an existing remote implementation, you can write the bot directly in Apps Script. This doesn't require any authentication (since Apps Scripts always run in the context of an authorized user).

Service accounts

Bots that asynchronously inject messages do so using the Hangouts Chat REST API. To make calls the this API, bots must authenticate using a service account.

Some bots don't fall into this category:

  • Apps Script bots
  • Incoming webhooks notifiers
  • Simple, synchronous HTTP bots that only send information back in the HTTP POST response.

Simple synchronous HTTP bots

Other types of bots

All other bots, unless they are implemented in Apps Script, need to use service accounts so that they can authenticate their inbound messages.

System architectures

This section describes several of the key architectures used to implement chat bots for Hangouts Chat, using the endpoint types described above.

Simple notifier

The simple notifier is not a conversational chat bot, and doesn't support messages from users to the bot. It simply allows an application to inject messages into a chat room.

This pattern uses an incoming webhook to inject messages into the room. It does not use a developer console project or a service account, so it cannot be published and added to various rooms. However, for one-off notifiers built for a single chat room, it is quick to implement.

Basic synchronous HTTP

This is the standard architecture for a one-in, one-out conversational bot. It doesn't use a service account; this is because its responses are always carried by the HTTP response to the originating HTTP POST message.

Many simple bots can be implemented using this architecture, and they can be registered so that they can be discovered and added to other chat rooms.

Asynchronous HTTP

This pattern allows HTTP-based bots to respond asynchronously to user messages or other triggers.

This pattern is slightly more complex to set up than the synchronous version, but is adaptable to a large range of app requirements.

Cloud Pub/Sub

This pattern is well suited to systems where the bot implementation is behind a firewall. Instead of Hangouts Chat attempting to traverse the firewall, part of the implementation is an event subscriber and "pulls" the messages from the Pub/Sub topic.

Note that there is no mechanism for responding through the Pub/Sub mechanism. The bot must respond asynchronously in the same way as the async HTTP pattern.

Send feedback about...

Hangouts Chat API
Hangouts Chat API
Need help? Visit our support page.