[MUSIC PLAYING]
WESLEY CHUN: Hey there and welcome to another episode
of "The G Suite Dev Show."
I'm your host, Wesley Chun.
As you can see, we're going to talk
about sending alerts and notifications in Hangouts Chat.
But when would you want to do this and why?
You also have to ask how to do this
and where you can do it from.
Well, the hint is in the subtitle,
but these answers and more coming up.
Chances are that, if you're here,
you've probably already used the Hangouts Chat bot framework
and built bots, which take user requests
and respond synchronously.
Well, if not, check out the other video
first, which introduces the framework
and how to write bots.
OK, so we get bots generally respond in a synchronous way,
meaning that, when someone talks to a bot, in a direct message
or @mentions a bot in a chat room,
the Hangouts Chat service forwards that message
via HTTP posts to your bot.
Your bot does what it needs to do
and sends its reply back in the HTTP response, which
is then rendered in the chat room or direct message.
By the way, we refer to rooms and DMs more generically
as spaces.
These asynchronous replies correspond to user requests.
But what if you need to know when a long-running background
job has completed, or a train or a bus running late
is arriving soon?
Or perhaps, you want an alert, when a server has gone down
or when a new customer is added to the corporate CRM.
Well, these are situations where you need out-of-band messages,
messages which are sent asynchronously by your bot
or other notification apps.
The Hangouts Chat bot framework supports asynchronous messages
just for these types of use cases.
Asynchronous messages can also be sent
to specific threads of context.
Well, more on this later.
If you take a closer look at the diagram,
recognize that a bot or some monitoring app
is trying to send a message to a space.
So it needs to initiate a connection to Hangouts Chat,
meaning some level of authorization is needed.
Well, Hangouts Chat will then send the notification
to the requested space.
There are two ways to connect to Hangouts Chat.
The first is for bots, and those are service accounts.
A service account is a special type of Google account that is
tied to your app-- in this case, a bot--
instead of a user.
The bot assumes the identity of the service account
to call the Hangouts Chat API.
The second way is for non-bot apps,
and that is to use incoming webhooks.
This entails calling a specific URL, with built-in credentials,
to communicate to a space.
Let's tackle these one at a time.
Here is a short Python script representing
part of your overall bot application.
Beyond the imports, this script starts with the OAuth scope
for Hangouts Chat.
This is the only permission needed
to send a message into a space.
Merge that scope, along with the service account client
ID of the API project, to generate the credentials needed
to create an API endpoint.
You can then use that endpoint to send messages to a space.
Now keep in mind that this is just part of your bot.
The code you don't see here is your custom workflow,
like pulling information from a database,
calling external APIs, or whatever
processing you want to do before you send
that message into the space.
Anytime you see permission scopes in code,
it's a pretty strong indication you're calling an API.
What makes Hangouts Chat different from other Google
APIs is that bots must have a service account to call
the API, because it's code that is never
executed on behalf of a user.
The Python script we just saw was
an example of creating messages in a space.
Now, more generally, the API can do all CRUD operations
on messages, as you see from the API docs here.
However, the API also has additional features
to give bots more context, such as getting info
on spaces or members in spaces.
All right, well, that's the first asynchronous technique.
Now along with the API, Hangouts Chat
also supports incoming webhooks as a convenient way
of sending asynchronous messages into spaces
that are not from a bot.
They're great for one-off alerts,
like the ones I mentioned earlier--
the server going down or a new customer in the house.
All right, but it doesn't always have to be something urgent.
For example, it could be used for standard or timed
notifications.
In other words, incoming webhooks
are a quick and easy way to integrate
any of your custom workflows.
Now, the way you use incoming webhooks
is to go to the space for which you want the webhook,
pull down the selector bar at the top,
then choose Configure Webhooks.
You'll see the configuration dialog pop up, like this one,
featuring one webhook.
Now you can have more than one, because this room may
get notified from different sources, right?
So you click Add Webhook to add a new one, provide a webhook
name, and an optional avatar--
otherwise, you get the generic webhook icon--
then click Save.
Then you click on the Copy icon to copy that hook
into your clipboard and then use that link in your notification
app.
Now these URLs are fairly long, since they
have built-in authorization.
Keep them safe, because like API keys,
anyone can use them to post into that space
if they're somehow exposed.
Incoming webhook messages can come from a variety of sources,
like this Python script, which can do anything from network
monitoring to CRM triggers.
An incoming webhook doesn't even have to be code.
You can even send an alert into a space
with just a cURL command, like what you see here.
Now here's a snippet of an incoming webhook
I wrote for my team using AppScript and a timed
trigger, which is similar to a UNIX cron job.
This reminds them to send out their weekly TPS reports,
as well as submit their timesheets,
so they can get paid.
Now one caveat is that async messages
can be numerous and disruptive when every new message spawns
a new thread.
Well, Hangouts Chat has an innovative feature
using what are known as thread keys, which
direct all async messages to the same threads,
grouping related notifications together,
like what you see here, and reducing the clutter.
Thread keys are supported by both the API and incoming
webhooks.
And here's an example of its use from our cURL example.
All subsequent async messages sent to the same thread key
go to the same conversation.
See the thread keys guide in the docs for more information.
Are you ready for your next steps?
Well, check out the first link to read more
about using the REST API.
The next resource is all about incoming webhooks.
And finally, we've got the Python incoming web Quickstart
sample ready for you to try out.
Now what should you do with your newfound knowledge?
Well, you've probably already written a bot,
so add the use of the API, so your bot can send messages
asynchronously into a space, for any of the reasons
we mentioned earlier, like completion of a background job.
For incoming webhooks, start the Quickstart,
and then build something on top of that
to send alerts or other notifications
into a relevant space, such as the weekly reminder shown
earlier.
Well, with this new tool under your belt,
you're now ready to build bots that
can send both synchronous and asynchronous messages.
Not all bots can respond synchronously,
and there will be situations where async
is the right tool for the job.
All right, be sure to subscribe to our channel
and tune into another episode soon.
This is Wesley Chun from Google, and we'll see you upstairs
in the G Suite.
[MUSIC PLAYING]