Tag Archives: Google APIs

Hangouts Chat alerts & notifications… with asynchronous messages

Posted by Wesley Chun (@wescpy), Developer Advocate, G Suite

While most chatbots respond to user requests in a synchronous way, there are scenarios when bots don't perform actions based on an explicit user request, such as for alerts or notifications. In today's DevByte video, I'm going to show you how to send messages asynchronously to rooms or direct messages (DMs) in Hangouts Chat, the team collaboration and communication tool in G Suite.

What comes to mind when you think of a bot in a chat room? Perhaps a user wants the last quarter's European sales numbers, or maybe, they want to look up local weather or the next movie showtime. Assuming there's a bot for whatever the request is, a user will either send a direct message (DM) to that bot or @mention the bot from within a chat room. The bot then fields the request (sent to it by the Hangouts Chat service), performs any necessary magic, and responds back to the user in that "space," the generic nomenclature for a room or DM.

Our previous DevByte video for the Hangouts Chat bot framework shows developers what bots and the framework are all about as well as how to build one of these types of bots, in both Python and JavaScript. However, recognize that these bots are responding synchronously to a user request. This doesn't suffice when users want to be notified when a long-running background job has completed, when a late bus or train will be arriving soon, or when one of their servers has just gone down. Recognize that such alerts can come from a bot but also perhaps a monitoring application. In the latest episode of the G Suite Dev Show, learn how to integrate this functionality in either type of application.

From the video, you can see that alerts and notifications are "out-of-band" messages, meaning they can come in at any time. The Hangouts Chat bot framework provides several ways to send asynchronous messages to a room or DM, generically referred to as a "space." The first is the HTTP-based REST API. The other way is using what are known as "incoming webhooks."

The REST API is used by bots to send messages into a space. Since a bot will never be a human user, a Google service account is required. Once you create a service account for your Hangouts Chat bot in the developers console, you can download its credentials needed to communicate with the API. Below is a short Python sample snippet that uses the API to send a message asynchronously to a space.

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()

The alternative to using the API with services accounts is the concept of incoming webhooks. Webhooks are a quick and easy way to send messages into any room or DM without configuring a full bot, i.e., monitoring apps. Webhooks also allow you to integrate your custom workflows, such as when a new customer is added to the corporate CRM (customer relationship management system), as well as others mentioned above. Below is a Python snippet that uses an incoming webhook to communicate into a space asynchronously.

import requests
import json

URL = 'https://chat.googleapis.com/...&thread_key=T12345'
message = {'text': 'Hello world!'}
requests.post(URL, data = json.dumps(message))

Since incoming webhooks are merely endpoints you HTTP POST to, you can even use curl to send a message to a Hangouts Chat space from the command-line:

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

To get started, take a look at the Hangouts Chat developer documentation, especially the specific pages linked to above. We hope this video helps you take your bot development skills to the next level by showing you how to send messages to the Hangouts Chat service asynchronously.

Developing bots for Hangouts Chat

Posted by Wesley Chun (@wescpy), Developer Advocate, G Suite

We recently introduced Hangouts Chat to general availability. This next-generation messaging platform gives G Suite users a new place to communicate and to collaborate in teams. It features archive & search, tighter G Suite integration, and the ability to create separate, threaded chat rooms. The key new feature for developers is a bot framework and API. Whether it's to automate common tasks, query for information, or perform other heavy-lifting, bots can really transform the way we work.

In addition to plain text replies, Hangouts Chat can also display bot responses with richer user interfaces (UIs) called cards which can render header information, structured data, images, links, buttons, etc. Furthermore, users can interact with these components, potentially updating the displayed information. In this latest episode of the G Suite Dev Show, developers learn how to create a bot that features an updating interactive card.

As you can see in the video, the most important thing when bots receive a message is to determine the event type and take the appropriate action. For example, a bot will perform any desired "paperwork" when it is added to or removed from a room or direct message (DM), generically referred to as a "space" in the vernacular.

Receiving an ordinary message sent by users is the most likely scenario; most bots do "their thing" here in serving the request. The last event type occurs when a user clicks on an interactive card. Similar to receiving a standard message, a bot performs its requisite work, including possibly updating the card itself. Below is some pseudocode summarizing these four event types and represents what a bot would likely do depending on the event type:

