Innovating Incredible New User Experiences In The Alexa Ecosystem

---

Let's Get Started

Note: The rest of this readme assumes you have your developer environment ready to go and that you have some familiarity with CLI (Command Line Interface) Tools, AWS, and the ASK Developer Portal.

Repository Contents

• /.ask - ASK CLI (Command Line Interface) Configuration

• /lambda/custom - Back-End Logic for the Alexa Skill hosted on AWS Lambda

• /lambda/custom/resources - Language specific speech response

• /models - Voice User Interface and Language Specific Interaction Models

• skill.json - Skill Manifest

Setup w/ ASK CLI

Pre-requisites

• Node.js (> v8.10)

• Register for an AWS Account

• Register for an Amazon Developer Account

• Install and Setup ASK CLI

• Rocket Chat Server updated to Release 1.0.0-rc3 or later

Installation

1. Clone the repository.

$ git clone https://github.com/RocketChat/alexa-rocketchat.git

2. Navigating into the repository's root folder.

$ cd alexa-rocketchat

3. Install npm dependencies by navigating into the lambda/custom directory and running the npm command: npm install

$ cd lambda/custom

$ npm install

Configuring Notifications

1. If you already have an Alexa Skill deployed, Open ./skill.json file and add the ARN of your AWS Lambda function.

2. If you're about to deploy your Alexa Skill for the first time, cut the following piece of code from the ./skill.json file,

    "permissions": [
        {
            "name": "alexa::devices:all:notifications:write"
        }
    ],
    "events": {
        "publications": [
            {
                "eventName": "AMAZON.MessageAlert.Activated"
            }
        ],
        "endpoint": {
            "uri": "your-arn-here"
        },
        "subscriptions": [
            {
                "eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"
            }
        ],
        "regions": {
            "NA": {
                "endpoint": {
                    "uri": "your-arn-here"
                }
            }
        }
    }
	

3. Go to Deployment and complete the deployment steps and also configure the account linking. Once done complete the following steps.
4. Paste the above piece of code back to your ./skill.json file. Add the ARN of your AWS Lambda function you just deployed in place of your-arn-here.
5. Deploy the changes.

	$ ask deploy

6. Go to your Alexa App and enable notifications for this skill. New users of the skill will be the shown the permissions settings while enabling the skill itself.

7. Setup a notifications microservice following the instructions in Rocket Chat Alexa Skill Notifications. Also it will be worth checking out this video to get insights Alexa Notifications with Proactive Events - Dabble Lab #125.

8. WE ARE DONE! To test the skill, go to Testing.

Deployment

ASK CLI will create the skill and the lambda function for you. The Lambda function will be created in us-east-1 (Northern Virginia) by default.

1. Make sure you are at your alexa-rocketchat top level project directory, then deploy the skill and the lambda function in one step by running the following command:

    $ ask deploy

2. After Deploying go to lambda console and set Environment variables values.

e.g:

1. SERVER_URL https://yourservername.rocket.chat

2. OAUTH_SERVICE_NAME (The name of the Custom OAuth you setup in next step)

3. DDB_NAME (The name of the Dynamo DB table being used by your skill)

4. Then go to the IAM console and add policies to access DynamoDB and Cloudwatch to the role for this lambda function.

5. Go back to Configuring Notifications to complete the rest of notification setup or proceed with configuring account linking steps if you're already done.

Configuring Account Linking

1. Login to Alexa Developer Console, click on the Rocket.Chat skill on the list, and go to Build section on top.

2. Click on Account Linking on the bottom left.

3. Toggle the Do you allow users to create an account or link to an existing account with you? button. Leave Allow users to enable skill without account linking as it is. Select auth code grant.

4. Now we need to fill up the Authorization URI, Access Token URI, Client ID, Client Secret which we will generate on our rocket chat server.

5. Note you need to be admin of the server to proceed with the further steps.

6. In a new tab go to your Server -> Three Dot Menu -> Administration.

7. Click on OAuth Apps.

8. Click on New Application on top right. Now we need to give it an Application Name and a Redirect URI.

9. For Application Name use "alexa". This can be anything else as well. And for the Redirect URI, go back to Amazon Developer Console Account Linking page and at the bottom of the page you'll find some redirect URLs.

Copy https://pitangui.amazon.com/api/skill/link/YOURVENDORID or https://layla.amazon.com/api/skill/link/YOURVENDORID or https://alexa.amazon.co.jp/api/skill/link/YOURVENDORID and paste it in the Redirect URI field. They work according to the locale of your developer account, so try another if one of them doesn't work. Click on save changes.

