Skip to main content
API docs by Redocly

Skill Implementation API (1.0.0)

Download OpenAPI specification:Download

URL: https://soulmachines-support.atlassian.net/wiki/spaces/SSAS/overview

Overview

The Skills REST API provides a way for developers to create their own skills programmatically and subsequently expose them in Digital DNA Studio so that they can be used by users building interactions with Digital People. These endpoints are hooks that will be triggered at different stages once the Skill has been registered and added to a project.

Note: The /execute endpoint is required while the other endpoints are optional. For Stateful Skills, it is recommended to implement the /session endpoint.

Init

Runs when a DDNA Studio project is deployed with this Skill configured.

(optional) Use this endpoint to implement any Skill-specific initialization (such as configuration, data storage, or pre-training) that needs to be run in advance of the Skill being executed at runtime.

This endpoint will be called each time a DDNA Studio Project using the Skill is deployed. The endpoint should expect to be called multiple times with the same projectId but varying config as the project may be redeployed with changes to the Skill's configuration.

header Parameters
Authorization
string

Authorization header (future functionality)

Request Body schema: application/json
projectId
required
string

Unique identifier for the project using the skill and its deployment environment. For example, each project will give a unique ID for either of its preview and public deployments.

deploymentEnvironment
required
string (DeploymentEnvironment)
Enum: "preview" "public"

Environment that the related Project is deployed in - preview (within DDNA Studio) or public (typical deployment for end users). When running in a preview environment, the Skill should minimize execution time, particularly for the Init endpoint.

ownerId
string
organizationId
string
config
required
object

Skill configuration data will be included in this object.

Responses

Request samples

Content type
application/json
{
  • "projectId": "ABC123",
  • "deploymentEnvironment": "preview",
  • "ownerId": "string",
  • "organizationId": "string",
  • "config": {
    }
}

Session

Establishes a session

(optional for Stateless Skills) Establishes a session with a particular projectID/sessionID/config combination. Required for stateful skills. This is an optional endpoint which is called at the start of every interaction between a user and a Digital Person prior to the first conversation turn. It can be used to initialize session-specific resources.

header Parameters
Authorization
string

Authorization header (future functionality)

Request Body schema: application/json
projectId
required
string

Unique identifier for the project using the skill and its deployment environment. For example, each project will give a unique ID for either of its preview and public deployments.

deploymentEnvironment
required
string (DeploymentEnvironment)
Enum: "preview" "public"

Environment that the related Project is deployed in - preview (within DDNA Studio) or public (typical deployment for end users). When running in a preview environment, the Skill should minimize execution time, particularly for the Init endpoint.

sessionId
required
string

A UUIDv4 identifier for this particular session

config
object

Includes Skill configuration data in this object.

Array of objects (Memory)

Information stored from the most recent response received from the endpoint

Responses

Request samples

Content type
application/json
{
  • "projectId": "ABC123",
  • "deploymentEnvironment": "preview",
  • "sessionId": "7600aff2-6ebd-44de-bcd2-1facd8ab4f29",
  • "config": {
    },
  • "memory": [
    ]
}

Response samples

Content type
application/json
{
  • "memory": [
    ]
}

Execute

Executes this Skill on each user conversation turn

(required) This is the primary endpoint to which user requests are sent every turn. This endpoint should return a response which is to be spoken by the Digital Person.

header Parameters
Authorization
string

Authorization header (future functionality)

Request Body schema: application/json
projectId
required
string

Unique identifier for the project using the skill and its deployment environment. For example, each project will give a unique ID for either of its preview and public deployments.

deploymentEnvironment
required
string (DeploymentEnvironment)
Enum: "preview" "public"

Environment that the related Project is deployed in - preview (within DDNA Studio) or public (typical deployment for end users). When running in a preview environment, the Skill should minimize execution time, particularly for the Init endpoint.

sessionId
required
string

A UUIDv4 identifier for this particular session

object (Intent)

Intent object containing the matched intent name and the confidence of the match

text
required
string

User input

required
Array of objects (Memory)

Information stored from the most recent response received from the endpoint

config
object

Skill configuration data will be included in this object. This property will only be included if the Skill is Stateless (i.e. no endpointSession is provided).

object

Contains the context of the request, is also used to send DP specific data e.g. EQ data. Might contain Processing_Stage stating if a request is for a pre or post stage. Might contain Conversation_History of up to 5 conversation turns.

Responses

Request samples

Content type
application/json
{
  • "projectId": "ABC123",
  • "deploymentEnvironment": "preview",
  • "sessionId": "7600aff2-6ebd-44de-bcd2-1facd8ab4f29",
  • "intent": {
    },
  • "text": "Show me a cat",
  • "memory": [
    ],
  • "config": {
    },
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "output": {
    },
  • "intent": {
    },
  • "memory": [
    ],
  • "endConversation": true,
  • "endRouting": false
}

Delete

Runs when a DDNA Studio project stops using this Skill

(optional) Use this endpoint to implement any clean-up for a Skill when it is no longer used by a project.

Skills which make use of the init endpoint may also find the delete endpoint particularly useful for cleaning up any long-running tasks or stored data associated with the provided projectId.

The delete endpoint will be called every time a DDNA Studio project using this Skill is deleted. It will also be called when a project using the Skill removes it and is then redeployed.

path Parameters
id
required
string

Project ID that triggered this hook

header Parameters
Authorization
string

Authorization header (future functionality)

Request Body schema: application/json
deploymentEnvironment
required
string (DeploymentEnvironment)
Enum: "preview" "public"

Environment that the related Project is deployed in - preview (within DDNA Studio) or public (typical deployment for end users). When running in a preview environment, the Skill should minimize execution time, particularly for the Init endpoint.

Responses

Request samples

Content type
application/json
{
  • "deploymentEnvironment": "preview"
}