README.md 12 KB
Newer Older
1 2 3 4 5 6


<p  align="center">

<img  src="https://user-images.githubusercontent.com/41849970/57236777-691ae200-7043-11e9-8d8e-67e05e60a8e4.png">

PrajvalRaval's avatar
PrajvalRaval committed
7 8
</p>

9 10 11 12 13 14
  

<h3  align="center">

Innovating Incredible New User Experiences In The Alexa Ecosystem

PrajvalRaval's avatar
PrajvalRaval committed
15 16
</h3>

17 18
  

PrajvalRaval's avatar
PrajvalRaval committed
19
---
Ashish Jha's avatar
Ashish Jha committed
20

21 22
  

Ashish Jha's avatar
Ashish Jha committed
23 24
# Let's Get Started

25 26
  

Ashish Jha's avatar
Ashish Jha committed
27 28
**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](https://aws.amazon.com/), and the [ASK Developer Portal](https://developer.amazon.com/alexa-skills-kit).

29 30
  

Ashish Jha's avatar
Ashish Jha committed
31 32
### Repository Contents

33 34 35 36 37 38 39 40 41 42 43 44
*  `/.ask` - [ASK CLI (Command Line Interface) Configuration](https://developer.amazon.com/docs/smapi/ask-cli-intro.html)

*  `/lambda/custom` - Back-End Logic for the Alexa Skill hosted on [AWS Lambda](https://aws.amazon.com/lambda/)

*  `/lambda/custom/resources` - Language specific speech response

*  `/models` - Voice User Interface and Language Specific Interaction Models

*  `skill.json` - [Skill Manifest](https://developer.amazon.com/docs/smapi/skill-manifest.html)

  
  
Ashish Jha's avatar
Ashish Jha committed
45 46 47

## Setup w/ ASK CLI

48 49
  

Ashish Jha's avatar
Ashish Jha committed
50 51
### Pre-requisites

52 53
  

Ashish Jha's avatar
Ashish Jha committed
54
* Node.js (> v8.10)
55

Ashish Jha's avatar
Ashish Jha committed
56
* Register for an [AWS Account](https://aws.amazon.com/)
57

Ashish Jha's avatar
Ashish Jha committed
58
* Register for an [Amazon Developer Account](https://developer.amazon.com/)
59

Ashish Jha's avatar
Ashish Jha committed
60
* Install and Setup [ASK CLI](https://developer.amazon.com/docs/smapi/quick-start-alexa-skills-kit-command-line-interface.html)
61

Ashish Jha's avatar
Ashish Jha committed
62
* Rocket Chat Server updated to [Release 1.0.0-rc3](https://github.com/RocketChat/Rocket.Chat/releases/tag/1.0.0-rc.3) or later
Ashish Jha's avatar
Ashish Jha committed
63

64 65
  
  
Ashish Jha's avatar
Ashish Jha committed
66 67

### Installation
68

Ashish Jha's avatar
Ashish Jha committed
69 70
1. Clone the repository.

71 72 73 74 75 76 77 78 79
  

```bash

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

```

  
Ashish Jha's avatar
Ashish Jha committed
80 81 82

2. Navigating into the repository's root folder.

83 84 85 86 87 88 89 90 91
  

```bash

$ cd alexa-rocketchat

```

  
Ashish Jha's avatar
Ashish Jha committed
92 93 94

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

95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
  

```bash

$ 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,

```javascript

    "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"
                }
            }
        }
    }
Ashish Jha's avatar
Ashish Jha committed
146
	
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
```
  

3. Go to [Deployment](#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.

  

```bash

	$ 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](https://github.com/RocketChat/alexa-rocketchat-notification). Also it will be worth checking out this video to get insights [Alexa Notifications with Proactive Events - Dabble Lab #125](https://www.youtube.com/watch?v=oMcHTMZDTVQ).

  

8. WE ARE DONE! To test the skill, go to [Testing](#testing).

  

Ashish Jha's avatar
Ashish Jha committed
174 175
### Deployment

176 177
  

Ashish Jha's avatar
Ashish Jha committed
178 179
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.

180 181
  

SingLi's avatar
SingLi committed
182
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:
Ashish Jha's avatar
Ashish Jha committed
183

184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
  

```bash

    $ 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](#configuring-notifications) to complete the rest of notification setup or proceed with configuring account linking steps if you're already done.
206

207 208
### Configuring Account Linking

209 210
  

SingLi's avatar
SingLi committed
211
1. Login to Alexa Developer Console, click on the Rocket.Chat skill on the list, and go to Build section on top.
212

213 214
  

215 216
2. Click on Account Linking on the bottom left.

217 218 219 220 221
  

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.

  
222 223 224

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.

225 226 227 228 229
  

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

  
230 231 232

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

233 234
  

235 236
![Go to Server -> Administration](https://i.ibb.co/wgJnBxD/diagram1.jpg)

237 238
  

239 240
7. Click on **OAuth Apps**.

241 242
  

243 244
![Click on OAuth Apps](https://i.ibb.co/Wp2P42k/diagram2.jpg)

245 246 247 248
  

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

249
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.
250

251
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.
252

253 254
  

255 256
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.

257 258
  

259 260
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.

261 262
  

263 264
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.

265 266
  

267 268
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**.

269 270
  

271 272
![Add custom OAuth](https://i.ibb.co/4jykrFx/diagram3.jpg)

273
  
274

275
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**.
276

277
  
SingLi's avatar
SingLi committed
278

279
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**.
280

281
  
282

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

285
  
286

287 288
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](#configuring-notifications) and complete the rest of notifications setup.
289

Ashish Jha's avatar
Ashish Jha committed
290 291
### Testing

292 293 294 295 296
  

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.

  
Ashish Jha's avatar
Ashish Jha committed
297

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

300 301
  

302
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](https://echosim.io/welcome), or through your Amazon Mobile App and say :
Ashish Jha's avatar
Ashish Jha committed
303

304 305 306 307 308 309 310 311
  

```text

    Alexa, start rocket chat

```

312 313 314

### Setting up Local development

Rocket_Chat's avatar
Rocket_Chat committed
315 316
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.
317 318 319 320 321 322 323

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>
324 325 326 327
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)>
328 329 330 331 332 333 334 335 336 337
```

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.

Ashish Jha's avatar
Ashish Jha committed
338 339
## Customization

340 341 342 343 344 345 346
  

1.  ```./skill.json```

  

Change the skill name, example phrase, icons, testing instructions etc ...
Ashish Jha's avatar
Ashish Jha committed
347

348
  
Ashish Jha's avatar
Ashish Jha committed
349

350
See the Skill [Manifest Documentation](https://developer.amazon.com/docs/smapi/skill-manifest.html) for more information.
Ashish Jha's avatar
Ashish Jha committed
351

352
  
Ashish Jha's avatar
Ashish Jha committed
353

354
2.  ```./lambda/custom/index.js```
Ashish Jha's avatar
Ashish Jha committed
355

356
  
357

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

360
  
Ashish Jha's avatar
Ashish Jha committed
361

362
3.  ```./lambda/custom/resources/*.json```
PrajvalRaval's avatar
PrajvalRaval committed
363

364 365 366 367 368 369 370 371 372 373 374 375 376 377
  

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.

  
  
PrajvalRaval's avatar
PrajvalRaval committed
378 379 380

## Documentation To Refer

381 382 383
  

1.  ```Rocket.Chat API Documentation```
PrajvalRaval's avatar
PrajvalRaval committed
384

385
The REST API allows you to control and extend Rocket.Chat with ease - [REST API Documentation]( https://rocket.chat/docs/developer-guides/rest-api/ )
PrajvalRaval's avatar
PrajvalRaval committed
386

387
  
388

389
2.  ```Axios Documentation```
390

391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407
  

Promise based HTTP client for the browser and node.js - [Github Page](https://github.com/axios/axios )

  

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](https://github.com/JargonInc/jargon-sdk-nodejs/tree/master/packages/alexa-skill-sdk )

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 ](https://developer.amazon.com/docs/custom-skills/slot-type-reference.html )
PrajvalRaval's avatar
PrajvalRaval committed
408 409 410

## Intent Structure

411 412
  

PrajvalRaval's avatar
PrajvalRaval committed
413
1. Keep sample utterance minimal.
414

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

PrajvalRaval's avatar
PrajvalRaval committed
417
3. Use only custom slots and include real examples from Rocket.chat for Natural language training.
418

PrajvalRaval's avatar
PrajvalRaval committed
419 420
4. Include as many slot values as you can. More the merrier.

421 422
  

PrajvalRaval's avatar
PrajvalRaval committed
423 424
## A Little Help

425 426
  

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

Feel free to join the discussion in our Alexa channel - [Rocket.Chat Alexa Channel](https://open.rocket.chat/channel/alexa)