Add dialogs and slash commands to your Google Workspace Chat bots

Posted by Charles Maxson, Developer Advocate

Developing your own custom Google Chat bot is a great way for users and teams to interact with your solutions and services both directly and within context as they collaborate in Chat. More specifically, Chat bots can be used in group conversations to streamline workflows, assist with activities in the context of discussions, and provide information and notifications in real time. Chat bots can also be used in direct messages, offering a new way to optimize workflows and personal productivity, such as managing project tasks or reporting time activity. Because use cases for bots are varied, you can consistently reach a growing audience of Chat users over time, directly where they work and uh-hum, chat.

Once you’ve identified your specific use case for your custom Chat bot, how you design the bot itself is super important. Bots that are intuitive and easy to use see better adoption and develop a more loyal following. Those that are not as fluid or approachable, or come across as confusing and complicated to use, will likely miss the mark of becoming an essential “sticky” tool even if your back end is compelling. To help you build an engaging, must-have Google Chat bot, we recently added a one-two feature punch to the Chat bot framework that allows you to build a much richer bot experience than ever before!

(Re)Introducing slash commands for Google Chat bots

The first new(er) feature that you can leverage to enhance the usability of your Chat bots are slash commands. Released a few months back, slash commands simplify the way users interact with your Chat bot, offering them a visual leading way to discover and execute your bot’s primary features. Unlike bots created prior to slash commands, where users had to learn what features a bot offered and then invoke the bot and type the command correctly to execute them, slash commands make Chat bot usage faster and help users get the most out of your bot.

Users can now simply type “/” in the message line to reveal a list of all the functions offered by the bots available to the room or direct message, and select the one to their liking to execute it. Slash commands can be invoked standalone (e.g. /help) or include user added text as parameters (e.g. /new_task review project doc ) that the developer can handle when invoked. To help make bot command discovery even simpler, the slash commands list filters matching commands once the user starts typing beyond the / (e.g. “/h” shows all commands beginning with H). This is super helpful as more and more bots are added to a room, and as more bots with slash commands are introduced by developers. Also included directly in the Slash Command UI is a description of what each command does (up to 50 characters), easing the guesswork out of learning.

Example of implementing slashbot in Google Chat

As a developer, slash commands are straightforward to implement, and daresay essential in offering a better bot experience. In fact, if you have an existing Google Chat bot you’ve built and deployed, it’s likely more than worthwhile to revise your bot to include slash commands in an updated release.

To add slash commands to any Chat bot, you will need to register your commands in the Hangouts Chat API configuration page. (e.g. https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=<?yourprojectname?>) There is a section for slash commands that allows you to provide the /name and the description the user will see, along with the important Command Id unique identifier (a number between 1-1000) that you will later need to handle these events in your code.

Example of editing slash command

When a user invokes your bot via a Slash Command, there is a slashCommand field attached to the message sent to the bot that indicates the call was initiated from a Slash Command. Remember users can still @mention your bot to call it directly by name without a / command and this helps you distinguish the difference. The message also includes the corresponding commandId for the invoked command based on what you set up in the bot configuration page, allowing you to identify the user’s requested command to execute. Finally, the message also offers additional annotations about the event and includes any argumentText supplied by the user already parsed from the command text itself.

