Boilerplate for remote skill

Table of Contents

• Authentication
• JSON Interface Reference
• API Reference
• Intents
• NLU
• Languages
• Logging
• Tests
• Code Style
• Tools

Authentication

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).

JSON Interface Reference

Manifest

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
          }
        ]
      }
    ]
}

Parameters Description

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

Skill Version

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:

• (PATCH) Bug fixes and other minor changes: Patch release, increment the last number, e.g. 1.0.1
• (MINOR) New features which don't break existing features: Minor release, increment the middle number, e.g. 1.1.0
• (MAJOR) Changes which break backwards compatibility: Major release, increment the first number, e.g. 2.0.0

See Semantic Versioning for more information.

Request

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": {
      }
    }
  }
}

Parameters Description

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

Request Context Types

Context Type	Description
user
application	Application specific context
session

User Context Object

Parameter	Description	Type	Required
id	User unique id	string	yes

Application Context Object

Parameter	Description	Type	Required
id	Application unique id	string	yes
attributes		object	yes

Session Context Object

Parameter	Description	Type	Required
new		boolean	yes
attributes		object	yes

Response

This defines the format of the response that that the skill should return to the interact core.

{
  "version": "string",
  "reject": "boolean",
  "error": "number",
  "shouldEndSession": "boolean",
  "speech": {
    "text": "string",
    "display": "string",
    "expressiveness": "string"
  },
  "card": {
    "type": "string",
    "title": "string",
    "subtitle": "string",
    "content": {
    }
  },
  "context": {
    "user": {
    },
    "session": {
    },
    "application": {
    }
  },
  "metrics": {
    "skill": "string"
  }
}

Parameters Description

Parameter	Description	Type	Required
version	Response version	string	yes
reject		boolean	yes
shouldEndSession		boolean	yes
context		object	yes

Speech Object

Parameter	Description	Type	Required
text		string	yes
expressiveness		string	yes

Card Object

Parameter	Description	Type	Required
type		string	yes
title		string	yes
subtitle		string	yes
content		object	no

Response Context Types

Context	Description
user
session

API Reference

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.

NLU

The Natural Language Understanding includes data required by the Interact core to extract intents and entities.

Intents Descriptors

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

Watson Conversation Service (WCS)

{
  "workspace": {
    "en-US": {
      "name:": "string",
      "workspaceId": "string"
    },
    "de-DE": {
      "name": "string",
      "workspaceId": "string"
    }
  }
}

Regular expressions

API.AI

Languages

TBD

Logging

TBD

Running

Locally

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.

Docker

Prerequisites

• Install Docker

Locally

• 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

Bluemix

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.

How To Manually Test Skill

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"
    }
  }
}

Tests

Running all the tests:

$ npm test