Create an Alexa skill using Watson Conversation and OpenWhisk

In this Code Pattern, we will create an Alexa skill using Watson Conversation via the Apache OpenWhisk serverless framework. Alexa is the voice service behind products like the Amazon Echo. IBM Cloud Functions (based on Apache OpenWhisk) will be used to integrate Alexa with Watson Conversation. Credit goes to Niklas Heidloff for creating the original project.

An example conversation is included to demonstrate how to pass context between different intents. You can also use this Code Pattern to try out a conversation from the Bot Asset Exchange (BAE).

When the reader has completed this Code Pattern, they will understand how to:

Create an OpenWhisk action in the IBM Cloud Functions serverless platform
Use Redis to store a session's conversation context across events
Import a conversation from the Bot Asset Exchange (BAE) or a JSON file
Invoke a conversation with Watson using Node.js
Use the Weather Channel Data service to lookup locations and forecasts
Create an Alexa skill to reach tens of millions of customers

Flow

User says "Alexa, ask Watson...".
Alexa invokes IBM Cloud Functions with input text.
The action gets the conversation context from Redis (if any).
The action gets a response from Watson Conversation.
The Weather Company Data service provides the forecast (when applicable).
The response context is stored in Redis.
The response text is sent back to Alexa.
Alexa replies to the user.

Included components

Watson Conversation: Create a chatbot with a program that conducts a conversation via auditory or textual methods.
OpenWhisk: Execute code on demand in a highly scalable, serverless environment.
Redis: An open-source, in-memory data structure store, used as a database, cache and message broker.

Featured technologies

Serverless: An event-action platform that allows you to execute code in response to an event.
Databases: Repository for storing and managing collections of data.
Node.js: An open-source JavaScript run-time environment for executing server-side JavaScript code.

Watch the Video

Steps

1. Clone the repo

Clone the alexa-skill-watson-conversation repo locally and cd to the local repo (for commands in later steps). In a terminal, run:

$ git clone https://github.com/IBM/alexa-skill-watson-conversation
$ cd alexa-skill-watson-conversation

2. Create a Watson Conversation workspace

Use one or both of these options (with or without BAE) to setup a Conversation workspace.

Using Bot Asset Exchange (BAE)

If you are using BAE, use Get a bot and Get this bot to automatically create your Conversation service and import your workspace(s). The service will be named Bot Asset Exchange Workspaces and can hold up to 5 selected workspaces.

Using the provided workspace.json file

Create the service by following this link and hitting Create:

Watson Conversation

Import the Conversation workspace.json:

Find the Conversation service in your IBM Cloud Dashboard.
Click on the service and then click on Launch Tool.
Click on the import icon (next to the Workspaces Create button).
Click Choose a file and find the local version of data/conversation/workspaces/workspace.json.
Select Everything and click Import.

3. Create a Compose for Redis service

Follow this link and hit Create:

Compose for Redis

4. Create a Weather Company Data service

If you are using the provided workspace.json, use Weather Company Data to provide weather responses.

Follow this link and hit Create:

Weather Company Data

This service includes an OpenWhisk package. Run the following command to update your OpenWhisk bindings:

$ bx wsk package refresh

5. Configure credentials

The credentials for IBM Cloud services (Conversation, Compose for Redis and Weather Company Data), can be found in the Services menu in IBM Cloud, by selecting the Service Credentials option for each service.

Find the WORKSPACE_ID by clicking on the context menu of the workspace and select View details.

The default runtime parameters need to be set for the action. These can be set on the command-line or via the IBM Cloud UI. Here we've provided a params.sample file for you to copy and use with the -param-file .params option.

Copy the params.sample to .params.

$ cp params.sample .params

Edit the .params file and add the required settings.

`params.sample:`

{
  "CONVERSATION_USERNAME": "<add_conversation_username>",
  "CONVERSATION_PASSWORD": "<add_conversation_password>",
  "WORKSPACE_ID": "<add_conversation_workspace_id>",
  "REDIS_URI": "<add_redis_uri>",
  "WEATHER_URL": "<add_weather_url>"
}

6. Create the OpenWhisk action

Install the CLI

Install and test the IBM Cloud Functions CLI by following the steps documented here.

Create the OpenWhisk action

Run these commands to gather Node.js requirements, zip the source files, and upload the zipped files to create a raw HTTP web action in OpenWhisk.

Note: You can use the same commands to update the action if you modify the code.

$ npm install
$ zip -r action.zip *
$ bx wsk action update alexa-watson action.zip --kind nodejs:6 --web raw --param-file .params

7. Create an Alexa skill

Follow the instructions here to register your new skill using the Alexa Skills Kit.

Select Custom Interaction Model and choose a Name and Invocation Name.

Save and hit Next and then you will enter an Intent Schema, Custom Slot Types and Sample Utterances. We'll use a very minimal data here and let Watson Conversation do most of the work.

Copy the data from data/alexa to fill out these three sections.

Intent Schema

Custom Slot Types

Sample Utterances

On the configuration page you need to define an HTTPS service endpoint which is the URL of your OpenWhisk action ending with '.json'. To find this URL, navigate to IBM Cloud Functions - Actions, click on your action and navigate to Endpoints.

To get the Web Action URL, take the example POST URL and:

Replace "/namespaces/" with "/web/"
Replace "/actions/" with "/default/" (or your package name)
Add a ".json" suffix

The resulting URL will have the following structure:

https://{APIHOST}/api/v1/web/{namespace}/{packageName}/{actionName}.json

Hit Next. Under 'Certificate for DEFAULT Endpoint:' select the My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority option.

Hit Next and your skill is ready for testing!

8. Talk to it

You can run the sample via Alexa enabled devices, or the Echo simulator or the service simulator in the Amazon developer portal.

You can invite others to test it with the beta test feature. In order to be eligible for beta test, you must fill out most of the publishing information.

You probably shouldn't publish this example, but you are now ready to create and publish your own Alexa skill.

Sample output

Here is a sample conversation flow using the provided conversation workspace.json:

User: Alexa, ask Watson what do you know about me?
Alexa/Watson: I don't know anything about you. Where do you live?
User: Alexa, tell Watson Berlin
Alexa/Watson: I understand you live in Berlin.
User: Alexa, ask Watson what is the weather forecast?
Alexa/Watson: Looking up weather information for Berlin ...

The sample has been implemented via the slots filling functionality in Watson Conversation. The screenshot shows how the entity (slot) 'location' is defined as mandatory and how the value is stored in a context variable.

The next screenshot shows how the location is automatically used in the next 'weather' intent.

Troubleshooting

Use the IBM Cloud UI to monitor logs, or use this command to show the latest activation log:

bx wsk activation list -l1 | tail -n1 | cut -d ' ' -f1 | xargs bx wsk activation logs

Invoke from command line

Use these commands to invoke the action (named alexa-watson in the example) without any input, then check the latest logs. Expect an error ("Must be called from Alexa").
```
bx wsk action invoke alexa-watson -bvd
bx wsk activation list -l1 | tail -n1 | cut -d ' ' -f1 | xargs bx wsk activation logs
```

Learn more

Artificial Intelligence Code Patterns: Enjoyed this Code Pattern? Check out our other AI Code Patterns.
AI and Data Code Pattern Playlist: Bookmark our playlist with all of our Code Pattern videos
With Watson: Want to take your Watson app to the next level? Looking to utilize Watson Brand assets? Join the With Watson program to leverage exclusive brand, marketing, and tech resources to amplify and accelerate your Watson embedded commercial solution.

License

Apache 2.0

aaditya025/alexa-skill-watson-conversation