Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/primaryobjects/chatskills

Run and debug Alexa skills on the command-line. Create bots. Run them in Slack. Run them anywhere!
https://github.com/primaryobjects/chatskills

alexa alexa-sdk alexa-skill amazon amazon-alexa amazon-alexa-skill amazon-echo chatbot chatbots conversational-ui echo javascript slack slack-bot slackbot

Last synced: 11 days ago
JSON representation

Run and debug Alexa skills on the command-line. Create bots. Run them in Slack. Run them anywhere!

Awesome Lists containing this project

README 

        
Chatskills

----------



Run [Alexa](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide) apps on the command-line. Run them in Slack. Run them anywhere! Supports Amazon Alexa skills and intents.



```bash

$ npm install chatskills

```



Chatskills is a quick and easy way to run Alexa apps outside of Amazon. Easily create your skills and intents and run them right on the command-line!



Chatskills does not require a server and can run directly in the console. It can also run on the web, or Slack, or anywhere. It handles requests from multiple users and maintains session memory. When a user starts a conversation with one of the skills, the skill continues to execute within a session context, until the skill terminates.



Here's what an Amazon Alexa app looks like, running on the command-line.



## Example



```

> chatskills, ask hello to say hi.

Hello, World!

> chatskills, ask horoscope for Scorpio.

Things are looking up today for Scorpio.

> chatskills, ask funny to tell me a joke

Knock knock.

> who's there?

Banana.

> banana who

Knock knock.

> whos there

Orange.

> orange who?

Orange you glad I didn't say banana?

```



