In this tutorial you will learn how to make external API callouts from Watson Assistant. We will use Webhooks, Cloud Function, and Twitter API, to retrieve the last tweets of any account.
What you will learn:
- How to leverage your virtual assistant to retrieve information from Twitter
- How to use Webhooks in Watson Assistant
- How to use and write Cloud Functions (in Python)
- IBM Cloud account
- Watson Assistant instance
- Twitter Developer Account : Consumer key (API key), Consumer Secret (API Secret), Access Token, and Access Token Secret.
How can you personalise your assistant and improve it by adding new functionality? How easy it is to make external API calls from Watson Assistant? With Webhooks is really easy.
In this tutorial, we will use the new webhooks feature from Watson Assistant, and cloud functions (FaaS) to achieve this goal and you will be able to ask your virtual assistant to retrieve the last tweets from any Twitter account.
Let’s focus on the Cloud Function, first. Go to your IBM Cloud account click on “create resource” (top right) and search for “functions” and select the result. Then, click on the “Actions” tab in the left banner, and create e new action (Create → Create Action). Note: On the top right, be sure to pick a CF-based namespace and not a new IAM-based namespace, since currently (last update oct-2019) you can make a call to an action that is managed by Cloud Foundry, but not to an action that uses token-based Identity and Access Management (IAM) authentication. Moreover, you should select the same region where your Watson Assistant instance sits.
Be sure to work on a CF-Based namespace and the Cloud Function and Watson Assistant instance need to be in the same region.
Pick a name for your function (e.g. “last_tweets”) and runtime (in this case I have picked Python 3) then click on “Create”. You can find the code to copy & paste here but make sure to add your Twitter Dev Account credentials in the appropriate fields (
client_secret) and hit Save:
Now, click on “Parameters” (left banner) and add a variable called “account”. This parameter will receive information from your Assistant when the user explicitly asks for tweets of a specific account. Here, I’m leaving a default value (@taylorswift13) so that I can test my function.
Let’s check if everything is working fine: go back to the “Code” tab (on the left) and invoke your function. You should be able to get the last tweets from Miss Swift (Default Value for now).
Everything working? If yes, next step:
Since you have completed your cloud function, click on “Endpoints” and take notes of:
- the URL of your action
- then click on “API-KEY” and the first part of the string (before the colon “:”) is your username and the second part is your password
Webhooks and Watson Assistant
Now, you are ready to move to Watson Assistant (WA). Download the skill in json format and upload it into your Watson Assistant instance (how to upload a skill). Again, be sure that your instance is in the same region as the cloud function.
A Webhook sends a POST request callout to an external application that performs a programmatic function. When used in a dialog skill, a webhook is triggered when the assistant processes a node that has a webhook enabled.
How to use a webhook:
- Webhook setup: specify the request URL for an external API you want to invoke
- Enable a dialog node: a webhook enabled node will trigger the action and sends specific parameters to the API.
Click on “Option” tab -> “Webhooks”:
- In Request URL, specify the URL of your action and it’s important to append
?blocking=trueparameter to the action URL to force a synchronous call to be made. You cannot make an asynchronous call to a cloud functions action with a webhook. When you send an asynchronous request, only an activation ID is returned.
- In Headers: Click Add authorization, add your credentials to the User name and Password fields, and then click Save.
Enable a dialog node
Go to the “Dialog” tab: click on “Twitter — Last tweets” node and see its children nodes. If the user specifies a twitter account then the first child node will be triggered (“Account Specified”) and in that node, Webhook functionality has been indeed activated. How to do it? It’s really simple: you need to click on the “customise” button, scroll down to the Webhooks section, and switch the toggle to On, and then click Apply (how to add a webhook in a node).
In “Account Specified” node (where Webhook option is active) you can see several new fields.
- Parameters: data that you want to pass to the external application as key and value pairs
- Return variable: response made by the callout is saved to the return variable
- Response condition if $webhook_result_1 is recognised: response to show when the webhook callout is successful and a return variable is sent back. Here, I would suggest playing with $webhook_result_1 variable to understand the content of the response and to decide what and in which format you want to show the results to the end-user. (i.e.
last tweet:<br>-<? $webhook_result_1.response.result.result ?>)
- Response condition if anything_else is recognised: response to show when the callout fails
Try it out!
Once you have created your cloud function, and correctly set up the webhook in the Options tab, the Watson Assistant Skill in the git repo already contains all the intent, entity and dialogue structure that allows you to play directly in the Try it out panel (top right). Try typing: “tweets from @blackmirror” (note the @ symbol) you should see displayed text and some images (if tweeted by the account).
Now you should be able to create your own cloud function, use webhooks in Watson Assistant and ask your virtual agent to show the latest tweets of your favourite artist, event or TV show etc!
- Documentation: https://cloud.ibm.com/docs/services/assistant?topic=assistant-dialog-webhooks
- Demo: https://www.youtube.com/watch?v=j8TBqD2rx2o
- Blog — It’s Now Way Easier to Personalize Your Assistant!: https://medium.com/ibm-watson/its-now-way-easier-to-personalize-your-assistant-9a23a9cadd4
- IBM Cloud Function & Webhooks: https://cloud.ibm.com/docs/services/assistant?topic=assistant-dialog-webhooks#dialog-webhooks-cf
- Blog — Weather as Function of Clouds: https://www.ibm.com/developerworks/community/blogs/hickmat/entry/Weather_as_a_Function_of_Clouds?lang=en