10. You'll see it automatically generating Client ID, Client Secret, Authorization URL, and Access Token URL. Now copy these from the oauth app page and paste it in the Client ID, Client Secret, Authorization URL, and Access Token URL fields on the amazon developer console account linking page.

11. Choose "HTTP Basic" for Client Authentication Scheme and leave Scope, Domain List and Default Access Token Expiration Time empty. Click on Save on top.

12. We are done on setting our OAuth App which will give us the access token to use for logging in. But for that we need to also enable custom oauth login for our server which we will do in the next steps.

13. Go to your Server -> Three Dot Menu -> Administration. Scroll down on your left and select OAuth and on top right click on Add custom OAuth.

14. Give a unique name in lower case for the custom oauth. For example enter "alexaskill".Click on Send. Set this name in the lambda environment variables for OAUTH_SERVICE_NAME.

15. You will now be provided a few fields some of which will be prefilled. We only need to change a few. First change the Enable to true. In the URL enter https://yourservername.rocket.chat/api/v1.

16. Finally at the bottom switch Merge users to true. We don't need to make any other changes here.

17. Click on Save Changes on top. We are done with setting up the account linking.

18. Go back to Step 4 of Configuring Notifications and complete the rest of notifications setup.

Testing

1. Before testing, you must make sure that Account Linking has completed. Go to alexa.amazon.com or your alexa app and click account linking to complete the link.

2. To test, you need to login to Alexa Developer Console, and enable the "Test" switch on your skill from the "Test" Tab.

3. Once the "Test" switch is enabled, your skill can be tested in the Alexa skill simulator or on devices associated with the developer account as well. Speak to Alexa from any enabled device, from your browser at echosim.io, or through your Amazon Mobile App and say :

    Alexa, start rocket chat

Setting up Local development

With this setup, develper can run the backend code of the skill in the system itself, leading to faster development.
Note: The below setups are optional and is not required for the code to run in aws lambda.

1. Navigate to ./lambda/custom folder and make a new file named .env

2. Add the following to .env file

ACCESS_KEY_ID=<your aws account access key ID>
SECRET_ACCESS_KEY=<your aws account secret access key>
SERVER_URL=<rocket chat server url>
OAUTH_SERVICE_NAME=<oauth service name>
DDB_NAME=<dynamo table name>
CUSTOM_LOG_URL=<custom logger url(optional parameter)>

3. From ./lambda/custom folder, run npm start to start the server at port 3000.

4. Install ngrok, then in a new terminal run ngrok http 3000, copy the https forwarding link.

5. In the build section of the Alexa Developer Console, go to endpoint submenu in the sidebar and set the Service Endpoint Type to HTTPS.

6. In the default region input box, paste the link from step 4 and set the drop down to "My development endpoint is a sub-domain of a domain that has wildcard certificate from a certificate authority" option, save the changes.

Customization

1. ./skill.json

Change the skill name, example phrase, icons, testing instructions etc ...

See the Skill Manifest Documentation for more information.

2. ./lambda/custom/index.js

Add new handlers for intents, modify intent logic, enhance the functionality of the source code to customize the skill.

3. ./lambda/custom/resources/*.json

Modify messages, and other strings to customize the skill responses. Repeat the operation for each locale you are planning to support.

4. ./models/*.json

Change the model definition to replace the invocation name and, if necessary for your customization, the sample phrases for each intent. Repeat the operation for each locale you are planning to support.

Documentation To Refer

1. Rocket.Chat API Documentation

The REST API allows you to control and extend Rocket.Chat with ease - REST API Documentation

2. Axios Documentation

Promise based HTTP client for the browser and node.js - Github Page

3. Jargon Documentation

The Jargon SDK makes it easy for skill developers to manage their runtime content, and to support multiple languages from within their skill - Github Page

4. Slot Type Reference

The Alexa Skills Kit supports several slot types that define how data in the slot is recognized and handled - Official Documentation

Intent Structure

1. Keep sample utterance minimal.

2. Make sure you have included the values that are required to send to the API as slots in the sample utterance.

3. Use only custom slots and include real examples from Rocket.chat for Natural language training.

4. Include as many slot values as you can. More the merrier.

A Little Help

Keep an eye on our issues. We are just beginning and will surely appreciate all the help we can get. All ideas are welcome.

Feel free to join the discussion in our Alexa channel - Rocket.Chat Alexa Channel