{
...
"message": {
"slashCommand": {
"commandId": 4
},
"annotations": [
{
"length": 6,
"slashCommand": {
"type": "INVOKE",
"commandId": 4,
"bot": {
"type": "BOT",
"displayName": "Slashbot"
},
"commandName": "/debug"
},
"type": "SLASH_COMMAND"
}
],
...
"argumentText": " show code",
"text": "/debug show code",
...
}

Here is a simple example used to determine if a Slash Command was invoked by the user, and if so, runs the requested command identified by its Command Id.

function onMessage(event) {

if (event.message.slashCommand) {

switch (event.message.slashCommand.commandId) {
case 1: // Command Id 1
return { 'text': 'You called commandId 1' }

case 2: // Command Id 2
return { 'text': 'You called commandId 2' }

case 3: // Help
return { 'text': 'You asked for help' }

}
}
}

Introducing dialogs for Google Chat bots

The second part of the one-two punch of new Google Chat bots features are dialogs. This is a brand new capability being introduced to the Chat bot framework that allows developers to build user interfaces to capture inputs and parameters in a structured, reliable way. This is a tremendous step forward for bot usability because it will simplify and streamline the process of users interacting with bot commands. Now with dialogs, users can be led visually to supply inputs via prompts, versus having to rely on wrapping bot commands with natural language inputs — and hoping they correctly executed syntax the bot could decipher.

For developers, you can design UIs that are targeted to work precisely with the inputs you need users to supply your commands, without having to parse out arguments and logically infer the intent of users. In the end, dialogs will greatly expand the type of solution patterns and use cases that Chat bots can handle, as well as making the experience truly richer and more rewarding for users and developers alike.

Slashbot project notifier

Technically, Chat bot dialogs leverage the aforementioned slash commands combined with the existing Google Workspace Add-on Card framework to support the creation and handling of dialogs. To get started, you create a Slash Command that will invoke your dialog by designating it’s Slash command triggers a dialog setting to true in the Slash Command configuration process, as seen below:

Example of enabling the slash command triggers a dialog setting

Once you have configured a Slash Command to trigger a dialog, it will send an onMessage event when it’s invoked as it would before, but now it includes new details that indicate it is representing a dialog request. To handle this event you can use the example above with non-dialog Slash Command, using the commandId you can use a switch to determine what the user requested.

Designing the actual elements that the dialog renders is where you draw from the Google Workspace Add-on Card-based framework. If you’ve built a new generation of Google Workspace Add-on, this part will be familiar where you construct widgets, add headers and sections, create events, etc. In fact, you can even reuse or share some of your Add-on UIs within your Chat bots, but do note there currently is a lighter subset of elements available for bots. The benefits of using Cards allows you to build modern, consistently-styled user interfaces for your bots that doesn’t require that you get bogged down in low level details like managing tags or CSS. You can learn more about working with Cards starting here. To make building your Cards-based interfaces for Add-ons and Chat bots even easier, we have also just introduced the GWAO Card Builder tool, which employs a drag-n-drop visual designer to boost your development efforts.

Once you’ve assembled your Card’s widgets, to make it render as a dialog when invoked you must specify that its a DIALOG type within the action_response as seen stubbed out here below:

{
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"widgets": [
{
"textInput": {
"label": "Email",
"type": "SINGLE_LINE",
"name": "fieldEmail",
"hintText": "Add others using a comma separator",
...

Now with a working dialog, all there is left to do is handle user events once it’s displayed. Again this is similar to how you would handle events working with Cards within Add-ons. Your bot will receive an event that is type CARD_CLICKED with a DialogEventType set to SUBMIT_DIALOG. The actionMethodName value will let you know what element the user clicked to process the request, e.g. ‘assign’ as depicted below. The response includes the formInputs details which are the user provided inputs returned from the dialog, which you can process as your solution needs to.

{ dialogEventType: 'SUBMIT_DIALOG',
type: 'CARD_CLICKED',
action: { actionMethodName: 'assign' },
...
common:
{ hostApp: 'CHAT',
formInputs:
{ 'whotochoose-dropdown': [Object],
whotochoose: [Object],
email: [Object] },
invokedFunction: 'assign' },
isDialogEvent: true }

Once your bot is finished processing its task, it can respond back to the user in one of two ways. The first is with a simple acknowledgement (aka OK) response letting them know their action was handled correctly and close out the dialog.

{
"action_response": {
"type": "DIALOG",
"dialog_action": {
"action_status": "OK",
...

The other option is to respond with another dialog, allowing you to follow-up with a new or revised dialog useful for complex or conditional input scenarios. This is accomplished as it was originally when you called a dialog using a dialog card within an ActionResponse to get started.

{
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
...

Next Steps

To get started building Google Workspace Chat bots, or to add slash commands and dialogs to your existing Chat bots, please explore the following resources:

Evolving Google Workspace Add-ons with Alternate Runtimes


Posted by Charles Maxson, Developer Advocate

Google Workspace Add-ons offer developers a simplified, structured, and safe way of integrating your solutions right within the Google Workspace user experience, allowing you to bring the logic and data of your application right within the reach of billions of Google Workspace users. So whether your goal is to help users avoid switching context from their inbox to your application, or to easily bring in data from your solution to Google Sheets, developing your own Google Workspace Add-ons makes a lot of sense to keep users productive, engaged and focused.

While the concept of Add-ons for Google Workspace isn’t new per se, building add-ons for Google Workspace has come a long way since they were first introduced some years back. Originally designed to allow solution developers to extend our collaboration apps: Google Docs, Sheets, Forms and Slides, it’s now possible to create a single add-on project for Google Workspace that spans the entire suite, including Gmail, Drive and Calendar.

The original design created for our collaboration apps also required you to use HTML, CSS and Google Apps Script to ‘hand roll’ elements like the user interface and events, requiring a bit more do-it-yourself effort (aka code) for developers, resulting in more inconsistency across the add-on market. That has evolved as Google Workspace Add-ons adopted Card-based interfaces more recently, allowing developers to simplify and standardize add-on building by leveraging just their knowledge of Google Apps Script.

Introducing Alternate Runtimes for Google Workspace Add-ons

Today we are pleased to announce that building Google Workspace Add-ons has evolved once again, this time to offer developers an alternative to using Apps Script for building add-ons with the general availability of Alternate Runtimes for Google Workspace Add-ons. Announced via an early access program mid last year, the release of Alternate Runtimes is a major breakthrough for Google Workspace developers who want to use their own development stack: hosting, tools, languages, packages, processes, etc.

While Alternate Runtimes enables the same functionality that Apps Script does for building add-ons, the flexibility and the freedom to choose your dev environment plus the opportunity to decouple from Apps Script will likely yield greater developer productivity and performance gains for future projects. This commonly requested feature by Google Workspace solution developers has finally become a reality.

Technically, there’s a little more effort in using the Alternate Runtimes method, as Apps Script does mask much of the complexity from the developer, but it’s essentially swapping in JSON for Apps Script in rendering the Cards service-based interfaces needed to drive Google Workspace Add-ons. Learn more about getting started with Alternate Runtimes here or try the five minute Quickstart for Alternate Runtimes to see it in action.

Also note, whether you are just getting started or you are an experienced add-on builder, we have recently released the GWAO Card Builder tool that allows you to visually design the user interfaces for your Google Workspace Add-ons projects. It is a must-have for add-on developers using either Apps Script or Alternate Runtimes, enabling you to prototype and design Card UIs super fast without hassle and errors of hand coding JSON or Apps Script on your own.


Google Workspace Card Builder Design Tool

Further Introducing the Google Workspace Add-ons Cloud API

Included with this launch of Alternate Runtimes for general availability is also the debut of the Google Workspace Add-ons Cloud API, which allows you to completely forgo using Apps Script for managing Google Workspace Add-on deployments using Alternate Runtimes. Unlike using Alternate Runtimes during the beta program where you still needed to create an Apps Script project to stub out your project endpoints via the manifest file, the Google Workspace Add-ons Cloud API allows you to create and manage your add-on deployment lifecycle with a series of command line instructions.

With the Google Workspace Add-ons Cloud API you can create a deployment, install or delete a deployment, get a list of deployments, manage permissions and more. These are straightforward to use from a CLI like gcloud, which will help simplify developing and deploying Google Workspace Add-ons built via Alternate Runtimes. For documentation on how to use the new Add-ons Cloud API, refer back to the Quickstart: Create an add-on in a different coding language example.

Showcase: Alternate Runtimes in Action

While Alternate Runtimes for Google Workspace Add-ons is officially generally available as of today, a number of Google Cloud partner teams have already been working with the technology via our early adopter program. One of those Google Cloud partners, Zzapps based out of the Netherlands, has already been creating solutions using Alternate Runtimes in their work building Add-ons for customers.

We asked Riël Notermans, owner of Zzapps (and Google Developer Expert), whose teams have been developing on Google Workspace for over a decade, to share his team’s key takeaways on Alternate Runtimes. He offered not only his insights, but added a few screenshots of one of their recent projects to illustrate as well. In Riël’s own words: “Now that we can use Alternate Runtimes for Add-ons, it changes how we approach projects from start to finish. Prototyping with GSAO makes it possible for us to quickly draft an add-on’s functionality, creating trust and clearness about what we will deliver. Alternate Runtimes makes it possible to tap into our existing applications with almost no effort. We only need to create a JSON response to push a card to interact with add-ons. Our developers are able to work in their own environment, keeping our own tools and development flow. Here’s an example below using a Node.js Express server project that we used to set email signatures, adding a few routes for the card but using our existing logic. The add-on is used to control the functionality.”


Routing Add-on requests to existing logic

“Being able to update your deployment for local development for live testing, without having to create new versions constantly, drastically improves the development experience.”


Introduces advantage of instant testing of add-ons

“Because the Add-on runtimes has built-in authorization and tokens, it is really easy to safely interact with the users data without building complex backend authentication.”


Maximizing use of existing UI with Add-ons

“In the end, we still offer our users solutions for a great experience with a Google Workspace Add-on, while our developers get to use the tools and processes that make them more productive, capable and accomplished”

Creating Add-ons with Alternate Runtimes allows flexible, fast UI design

For More Information

If you want to learn more about using Alternate Runtimes for building Google Workspace Add-ons, here are some essential links for Google Workspace Add-on resources to get you started:

Google People API now supports batch mutates and searches of Contacts


Posted by Ting Huang, Software Engineer

Some time ago, we announced that the Google Contacts API was being deprecated in favor of the People API, and it is scheduled for sunset on June 15, 2021. To aid in the process of migrating from Contacts API, we are pleased to announce that we have added two sets of new endpoints for working with contacts via the People API.

First, we now have new write endpoints that allow developers to create, delete, and update multiple contacts at once. In addition, we also have new read endpoints that allow developers to search a user’s contacts using a prefix query. Both will greatly improve working with the People API, so let’s take a quick look at how you can leverage these new endpoints today.

Getting Started with the People API

Applications need to be authorized to access the API, so to get started you will need to create a project on the Google Developers Console with the People API enabled to get access to the service. If you are new to the Google APIs, you can follow the steps here to begin accessing People API.

Google profile image

Working with Batch Mutate Endpoints

Once you’re authorized, you can simply create new contacts like this (using the Google APIs Client Library for Java):

Person person = new Person();
person.setNames(ImmutableList.of(new
Name().setGivenName("John").setFamilyName("Doe")));
ContactToCreate contactToCreate = new ContactToCreate();
contactToCreate.setContactPerson(person);

BatchCreateContactsRequest request = new BatchCreateContactsRequest();
request.setContacts(ImmutableList.of(contactToCreate)).setReadMask("names");

BatchCreateContactsResponse response =
peopleService.people().batchCreateContacts(request).execute();

The scope your app needs to authorize with is https://www.googleapis.com/auth/contacts. Full documentation on the people.batchCreateContacts method is available here.

Similarly, you can update existing contacts like this:

String resourceName = "people/c12345"; // existing contact resource name
Person contactToUpdate =
peopleService
.people()
.get(resourceName)
.setPersonFields("names,emailAddresses")
.execute();
contactToUpdate.setNames(
ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));

BatchUpdateContactsRequest request = new BatchUpdateContactsRequest();
ImmutableMap<String, Person> map =
ImmutableMap.of(contactToUpdate.getResourceName(), contactToUpdate);
request.setContacts(map).setUpdateMask("names")
.setReadMask("names,emailAddresses");

BatchUpdateContactsResponse response =
peopleService.people().batchUpdateContacts(request).execute();

Full documentation on the people.batchUpdateContacts method is available here.

Working with Search Endpoints

You can search through the authenticated user’s contacts like this:

SearchResponse response = peopleService.people().searchContacts()
.setQuery("query")
.setReadMask("names,emailAddresses")
.execute();

The scope your app needs to authorize with is https://www.googleapis.com/auth/contacts or https://www.googleapis.com/auth/contacts.readonly. Full documentation on the people.searchContacts method is available here.

You can also search through the authenticated user’s “other contacts” like this:

SearchResponse response = peopleService.otherContacts().search()
.setQuery("query")
.setReadMask("names,emailAddresses")
.execute();

The scope your app needs to authorize with is https://www.googleapis.com/auth/contacts.other.readonly. Full documentation on the otherContacts.search method is available here.

Next Steps

We hope that these newly added features inspire you to create the next generation of cool web and mobile apps that delight your users and those in their circles of influence. To learn more about the People API, check out the official documentation here.

Enhancing Add-ons in Gmail with Compose-time functions

Posted by Jon Harmer, Product Manager, Google Workspace

Google Workspace Add-ons can already do lots of cool things in Gmail. In addition to providing a way to interact with the other apps that you use every day, from the right hand sidebar as you read a Gmail message, Google Workspace add-ons can also provide another integration point: when you are composing new messages or replying to existing ones. This allows Google Workspace add-ons to make it easier for you to work with multiple applications when you are working on your daily routine of reading and responding to email.

More ways of creating

Previously, the only way a developer could modify the draft of a message in Gmail was by inserting content at the user’s cursor. But we have enhanced this functionality, and now you can enable your add-on to modify the To, CC, and BCC fields, the Subject Line, and you can insert content into the top or bottom of the message the user is composing.

This opens up a number of interesting possibilities. You could use the add-on to BCC your CRM, which allows you to log that message to the appropriate CRM record. Or you could insert a footer to the message or a tag in the subject line depending on who the message is being sent to. You can even insert message templates into the top of the email and help users to compose messages in order to give them a nicer look and feel.

Enhancing Add-ons in Gmail with Compose-time functions  gif

Convenient and secure

These enhancements to Compose Actions are a new feature of Google Workspace Add-ons, which means the moment you authorize action with the feature, they will work in Gmail across mobile and web. Google Workspace admins can also easily allowlist the add-ons they want to enable for their organization.

Try Compose Actions today

Google Workspace and Gmail users can check out the Google Workspace Marketplace to find and install add-ons, with more compose actions coming soon. Developers can also consult our documentation to build their own.

Sign up for early access programs

If you want to subscribe to news & updates about the Google Workspace developer platform or sign up to be considered for any of our Early Access Programs, click here.