function processEvent(req, rsp) {
var event = req.body; // event type received
var message; // JSON response message

if (event.type == 'REMOVED_FROM_SPACE') {
// no response as bot removed from room
return;

} else if (event.type == 'ADDED_TO_SPACE') {
// bot added to room; send welcome message
message = {text: 'Thanks for adding me!'};

} else if (event.type == 'MESSAGE') {
// message received during normal operation
message = responseForMsg(event.message.text);

} else if (event.type == 'CARD_CLICKED') {
// user-click on card UI
var action = event.action;
message = responseForClick(
action.actionMethodName, action.parameters);
}

rsp.send(message);
};

The bot pseudocode as well as the bot featured in the video respond synchronously. Bots performing more time-consuming operations or those issuing out-of-band notifications, can send messages to spaces in an asynchronous way. This includes messages such as job-completed notifications, alerts if a server goes down, and pings to the Sales team when a new lead is added to the CRM (Customer Relationship Management) system.

Hangouts Chat supports more than JavaScript or Python and Google Apps Script or Google App Engine. While using JavaScript running on Apps Script is one of the quickest and simplest ways to get a bot online within your organization, it can easily be ported to Node.js for a wider variety of hosting options. Similarly, App Engine allows for more scalability and supports additional languages (Java, PHP, Go, and more) beyond Python. The bot can also be ported to Flask for more hosting options. One key takeaway is the flexibility of the platform: developers can use any language, any stack, or any cloud to create and host their bot implementations. Bots only need to be able to accept HTTP POST requests coming from the Hangouts Chat service to function.

At Google I/O 2018 last week, the Hangouts Chat team leads and I delivered a longer, higher-level overview of the bot framework. This comprehensive tour of the framework includes numerous live demos of sample bots as well as in a variety of languages and platforms. Check out our ~40-minute session below.

To help you get started, check out the bot framework launch post. Also take a look at this post for a deeper dive into the Python App Engine version of the vote bot featured in the video. To learn more about developing bots for Hangouts Chat, review the concepts guides as well as the "how to" for creating bots. You can build bots for your organization, your customers, or for the world. We look forward to all the exciting bots you're going to build!

Making progress (bars) with Slides Add-ons

Originally posted on the G Suite Developers Blog by Wesley Chun (@wescpy), Developer Advocate and Grant Timmerman, Developer Programs Engineer, G Suite

We recently introduced Google Slides Add-ons so developers can add functionality from their apps to ours. Here are examples of Slides Add-ons that some of our partners have already built—remember, you can also add functionality to other apps outside of Slides, like Docs, Sheets, Gmail and more.

When it comes to Slides, if your users are delivering a presentation or watching one, sometimes it's good to know how far along you are in the deck. Wouldn't it be great if Slides featured progress bars?

In the latest episode of the G Suite Dev Show, G Suite engineer Grant Timmerman and I show you how to do exactly that—implement simple progress bars using a Slides Add-on.

Using Google Apps Script, we craft this add-on which lets users turn on or hide progress bars in their presentations. The progress bars are represented as appropriately-sized rectangles at the bottom of slide pages. Here's a snippet of code for createBars(), which adds the rectangle for each slide.

var BAR_ID = 'PROGRESS_BAR_ID';
var BAR_HEIGHT = 10; // px
var presentation = SlidesApp.getActivePresentation();

function createBars() {
var slides = presentation.getSlides();
deleteBars();
for (var i = 0; i < slides.length; ++i) {
var ratioComplete = (i / (slides.length - 1));
var x = 0;
var y = presentation.getPageHeight() - BAR_HEIGHT;
var barWidth = presentation.getPageWidth() * ratioComplete;
if (barWidth > 0) {
var bar = slides[i].insertShape(SlidesApp.ShapeType.RECTANGLE,
x, y, barWidth, BAR_HEIGHT);
bar.getBorder().setTransparent();
bar.setLinkUrl(BAR_ID);
}
}
}

To learn more about this sample and see all of the code, check out the Google Slides Add-on Quickstart. This is just one example of what you can build using Apps Script and add-ons; here's another example where you can create a slide presentation from a collection of images using a Slides Add-on.

If you want to learn more about Apps Script, check out the video library or view more examples of programmatically accessing Google Slides here. To learn about using Apps Script to create other add-ons, check out this page in the docs.

Make progress (bars) in presentations with Slides Add-ons



We recently introduced Google Slides Add-ons so developers can add functionality from their apps to ours. Here are examples of Slides Add-ons that some of our partners have already built—remember, you can also add functionality to other apps outside of Slides, like Docs, Sheets, Gmail and more.

