Extensions made easy with Watson Assistant starter kits

Photo by Sigmund on Unsplash

So you’ve seen the announcement – Watson Assistant Extensions is live! Your intelligent chatbot hopes and dreams are coming to life!

So, how can you get started? Are there any examples you can use?

Of course, we’ve got your back. Extensions starter kits are here to kickstart your journey into building extensions with Watson Assistant in just a few minutes. No prior knowledge necessary.

Follow along to see how you can:

• Create and demo a custom extension in 5 minutes
• Learn how to tame and tailor your bot to your desired flow
• Have some creative fun with your bot’s capabilities

— Notice —

Since the publishing of this blog, the MetaWeather API has gone permanently out of commission. Since the given example extension setup will no longer work end-to-end, the starter kit has been removed from our repository’s offering list.

Feel free to follow along using a different starter kit, or follow along anyway using the deprecated MetaWeather code.

Part 1: Create a Working Extension

Your First Task: Choose Your Character!

Photo by Cláudio Luiz Castro on Unsplash

Navigate to Watson Assistant’s official public GitHub repository.

You’ll see a list of (ever expanding) starter kits to choose from:

• MetaWeather — for your weather reporting needs
• HubSpot — centralize your business tools and analytics
• Zendesk Support — create service tickets directly from your bot
• Spotify — take control of your music and playlists
• ServiceNow — automate and manage your IT business services
• IBM App Connect — integrate apps and automate your workflow
• …and more to come!

Feel free to shop and poke around these choices. We’ll be showing you how it’s done using MetaWeather as an example, but choose whichever kit you would like to try — the process is the same!

NOTE — for MetaWeather and HubSpot, we have basic and advanced pairs of OpenAPI specs and actions skills available for you to use depending on your level of comfort. You can also simply use these as references to aid your learning.

Once you’ve decided, visit the chosen folder. This will give you two crucial files:

{extension}.openapi.json
{extension}.actions.json

Go ahead and save these files onto your computer.

Upload Starter Kit Files

Next, go to your Watson Assistant landing page, and you’ll see an Integrations tab on the lower left hand side. Click on the tab.

The Integrations tab can be found on the lower left menu.

Scroll down and click Build custom extension. You’ll be prompted to give a name and description to your extension.

Now it’s time to upload an OpenAPI document — this is where your {extension}.openapi.json file comes in. Upload and click through the rest of the setup. Finally, in order to link your extension to your assistant, you’ll need to click Add on your freshly created extension.

The extension creation process.

NOTE — if you chose an extension that requires a security setup, you will need to fill out the Authentication page as well, according to the instructions from the Pre-Req: Getting Auth Keys section of the extension’s README.

Next — uploading your skill file. Go to the Actions tab and click the cog icon on the top right corner. Navigate to the Upload/Download tab, select your {extension}.actions.json from your files, then click Upload. You will see some actions populate.

The skill adding process.

You’re almost done!

Configure Your Skill

The final step is to configure your extension within the uploaded skill. In order to do this, open up the Using this Starter Kit section on the starter kit specific README (i.e. if you were using MetaWeather, this section).

From the Actions tab, click on any action that you’d like to try out. You’ll see a few “missing” alerts — which is exactly what we’re going to fix. On the left hand stack of steps, find and click on those labeled with Use an extension. For each one of these, click Edit extension at the bottom.

Use the README to configure your action steps.

A window will pop up, allowing you to select your desired extension and operation for that step. You should reference the Using This Starter Kit section to fill these out – each action has a corresponding list of operations and parameters that you should populate.

Now, Time to Demo!

Check out your newly working action and extension combo in the Preview tab on the left hand menu. You can now use the action you configured, i.e. “Let me check the weather,” and your Assistant will now make an API call via the extension to retrieve the information!

Watch the magic happen!

You can go off and explore on your own from here if you’d like. However, if you want to see some cool ideas on how you can further evolve your assistant using extensions, read on!

Part 2: Mix, Match, and Keep Extending

The starter kits, as you have seen so far, can help you quickly bring an extension to life. But this is only the beginning — you can now play around with the OpenAPI spec, actions, parameters, etc. to tailor the customer experience completely to your liking.

Here’s an example to show you what we mean.

Scenario: Customers are requesting reservation cancellations due to a stormy weather forecast

