Chatting with Watson to Hook any Tweets: Webhook Tutorial

Published in

IBM watsonx Assistant

6 min readAug 29, 2019

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)

Prerequisite:

IBM Cloud account
Watson Assistant instance
Twitter Developer Account : Consumer key (API key), Consumer Secret (API Secret), Access Token, and Access Token Secret.

Introduction

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.

Code for this tutorial is available on Github

Cloud Function

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_key , 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.

add a default value to be able to test your function by using “Invoke”

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

Successfully tested the Action that returns correct values (on the right)

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

API Key — get username and password to access the

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.

Webhook Setup

Click on “Option” tab -> “Webhooks”:

In Request URL, specify the URL of your action and it’s important to append ?blocking=true parameter 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.

https://us-south.functions.cloud.ibm.com/api/v1/namespaces/<your-email>/actions/last_tweets?blocking=true

In Headers: Click Add authorization, add your credentials to the User name and Password fields, and then click Save.

How to set up a Webhook in Watson Assistant — super easy

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

How to activate the webhooks option in the 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[0] ?>)
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).

Conclusion

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!

Code for this tutorial is available on Github