When it comes to Slides, if your users are delivering a presentation or watching one, sometimes it's good to know how far along you are in the deck. Wouldn't it be great if Slides featured progress bars?
In the latest episode of the G Suite Dev Show, G Suite engineer Grant Timmerman and I show you how to do exactly that—implement simple progress bars using a Slides Add-on.

Using Google Apps Script, we craft this add-on which lets users turn on or hide progress bars in their presentations. The progress bars are represented as appropriately-sized rectangles at the bottom of slide pages. Here's a snippet of code for createBars(), which adds the rectangle for each slide.

var BAR_ID = 'PROGRESS_BAR_ID';
var BAR_HEIGHT = 10; // px
var presentation = SlidesApp.getActivePresentation();

function createBars() {
var slides = presentation.getSlides();
deleteBars();
for (var i = 0; i < slides.length; ++i) {
var ratioComplete = (i / (slides.length - 1));
var x = 0;
var y = presentation.getPageHeight() - BAR_HEIGHT;
var barWidth = presentation.getPageWidth() * ratioComplete;
if (barWidth > 0) {
var bar = slides[i].insertShape(SlidesApp.ShapeType.RECTANGLE,
x, y, barWidth, BAR_HEIGHT);
bar.getBorder().setTransparent();
bar.setLinkUrl(BAR_ID);
}
}
}

To learn more about this sample and see all of the code, check out the Google Slides Add-on Quickstart. This is just one example of what you can build using Apps Script and add-ons; here’s another example where you can create a slide presentation from a collection of images using a Slides Add-on.

If you want to learn more about Apps Script, check out the video library or view more examples of programmatically accessing Google Slides here. To learn about using Apps Script to create other add-ons, check out this page in the docs.

Develop bot integrations with the Hangouts Chat platform and API

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": "https://google.com/maps/search/?api=1&query=" + 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.

Develop bot integrations with the Hangouts Chat platform and API



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": "https://google.com/maps/search/?api=1&query=" + 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.

Gmail Add-ons framework now available to all developers

Originally posted by Wesley Chun, G Suite Developer Advocate on the G Suite Blog

Email remains at the heart of how companies operate. That's why earlier this year, we previewed Gmail Add-ons—a way to help businesses speed up workflows. Since then, we've seen partners build awesome applications, and beginning today, we're extending the Gmail add-on preview to include all developers. Now anyone can start building a Gmail add-on.

Gmail Add-ons let you integrate your app into Gmail and extend Gmail to handle quick actions.

They are built using native UI context cards that can include simple text dialogs, images, links, buttons and forms. The add-on appears when relevant, and the user is just a click away from your app's rich and integrated functionality.

Gmail Add-ons are easy to create. You only have to write code once for your add-on to work on both web and mobile, and you can choose from a rich palette of widgets to craft a custom UI. Create an add-on that contextually surfaces cards based on the content of a message. Check out this video to see how we created an add-on to collate email receipts and expedite expense reporting.

Per the video, you can see that there are three components to the app's core functionality. The first component is getContextualAddOn()—this is the entry point for all Gmail Add-ons where data is compiled to build the card and render it within the Gmail UI. Since the add-on is processing expense reports from email receipts in your inbox, the createExpensesCard()parses the relevant data from the message and presents them in a form so your users can confirm or update values before submitting. Finally, submitForm()takes the data and writes a new row in an "expenses" spreadsheet in Google Sheets, which you can edit and tweak, and submit for approval to your boss.

Check out the documentation to get started with Gmail Add-ons, or if you want to see what it's like to build an add-on, go to the codelab to build ExpenseItstep-by-step. While you can't publish your add-on just yet, you can fill out this form to get notified when publishing is opened. We can't wait to see what Gmail Add-ons you build!

Gmail add-ons framework now available to all developers



Email remains at the heart of how companies operate. That’s why earlier this year, we previewed Gmail Add-ons—a way to help businesses speed up workflows. Since then, we’ve seen partners build awesome applications, and beginning today, we’re extending the Gmail add-on preview to include all developers. Now anyone can start building a Gmail add-on.

Gmail Add-ons let you integrate your app into Gmail and extend Gmail to handle quick actions. They are built using native UI context cards that can include simple text dialogs, images, links, buttons and forms. The add-on appears when relevant, and the user is just a click away from your app's rich and integrated functionality.

Gmail Add-ons are easy to create. You only have to write code once for your add-on to work on both web and mobile, and you can choose from a rich palette of widgets to craft a custom UI. Create an add-on that contextually surfaces cards based on the content of a message. Check out this video to see how we created an add-on to collate email receipts and expedite expense reporting.