Imagine that you run an event reservation service. There’s news of an incoming tropical storm in the south, which has resulted in an overwhelming number of calls to the event cancellations help line.

Photo by Marília Castelli on Unsplash

To your dismay, this means you’ll need to check the weather forecast for each event location and date, to see if the cancellation is justified.

What if you could collect all these requests with the location, date, and automatically pulled weather forecast information, into a ticketing system? All you would need to do is approve or reject each request, since the information already resides in the ticket.

By adding a ticketing extension and linking it with the MetaWeather extension we created in Part 1, we can achieve this flow! Let’s take a closer look.

1. Add a Zendesk Support Extension

For this example, we’ll say our ticketing service of choice was Zendesk. We can repeat the steps from Part 1 to create a Zendesk Support extension.

NOTE — No need to add the Zendesk skill during this step. We will be creating/importing a new skill that uses both extensions.

Both extensions have been added to the assistant!

2. Create an Action that Uses MetaWeather and Zendesk Support

Now, we need to link the two extensions together. Upon a message such as “I want to cancel my event due to the weather,” our bot will:

1. Ask for the customer’s name, email, then the location and date of the reserved event.
2. Retrieve the weather information for that location and date, then create a ticket in Zendesk including that information.
3. Provide the Zendesk ticket number to the customer.

To achieve this, we pass the retrieved values from the MetaWeather response into the Zendesk request. Specifically, we will first use the MetaWeather Location and Location Day operations in order to retrieve the weather information for the date and location provided by the customer.

Storing response items from MetaWeather extension call into relevant variables.

Under Variable values, the starter kit skill comes with expressions that are assigned to various variables. For instance, “Set weather_items to 7.body” will do the following:

1. Grab the response from Step 7.
2. Access the body object field of the response.
3. Assign it to session variable weather_items, which can now be used in future steps and actions.

The value stored in weather_items is an array. So, the function .get(0) grabs the first item for us, from which we can grab and store the weather data values we want.

NOTE— You can check the full structure and types of any given response object or field by looking at the OpenAPI spec in a text editor.

Next, you can feed these Variable values into the Zendesk Create Ticket operation.

Feeding MetaWeather response items into the Zendesk create ticket request.

You can see above that the ticket_request_body variable has been assigned an appended string. This string in full looks like:

"Date: ".append(${step_450}.value).append("\nLocation: ").append(${step_667}).append("\nWeather: ").append(${weather_item_0_status}).append("\nTemperature: ").append(${weather_item_0_temperature}).append("\nWind Speeds: ").append(${weather_item_0_wind_speed})

NOTE — The .append() and the .get() function are part of the Assistant Spring Expression Language (ASEL). Check the documentation to learn how to use this and other similar functions that can help format your content.

This collects all necessary MetaWeather response variables into a single string, which then is passed as the comment body for the Create Ticket operation of the Zendesk extension.

NOTE — If you’d like to explore further, this skill can be found here. Remember that you’ll need to configure the operations and parameters in the action, according to the README section.

3. Voila — Zendesk Now Collects All Your Tickets, Including the Event Specific Weather Data

Now, upon all customer event cancellation requests, tickets will generate and be fully populated with the weather data for the event location and date.

So, a conversation like this…

Customer requests event cancellation due to predicted bad weather.

…will result in…

All requests are gathered under your Zendesk tickets, with full weather and event information!

You can now handle these requests on a case-by-case basis at a single glance, with the clearly and automatically collected weather and event information!

Part 3: Get creative!

You now have all the tools to get started with extensions. Whether you want to integrate customer tickets with calendar invites, purchases with time of day, or something fun like weather with music, there are a multitude of APIs out there that you can combine.

If you ever feel confused, remember that the public repo’s README and Advanced Usage document are there to help you. For even more examples and tools for custom extensions, we also recommend checking out our HubSpot CRM extension article and our OpenAPI generation article!

Oh, and if you don’t see a starter kit for an API you wanted to try, you can:

1. Ask us by creating an issue — if we see increasing demand for a certain API, we’ll add it!
2. Create and contribute the spec to the public repo. We welcome and appreciate your help in creating a more expansive set of starter kits.

In parting, we encourage you to explore Watson Assistant Extensions and see how they can not only help automate, but also differentiate your business with a flexible and capable chat bot experience. Happy building!