Develop bot integrations with the Hangouts Chat platform and API

February 28, 2018

Link copied to clipboard
Posted by Mike Sorvillo, Product Manager, Hangouts Chat and Wesley Chun (@wescpy), Developer Advocate, G Suite

You might have seen that we announced new features in G Suite to help teams transform how they work, including Hangouts Chat, a new messaging platform for enterprise collaboration on web and mobile. Perhaps more interesting is that starting today you'll be able to craft your own bot integrations using the Hangouts Chat developer platform and API.

Now, you can create bots to streamline work—automate manual tasks or give your users new ways to connect with your application, all with commands issued from chat rooms or direct messages (DMs). Here are some ideas you might consider:

  • Create a bot that can complete simple tasks or query for information
  • Create a bot that can post asynchronous notifications in any room or DM
  • Use interactive UI cards to bring your message responses to life
  • Use Google Apps Script to create custom bots for your colleagues or organization

For example, a bot can take a location from a user, look it up using the Google Maps API, and display the resulting map right within the same message thread in Hangouts Chat. The bot output you see in the image below is generated from the Apps Script bot integration. It returns the JSON payload just below the same image shown on this page in the documentation.

When messages are sent to an Apps Script bot, the onMessage() function is called and passed an event object. The code below extracts the bot name as well as the location requested by the user. The location is then passed to Google Maps to create the static map as well as an openLink URL that takes the user directly to Google Maps if either the map or "Open in Google Maps" link is clicked.

function onMessage(e) {
  var bot = e.message.annotations[0].userMention.user.displayName;
  var loc = encodeURI(e.message.text.substring(bot.length+2));
  var mapClick = {
    "openLink": {
      "url": "" + loc

  return {
    // see JSON payload in the documentation link above

Finally, this function returns everything Hangouts Chat needs to render a UI card assuming the appropriate links, data and Google Maps API key were added to the response JSON payload. It may be surprising, but this is the entire bot and follows this common formula: get the user request, collate the results and respond back to the user.

When results are returned immediately like this, it's known as a synchronous bot. Using the API isn't necessary because you're just responding to the HTTP request. If your bot requires additional processing time or must execute a workflow out-of-band, return immediately then post an asynchronous response when the background jobs have completed with data to return. Learn more about bot implementation, its workflow, as well as synchronous vs. asynchronous responses.

Developers are not constrained to using Apps Script, although it is perhaps one of the easiest ways to create and deploy bots. Overall, you can write and host bots on a variety of platforms:

No longer are chat rooms just for conversations. With feature-rich, intelligent bots, users can automate tasks, get critical information or do other heavy-lifting with a simple message. We're excited at the possibilities that await both developers and G Suite users on the new Hangouts Chat platform and API.