Amazon Alexa

This node.js example connector makes a Teneo bot available on Amazon Alexa as a Skill. This guide will take you through the steps of deploying the connector to respond to events sent by Alexa.

Amazon Alexa logo

You can find the source code of this project on Github.

Prerequisites

Amazon Developer account

Create an Amazon Developer Account here.

Teneo Engine

Your bot needs to be published and you need to know the engine URL.

Setup instructions

Setup an Alexa Skill

Go to the Amazon Developer Console and create a new skill:
- Click Create Skill
- Give you skill a name
- Select a language from the dropdown
- Leave model as Custom or select another if appropiate
- Leave as Alexa-hosted
- Click Create Skill at the upper right of page
- Leave template as Hello World Skill, click Continue with Template at upper right of page – this will take a minute or so.

Click Interaction Model in left menu then select the JSON Editor section, paste the JSON below. In the example JSON below we will call our bot 'Studio bot'. If you want to use a different name to invoke your bot, make sure you update the invocationName and the sample sentences for the AMAZON.StopIntent. You can do this after you have pasted the JSON below into the Amazon JSON Editor.

json

1{
2    "interactionModel": {
3        "languageModel": {
4            "invocationName": "studio bot",
5            "intents": [
6                {
7                    "name": "AMAZON.FallbackIntent",
8                    "samples": []
9                },
10                {
11                    "name": "AMAZON.CancelIntent",
12                    "samples": []
13                },
14                {
15                    "name": "AMAZON.HelpIntent",
16                    "samples": []
17                },
18                {
19                    "name": "AMAZON.StopIntent",
20                    "samples": [
21                        "close studio bot",
22                        "dismiss studio bot",
23                        "shut down studio bot",
24                        "goodbye studio bot",
25                        "bye studio bot"
26                    ]
27                },
28                {
29                    "name": "teneointent",
30                    "slots": [
31                        {
32                            "name": "RawInput",
33                            "type": "LIST_OF_COMMANDS"
34                        }
35                    ],
36                    "samples": [
37                        "{RawInput}"
38                    ]
39                },
40                {
41                    "name": "AMAZON.NavigateHomeIntent",
42                    "samples": []
43                }
44            ],
45            "types": [
46                {
47                    "name": "LIST_OF_COMMANDS",
48                    "values": [
49                        {
50                            "name": {
51                                "value": "Hello"
52                            }
53                        },
54                        {
55                            "name": {
56                                "value": "What is your name"
57                            }
58                        },
59                        {
60                            "name": {
61                                "value": "Where are you"
62                            }
63                        }
64                    ]
65                }
66            ]
67        }
68    }
69}
70

This JSON represents the Interaction Model of this Alexa skill, and defines:

The invocation name of our bot, which is used to redirects the conversation away from Alexa to your Teneo bot when the user says something like "Alexa, launch Studio bot".
The phrases that trigger the StopIntent, which dismisses your bot, and steers the conversation back to Alexa.
The way in which the user input is captured, to be later relayed to your Teneo bot.

Click Save Model and then Build Model at the top of the page to build and update Alexa's Interaction model.  This will take about a minute.

Run the connector

Before continuing setting up things on Alexa's Developer Console side, get the connector code running using one of the two available ways described ahead:

The way is to run the connector locally or to deploy it on a server of your choice. This preferred if you're familiar with node.js development and want to have a closer look at the code and plan to enhance or modify it.

Running the connector locally

If you want to run the connector locally, follow the steps below.

Download or clone the connector source code: git clone https://github.com/artificialsolutions/tie-api-example-alexa.git
Install dependencies by running the following command in the folder where you stored the source: npm install
Create a .env file in the folder where you stored the source, and add the Teneo engine url: TENEO_ENGINE_URL=<your_engine_url>
Start the connector in Console: node server.js

Next, we need to make the connector available via https. We'll use ngrok for this.

Start ngrok. The connector runs on port 3467 by default, so we need to start ngrok like this: ngrok http 3467
Running the command above will display a public https URL. Copy it, we will use it as a Service Endpoint URL in the next steps ahead.

Add the endpoint URL to your skill

Go back to the Developer Console and select your skill.
Click Endpoint from the left menu.
Select a HTTPS service endpoint type, and paste the public URL from ngrok obtained earlier in the Default Region field. Make sure this URL does not end in a slash character '/'.
From the Select SSL certificate type dropdown, select 'My developement endpoint is a sub-domain ... that has a wildcard certificate from a certificate authority'.
Click on Save endpoints.
Click on the Left Side menu > JSON Editor > Build Model to update the changes.

That's it! You're now ready to talk to your Alexa bot.

Start talking to your bot

In the top menu, click Test to begin chatting to the bot. Skill Testing is enabled by selecting Development mode, if requested. At first, the conversation takes place with Alexa. To begin talking with your Teneo bot, say something like "Alexa, launch studio bot". Your Teneo bot should then greet you, and take over the conversation.
To end a conversation with your bot and go back to talking to Alexa, say something like "Goodbye studio bot". You will now be talking to Alexa again.

Engine input parameters

The following input parameters are included in requests to Engine.

Channel

In addition to the input entered by the user, requests to the Teneo Engine also contain an input paramter 'channel' with value 'amazon-alexa'. This allows you to change the behavior of your bot, depending on the channel used. For information on how to retrieve the value of an input parameter in Teneo Studio, see Store input parameters on the Teneo Developers website.