Connect to backend systems and third-party APIs with ease thanks to Watson Assistant Extensions!
In our previous article, we explained how we’ve revamped Watson Assistant to make it dramatically easier and faster for anyone (yes, anyone!) to build, publish, and improve a virtual assistant. However, we were missing a key piece: the ability to easily connect to your backend systems or third-party APIs. This is no longer the case! In this article we will explain our newest capability: custom extensions.
The Value
Custom extensions enable you to use more than one endpoint and eliminate the need to create a proxy or a layer of middleware between your assistant and other APIs. Plus, it’s easy to keep track of all of your custom extensions in our integration catalog, and you can work with them in the same way you work with variables when authoring. In short, this feature combines the power of integrating with an API while improving ease of use for developers and content authors alike.
With this increased flexibility, the possibilities for custom extensions are nearly endless, but here are some use cases for inspiration.
- Ticketing — Creating tickets, looking up ticket status
- CRM — Creating lead records, updating lead records, retrieving user info, retrieving account info
- Transactions — Submitting a vacation request in an HR system, filing a claim
- Real-time data — look up the weather, mortgage rates, or items in stock at a store location
Let’s talk about the problem we set out to solve
Typically, information systems, chatbots included, have two options to connect to the external world: Webhooks and Calling an external API (Usually RESTful).
Webhooks are great when you control both ends of the stick and you need to push (or pull) data to external applications. If you own those applications, you can consume the webhook with its data model and do as you please.
In reality, (and more often than we might like to think!), most of us don’t own the application which we are interacting with. It may be a third-party API you want to connect to, or it might be an application owned by a different group in the organization that simply can’t take on consuming a webhook.
With the need to connect to external applications not owned by a single team, the solution is to call those applications using the RESTful API they publish. Let me say it again, as it is critical: we all need to call RESTful APIs that are owned and published by another organization or team — which we have zero control over.
But, because there is no free lunch, the classic problem of data mapping raises its head: if they own the APIs how can we push or pull data to/from those applications, without having to always keep a developer in the loop? Remember, we aim to make Watson Assistant the sweet spot of power + ease of use by a business user. So, here’s an integration method to match!
Here’s how we solved it!
We found a low code approach to building an integration that delivers more power than a webhook while keeping authoring simple. You just need to upload a description of the API you want to connect to, which shows Watson Assistant how the extension works. Then, you use a simple form-based mapping between the assistant’s conversational context and the API request.
A description of the API? Sounds complicated… well, luckily, the development community has zeroed-in on a standard for describing RESTful APIs —the OpenAPI Specification (formerly known as Swagger API).
Often, building a custom extension is as simple as locating the published specification on the third-party application’s website. Alternatively, if its your own backend system that you would like to integrate with, just use one of the free OpenAPI spec editors available online (I recommend swagger.io) to write up your api description.
Let’s go through an example!
Let’s walk through an example using a really slick CRM and ticketing system called Hubspot. Throughout this example, keep in mind how custom extensions deliver the power of a backend integration while also providing ease of use for the developers and the content authors on your team.
Like many products out there, HubSpot publishes an open API specification for all of its APIs, we will focus here on Tickets. Their API is quite comprehensive so before uploading it to Watson Assistant, you might want to view it in an editor.
If the entire spec is overwhelming or you’re just looking to use one or two operations, just delete the operations you don’t plan to use. Then, upload that version of the document to Watson Assistant. From there, you can review your specification before finalizing your extension.
Now that we have the spec, we’ll move into Watson Assistant. The first thing you do is navigate to the integrations catalog and click to build a new extension. Then add your OpenAPI spec.
Once done, your custom integration is almost ready to go. All you need to do is add your credentials to start testing your extension.
Because our clients want to test features in a sandbox environment, Watson assistant allows you to configure your extension in draft with test connection details, such as a server url and credentials that points to your dev environment. That way, you don’t need to send messages to your agents on call just to test your extension. Then, once you are happy with the result, you can can publish your extension by adding an integration to your live environment with details that match your production settings.
Ok, so the extension is ready, but it’s no good if you don’t use it 😉. Here, we’ve focused on ease of use.
Just three steps to go!
A. choose the extension — as you might have more than one
B. choose an operation — as each extension can have multiple operations
C. Map between the contextual information your assistant collected to the input the operation needs in order to execute.
Following along with our Hubspot example, we’ve created a simple action that collects some information to file a ticket disputing a charge, in this example we need the name of the charge (e.g. Walmart, Target, etc), the amount of the charge (e.g. $100) and finally the date (e.g. 1/19/2022).
On the next step, we will choose to use an extension. We can find this under the And then menu:
Select which extension, and which operation you would like to invoke, in this case, we’ll select the Ticketing operation within the Hubspot extension.
Then set the parameters to the information your assistant collected during the conversation. Here we’ve mapped all of the information required to file a ticket. Subject and hs_pipeline_stage are unique to routing within our specific Hubspot instance, simply stating that it’s a dispute ticket and that it is a new stage 1 ticket (as opposed to assigned or closed). We will also add the three pieces of information we collected in the steps above.
Calling the Third-party API is half the job, the other half, is doing something useful with its response. Here, we simply presented the user with the ticket number so they can use it for reference.
Pro Tip: you might have noticed that we checked in the condition if the ticket is defined, but what if something went wrong…? We recommend having another step that will display the status of the call. Check out our example to find out how.
Coming Next….
This is out! Go play with it! Fun Guaranteed! But because we really believe its fun, we plan on publishing quite a few examples, ranging from CRM, Ticketing, Retail, Media to just fun APIs like Weather and Music.
One more thing, we promise to follow-up with another blog on how to troubleshoot 😃! Stay tuned!