In this example, the user accesses three different skills: [hello](https://github.com/primaryobjects/chatskills/blob/master/test.js#L4-L15), [horoscope](https://github.com/primaryobjects/chatskills/blob/master/horoscope.js), and [funny](https://github.com/primaryobjects/chatskills/blob/master/funny.js).



## Usage



Using chatskills is easy. Use the Alexa syntax to add a new skill, then create some intents. Here's a simple example.



```javascript

var chatskills = require('chatskills');



// Create a skill.

var hello = chatskills.app('hello');



// Create an intent.

hello.intent('helloWorld', {

    'slots': {},

    'utterances': [ '{to |}{say|speak|tell me} {hi|hello|howdy|hi there|hiya|hi ya|hey|hay|heya}' ]

    },

    function(req, res) {

        res.say('Hello, World!');

    }

);



// Respond to input.

chatskills.respond('chatskills, ask hello to say hi', function(response) {

    console.log(response);

});

```



In the above example, the utterances grammar automatically expands to match on the following phrases:



```

helloWorld      to say hi

helloWorld      say hi

helloWorld      to speak hi

helloWorld      speak hi

helloWorld      to tell me hi

helloWorld      tell me hi

helloWorld      to say hello

helloWorld      say hello

helloWorld      to speak hello

helloWorld      speak hello

helloWorld      to tell me hello

helloWorld      tell me hello

helloWorld      to say howdy

...

```



To interact with the chatbot using this skill, say any of the target phrases. In the above example, we've used the phrase "to say hi", but you can match against any of the generated phrases. For example:



```

> chatskills, ask hello to tell me hi

Hello, World!

> chatskills, ask hello to say hello

Hello, World!

> chatskills, ask hello to say howdy

Hello, World!

```



## Reading from the Console



To create a chatbot that runs locally on the console, just include a loop for reading input.



```javascript

var readlineSync = require('readline-sync');



// Console client.

var text = ' ';

while (text.length > 0 && text != 'quit') {

    text = readlineSync.question('> ');



    // Respond to input.

    chatskills.respond(text, function(response) {

        console.log(response);

    });

}

```



If you're using async calls in your skills (such as request, etc) then you'll want to use an async loop, instead of the while loop above. Here's an [example](https://github.com/primaryobjects/chatskills/blob/master/chatbot.js#L39).



## Reading from Slack



You don't have to use just the console! You can run your chatbot anywhere, like Slack. See [here](https://gist.github.com/primaryobjects/e1a182c7ef2f8d33731e) for full example.



```javascript

var SlackBot = require('slackbots');

var bot = new SlackBot({ token: token, name: 'awesome' });



// Listen to slack messages.

bot.on('message', function(message) {

    // Reply to humans.

    if (message.type == 'message' && message.text && message.subtype != 'bot_message') {

        var author = getUserById(message.user);

        var channel = getChannelById(message.channel);



        // Respond to input, use author.name as the session id.

        chatskills.respond(message.text, author.name, function(response) {

            if (channel) {

                // Public channel message.

                bot.postMessageToChannel(channel.name, response);

            }

            else {

                // Private message.

                bot.postMessageToUser(author.name, response);

            }

        });

    }

});

```



![Chatskills running on Slack](https://raw.githubusercontent.com/primaryobjects/chatskills/master/images/chatskills-slack.png)



## Creating a Skill



Skills are programs that your chatbot can run. They consist of intents, which are composed of utterances (phrases to match from the user input), responses, and session memory. Each skill can access session memory, so you can store and retrieve variables to help with responding intelligently to the user.



Here's an example of creating a new skill, named "horoscope".



```javascript

var horoscope = chatskills.app('horoscope');

```



## Creating an Intent



Skills are made up of intents. This is where input from the user is matched against an array of utterances. When a match is found, that intent is executed. An intent can get/set variables in the user session by calling ```req.get('variable')``` and ```req.set('variable', value)```. An intent can output a response by calling ```res.say('hello')```.



Here's an example of creating a new intent for the skill "horoscope".



```javascript

horoscope.intent('predict', {

    'slots': {'SIGN':'LITERAL'},

    'utterances': [ 'for {signs|SIGN}' ]

    },

    function(req, res) {

        res.say('Things are looking up today for ' + req.get('SIGN') + '.');

    }

);

```



This intent can be interacted with like this:



```

> chatskills, ask horoscope for Scorpio

Things are looking up today for Scorpio.

```



## Launching a Skill



There are two ways to begin running a skill.



#### Using an Intent to "Run"



The first way to launch a skill is to create an intent such as, "run". This would let you enter: "chatskills, ask [skillname] to run.". Provided the intent has a return value of true (to keep the session alive), your skill will now be running.



An example of a "run" skill can be found in [guessinggame](https://github.com/primaryobjects/chatskills/blob/master/guessinggame.js).



```javascript

app.intent('run', {

        "slots": {},

        "utterances": ["{to|} {run|start|go|launch}"]

    }, function(req, res) {

        var prompt = "Guess a number between 1 and 100!";

        res.say(prompt).reprompt(prompt).shouldEndSession(false);

    }

);

```



#### Using the Launch Method



The second way to launch a skill is to create a launch method to automatically run upon starting your app. Then simply call `chatskills.launch(app)` to start your skill. You can pass the skill or the name of the skill. You can also provide an optional unique sessionId.



Example: `chatskills.launch(app)` or `chatskills.launch('horoscope')` or `chatskills.launch('horoscope', 'some-unique-id')`.



Here's a complete [example](https://github.com/primaryobjects/chatskills/blob/master/hello.js).



```javascript

var chatskills = require('./lib/chatskills');

var readlineSync = require('readline-sync');



// Create a skill.

var hello = chatskills.app('hello');



// Launch method to run at startup.

hello.launch(function(req,res) {

    res.say("Ask me to say hi!");



    // Keep session open.

    res.shouldEndSession(false);

});



// Create an intent.

hello.intent('helloWorld', {

    'slots': {},

    'utterances': [ '{to |}{say|speak|tell me} {hi|hello|howdy|hi there|hiya|hi ya|hey|hay|heya}' ]

    },

    function(req, res) {

        res.say('Hello, World!');

    }

);



// Start running our skill.

chatskills.launch(hello);



// Console client.

var text = ' ';

while (text.length > 0 && text != 'quit') {

    text = readlineSync.question('> ');



    // Respond to input.

    chatskills.respond(text, function(response) {

        console.log(response);

    });

}

```



## Starting and Ending a Session



When a user provides input, the input is matched against each skill and their list of intents. When a match is found, a new session starts, and the skill begins executing.



When a session has started for a user, the activated skill's intent can get/set variable values within the session. This allows you to store and retrieve data.



While a session is open for a user, all input from the user is directed to the activated skill. In this manner, the user does not need to re-request a skill ("chatskills, ask hello to say hi"). Instead, the user can simply provide text, which will be matched against the currently executing skill's intents.



An intent can keep a session open by returning `true` or by calling `res.shouldEndSession(false)` and end a session by returning `false` or by calling `res.shouldEndSession(true)`. An intent may also omit a return statement, which is the same as returning false.



For an example using session, see the [horoscope](https://github.com/primaryobjects/chatskills/blob/master/horoscope.js#L31) skill. Notice, the intent asks the user a question and then returns true to keep the session going. The intent only returns false once a valid response is given, thus, ending the session.



In summary, when a user session is open, all input from the user is directed to the skill. When a user session is ended, input from the user must be received in the format, "chatskills, ask [SKILL] text", to execute a new skill.



## Session Timeout



The default session timeout is 1 hour of no input from the user. To change the session timeout, set ```chatskills.timeout = 3600```, where the value is specified in seconds. To disable session timeout, set the value to 0.



## Changing the Chatbot Name



The default chatbot name is "chatskills". All requests to execute a skill must begin with the chatbot name. For example, "chatskills, ask hello to say hi". To customize the chatbot name, use the following:



```javascript

chatskills.name('awesome');

```



## Verbose Output



To display warnings and errors, set ```chatskills.verbose = true```.



## Schema and Utterances



Chatskills uses [alexa-app](https://www.npmjs.com/package/alexa-app) to generate many sample utterances from your intents. For a more detailed description of utterances, see [here](https://www.npmjs.com/package/alexa-app#schema-and-utterances).



### Schema Syntax



Pass an object with two properties: slots and utterances.



```javascript

app.intent('sampleIntent',

    {

        "slots":{"NAME":"LITERAL","AGE":"NUMBER"}, 

        "utterances":[ "my {name is|name's} {names|NAME} and {I am|I'm} {1-100|AGE}{ years old|}" ]

    },

    function(request,response) { ... }

);

```



#### Slots



The slots object is a simple Name:Type mapping. The type must be one of Amazon's supported slot types: LITERAL, NUMBER, DATE, TIME, DURATION



#### Custom Slot Types



As a replacement for the `LITERAL` slot type, which is no longer being supported by Amazon, it is recommended to use custom slot types in its place. Here is an example of defining a custom slot type for `DragonType`.



```javascript

app.intent('attack', 

    {

        'slots': { 'DragonType': 'DRAGONTYPE' },

        'utterances': ['{attack|fight|hit|use} {sword|dagger|wand} on {-|DragonType} dragon']

    }, function(request,response) {

        response.say('You are attacking the ' + request.slot('DragonType') + ' dragon!');

    }

);

```



You can include custom slot types within utterances by using the syntax `{-|CustomTypeName}`. This indicates that the term should come from a list of values for the custom slot type. In the example above, the utterance uses the term `{-|DragonType}`, indicating a term should come from the list of values (shown below). For chatskills, a list of values does not need to be provided - any word will be accepted for a custom slot type and used as its value.



If publishing to the Amazon Alexa service, you would provide the custom slot types for `DragonType` by specifying the type name and a list of values. For example:



Type:

`DRAGONTYPE`



Values:

```

golden

fire

ice

water

snow

```



Note, chatskills and Amazon Alexa will actually accept any word for the custom slot value. It doesn't have to match a word from the list of values. In this manner, custom slot types are similar to `LITERAL`.



#### Utterances



The utterances syntax allows you to generate many (hundreds or even thousands) of sample utterances using just a few samples that get auto-expanded. Any number of sample utterances may be passed in the utterances array. Below are some sample utterances macros and what they will be expanded to.



#### Multiple Options mapped to a Slot



```

"my favorite color is {red|green|blue|NAME}"

=>

"my favorite color is {red|NAME}"

"my favorite color is {green|NAME}"

"my favorite color is {blue|NAME}"

```



#### Generate Multiple Versions of Static Text



This lets you define multiple ways to say a phrase, but combined into a single sample utterance



```

"{what is the|what's the|check the} status"

=>

"what is the status"

"what's the status"

"check the status"

```



#### Auto-Generated Number Ranges



When capturing a numeric slot value, it's helpful to generate many sample utterances with different number values



```

"buy {2-5|NUMBER} items"

=>

"buy {two|NUMBER} items"

"buy {three|NUMBER} items"

"buy {four|NUMBER} items"

"buy {five|NUMBER} items"

```



Number ranges can also increment in steps



```

"buy {5-20 by 5|NUMBER} items"

=>

"buy {five|NUMBER} items"

"buy {ten|NUMBER} items"

"buy {fifteen|NUMBER} items"

"buy {twenty|NUMBER} items"

```



#### Optional Words



```

"what is your {favorite |}color"

=>

"what is your color"

"what is your favorite color"

```



#### Using a Dictionary



Several intents may use the same list of possible values, so you want to define them in one place, not in each intent schema. Use the app's dictionary.



```

app.dictionary = {"colors":["red","green","blue"]};

...

"my favorite color is {colors|FAVEORITE_COLOR}"

"I like {colors|COLOR}"

```



## Displaying Home Cards



You can display Amazon Alexa Home [Cards](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/providing-home-cards-for-the-amazon-alexa-app#Creating%20a%20Home%20Card%20to%20Display%20Text%20and%20an%20Image) by handling the card [object](https://www.npmjs.com/package/alexa-app#card-examples) returned in the response method. When using alexa-app, the home card will be displayed in the Amazon Alexa App on your mobile device. When using chatskills, the home card can be handled in the `chatskills.respond()` callback method, which returns two arguments: `response` and `card`.



Using the card object, you can display the card's text and image in any manner you wish. For example, if hosting your chatskills app in Slack, you may want to show the image as embedded media. Likewise, if hosting as a text chatbot on the console, you may simply want to output the card as text.



Below is an example.



```javascript

app.intent('example', {

        "slots": {},

        "utterances": ["show a card"]

    }, function(req, res) {

      // Show home card in Alexa app.

      res.card({

        type: 'Standard',

        title: 'My Awesome Card', // this is not required for type Simple or Standard 

        text: 'This is an example of an Alexa home card.',

        image: { // image is optional 

          smallImageUrl: 'http://www.yoursite.com/image.jpg', // required 

          largeImageUrl: null

        }

      });

});



// Respond to input.

chatskills.respond(text, function(response, card) {

    if (!card) {

      // Text response from res.say() method.

      console.log(response);

    }

    else {

      // Home card response from res.card() method.

      console.log('[DISPLAYING CARD: Title=' + card.title + ', Text=' + card.text + ']');

    }

});

```



License

----



MIT



Author

----



Kory Becker

http://www.primaryobjects.com/kory-becker