Skill can authenticate incoming converse requests.
BY default - the skill will respond to any incoming converse request. By default it will not authenticate incoming converse requests to make sure that they are coming from a core that this skill is registered to. in order to enable such authentication, change the parameter AUTHENTICATE_REQUESTS to true in the '.env' configuration file
After enabling the authentication, all incoming calls to the skill will be authenticated using a key. The key is generated by the core when the skill is registered to the core, the key should be stored in the keys.txt file found in res/assets/keys.txt.
A key is also used in order to access the skill swagger page, in order to get access just add one of the keys in your key.txt file to the header (you can also create a new key).
This section defines the skill configuration which is used by the core to access and control the skill.
{
"name": "string",
"description": "string",
"private": false,
"author": "string",
"version": "string",
"license": "string",
"callword": "string",
"lifetime": "string",
"threshold": 0,
"languages": [
"string", "string"
],
"tags": [
"string"
],
"nlu": [
"string"
],
"services": [
{
"name": "string",
"description": "string",
"url": "string",
"attributes": [
{
"name": "string",
"type": "string",
"required": false
},
{
"name": "string",
"type": "string",
"required": true
}
]
}
]
}
Parameter | Description | Type | Required |
---|---|---|---|
name | The skill name | string | Yes |
description | Description of the skill | string | No |
private | false for common skill | boolean | no |
author | Author name | string | No |
version | Skill version | string | Yes |
license | string | No | |
languages | Supported languages by the skill | string array | no |
tags | string array | No | |
nlu | Supported NLU engines | string array | No |
services | No |
If an skill is going to be published, it should start at 1.0.0, though it is not mandatory.
After this, changes should be handled as follows:
See Semantic Versioning for more information.
This defines the request interface that is sent to the skill action handler function
{
"id": "string",
"version": "string",
"language": "string",
"text": "string",
"retext": "string",
"attributes": {
},
"context": {
"user" : {
"id": "string"
},
"session" : {
"id": "string",
"new": true,
"attributes" : {
}
},
"application" : {
"id": "string",
"attributes": {
}
}
}
}
Parameter | Description | Type | Required |
---|---|---|---|
id | request id | string | yes |
version | Request version | string | yes |
language | User text query language | string | no |
text | User query as text | string | yes |
retext | User query after text reformatting | string | yes |
attributes | The extracted intent and entities from user request | object | yes |
context: Request context data | object | yes |
Context Type | Description |
---|---|
user | |
application | Application specific context |
session |
Parameter | Description | Type | Required |
---|---|---|---|
id | User unique id | string | yes |
Parameter | Description | Type | Required |
---|---|---|---|
id | Application unique id | string | yes |
attributes | object | yes |
Parameter | Description | Type | Required |
---|---|---|---|
new | boolean | yes | |
attributes | object | yes |
This defines the format of the response that that the skill should return to the interact core.
{
"version": "string",
"reject": "boolean",
"error": "number",
"deleteSkillSession": "boolean",
"speech": {
"text": "string",
"display": "string",
"expressiveness": "string"
},
"card": {
"type": "string",
"title": "string",
"subtitle": "string",
"content": {
}
},
"context": {
"user": {
},
"session": {
},
"application": {
}
},
"metrics": {
"skill": "string"
}
}
Parameter | Description | Type | Required |
---|---|---|---|
version | Response version | string | yes |
reject | boolean | yes | |
deleteSkillSession | boolean | yes | |
context | object | yes |
Parameter | Description | Type | Required |
---|---|---|---|
text | string | yes | |
expressiveness | string | yes |
Parameter | Description | Type | Required |
---|---|---|---|
type | string | yes | |
title | string | yes | |
subtitle | string | yes | |
content | object | no |
Context | Description |
---|---|
user | |
session |
Method | API | Description |
---|---|---|
GET | /v1/api/manifest | Returns the skill manifest as a JSON object. |
GET | /v1/api/nlu | Returns NLU metadata which is used by the interact core NLU engines. |
GET | /v1/api/intents | Returns skill intents descriptors. |
GET | /v1/api/healthCheck | Check the status (health) of the skill. |
POST | /v1/api/converse | Get a response from user input or event. |
The Natural Language Understanding includes data required by the Interact core to extract intents and entities.
The intents file is optional metadata file which includes skill intent descriptors. The information in this file is applied by the core to extracted intent (after NLU extraction phase). The skill developer can use the intents descriptors to increase the accuracy of the skill and to control intent behavior.
{
"<intent name>" :
{
"visibility" : "string",
"entities" : [
{
"name" : "string",
"required" : "boolean"
}
]
}
}
Parameter | Description | Type | Required |
---|---|---|---|
visibility | Can be use to hide or show intent to core | string | No |
{
"workspace": {
"en-US": {
"name:": "string",
"workspaceId": "string"
},
"de-DE": {
"name": "string",
"workspaceId": "string"
}
}
}
TBD
TBD
To run skill locally you can use the following command
npm start
Note! Make sure the port is not used by any other skill / server as the skill will not start.
Build the image
docker build -t skill-boileplate:local .
Create and run a container
docker run --name fun -p 3000:3000 -e PORT=3000 -it skill-boileplate:local
For more information how to build and run containers in Bluemix you can refer to Adding Docker images to your organization's private Bluemix images registry
Build your image and push it to your private Bluemix registry.
bx ic build -t registry.ng.bluemix.net/<namespace>/skill-boileplate:v1.0.0 .
Tip: Run bx ic namespace get
to retrieve your namespace information.
Create a container from your image.
bx ic create --name skill-boileplate -p 3001:3001 -e PORT=3001 registry.ng.bluemix.net/<namespace>/skill-boileplate:v1.0.0
Note: Select port that will not conflict with other skill
If can be published as public skill, bind a public IP address to your container.
bx ic bind <ip address> <container ID>
Tip: You can see your public IP addresses by running bx ic ips
. To request a new one, run bx ic ip request
.
The skill (locally or hosted) can be tested directly with the skill converse REST API. Use the following json block in the skill swagger page.
{
"id": "001",
"text": "hello world",
"retext": "hello world",
"version": "1.0",
"language": "en-US",
"attributes": {
"intent": "hello-world"
},
"context": {
"user": {
"id": "user-001"
},
"application": {
"id": "app-001",
"attributes": {
}
},
"session": {
"new": true,
"attributes": {
},
"version": "1.0"
}
}
}
Running all the tests:
$ npm test