Per the video, you can see that there are three components to the app’s core functionality. The first component is getContextualAddOn()—this is the entry point for all Gmail Add-ons where data is compiled to build the card and render it within the Gmail UI. Since the add-on is processing expense reports from email receipts in your inbox, the createExpensesCard()parses the relevant data from the message and presents them in a form so your users can confirm or update values before submitting. Finally, submitForm() takes the data and writes a new row in an “expenses” spreadsheet in Google Sheets, which you can edit and tweak, and submit for approval to your boss.

Check out the documentation to get started with Gmail Add-ons, or if you want to see what it's like to build an add-on, go to the codelab to build ExpenseIt step-by-step. While you can't publish your add-on just yet, you can fill out this form to get notified when publishing is opened. We can’t wait to see what Gmail Add-ons you build!

Generating Google Slides from images using Apps Script



Today, we announced a collection of exciting new features in Google Slides—among these is support for Google Apps Script. Now you can use Apps Script for Slides to programmatically create and modify Slides, plus customize menus, dialog boxes and sidebars in the user interface.

Programming presentations with Apps Script

Presentations have come a long way—from casting hand shadows over fires in caves to advances in lighting technology (magic lanterns) to, eventually, (in)famous 35mm slide shows of your Uncle Bob's endless summer vacation. More recently, we have presentation software—like Slides—and developers have been able to write applications to create or update them. This is made even easier with the new Apps Script support for Google Slides. In the latest G Suite Dev Show episode, we demo this new service, walking you through a short example that automatically creates a slideshow from a collection of images.
To keep things simple, the chosen images are already available online, accessible by URL. For each image, a new (blank) slide is added then the image is inserted. The key to this script are two lines of JavaScript (given an existing presentation and a link to each image):

var slide = presentation.appendSlide(SlidesApp.PredefinedLayout.BLANK);
var image = slide.insertImage(link);

The first line of code adds a new slide while the other inserts an image on the new slide. Both lines are repeated for each image in the collection. While this initial, rudimentary solution works, the slide presentation created doesn't exactly fit the bill. It turns out that adding a few more lines make the application much more useful. See the video for all the details.

Getting started 

To get started, check the documentation to learn more about Apps Scripts for Slides, or check out the Translate and Progress Bar sample Add-ons. If you want to dig deeper into the code sample from our video, take a look at the corresponding tutorial. And, if you love watching videos, check out our Apps Script video library or other G Suite Dev Show episodes. If you wish to build applications with Slides outside of the Apps Script environment and want to use your own development tools, you can do so with the Slides (REST) API—check out its documentation and video library.

With all these options, we look forward to seeing the applications you build with Google Slides!

Monitoring the Apps Script issue tracker…with Apps Script

Originally posted by Paul McReynolds, Product Manager (@pauljmcr), Apps Script and Wesley Chun (@wescpy), Developer Advocate, G Suite on the G Suite Developers Blog

Apps Script is just as popular inside Google as it is among external users and developers. In fact, there are more than 70,000 weekly active scripts written by thousands of Googlers. One of our many uses for Apps Script at Google is to automate and monitor our internal issue tracker.

Your business depends on Apps Script...so does ours

In spring of this year, we migratedour G Suite issue trackers to a new system based on our internal tracker. This carries a lot of benefits, including improving our ability to track how issues reported from outside of Google relate to bugs and features we're working on internally. We also have an internal Apps Script API that talks to our issue tracker, which we can now use to work with issues reported from outside of Google.

As soon as the migration was finished, we put Apps Script to work monitoring…itself. Now we have a script in place that monitors Apps Script issues as they are reported and upvoted on the public tracker. When we see an issue that's having widespread or sudden impact, the script generates an alert that we can then investigate. With the help of our large, active community of developers, and leveraging Apps Script, we're now able to identify and respond to issues more quickly.

There's no substitute for independent monitoring, and our Apps Script-based approach isn't the first or the last line of defense. Instead, this new script helps us catch anything that our monitoring systems miss by listening to what developers are saying on the tracker.

If you see something, say something

Please help us keep Apps Script humming! When you notice a problem, search the issue trackerforit and file an issue if it's new. Click the star to let us know you're affected and leave a comment with instructions to reproduce, along with any other relevant details. Those instructions and other details help us respond to the issues more effectively, so please be sure to include them.

Happy scripting!