Async skill api 1.0.0 documentation

Async skill api 1.0.0

Overview

The Skills Async API provides a way for developers to create more advanced conversation interactions with your Digital People, by allowing you to send and receive messages asynchronously. This provides more flexibility than the REST-based skill API when you want to go beyond simple request-response interactions.

Example applications can be streaming multiple messages in the same turn, or allowing the skill to send messages to the user proactively.

Messages consist of a name and a payload, as per AsyncAPI standards. Messages are sent over a websocket connection that persists through the session.

You can still implement the skill REST API Init and Delete project operations as part of your async skill if you need to do any project related processing.

Servers

ws://localhost:5000/wslocal
Local WebSocket server for development and testing

Operations

RECEIVE /
Operation IDreceiveMessage
Available only on servers:
- local
Accepts one of the following messages:
- #0conversation
  Message IDconversation
  object
  Payload schema for conversation messages. Conversation message from the user sent to the skill.
  
  projectId
  string
  sessionId
  string
  object
  Additional properties are allowed.
  text
  required
  string
  object
  Additional properties are allowed.
  array<object>
  object
  Memory used to persist information between calls to /execute and between skills
  
  name
  required
  string
  Identifier for the memory value
  
  value
  required
  any
  Memory value (can be of any type)
  
  session_id
  string
  Optional session ID to identify this memory value
  
  scope
  string
  Memory scope:
  
  PRIVATE - memory values tagged with this scope are not shared outside calls to this skill
  
  PUBLIC - memory values tagged with this scope are viewable and modifiable by all skills
  
  Allowed values:
  "PRIVATE"
  "PUBLIC"
  object
  tuple<object, object, object, ...optional<any>>
  1 item:
  object
  object
  name
  memory1
  scope
  PRIVATE
  value
  value1
  session_id
  456ABC456
  2 item:
  object
  object
  name
  memory2
  scope
  PUBLIC
  object
  name
  string
  3 item:
  object
  object
  name
  memory3
  scope
  PUBLIC
  value
  1
  session_id
  123ABC123
  Additional properties are allowed.
  deploymentEnvironment
  string
  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.
  
  Allowed values:
  "preview"
  "public"
  Additional properties are allowed.
  Examples
  { "projectId": "string", "sessionId": "string", "config": {}, "text": "string", "variables": {}, "memory": [ { "name": "string", "value": null, "session_id": "string", "scope": "PRIVATE" } ], "deploymentEnvironment": "preview" }
  
  This example has been generated automatically.
- #1sessionStart
  Message IDsessionStart
  object
  Payload schema for sessionStart messages. Message sent to the skill at the start of the session, can be useful to do processing or caching on a per-session basis.
  
  projectId
  required
  string
  sessionId
  required
  string
  required
  object
  Additional properties are allowed.
  deploymentEnvironment
  string
  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.
  
  Allowed values:
  "preview"
  "public"
  Additional properties are allowed.
  Examples
  { "projectId": "string", "sessionId": "string", "config": {}, "deploymentEnvironment": "preview" }
  
  This example has been generated automatically.
- #2sessionEnd
  Message IDsessionEnd
  object
  Payload schema for sessionEnd messages. Message sent to the skill at the end of the session, can be useful to clean up session resources or do end-of-session processing
  
  projectId
  required
  string
  sessionId
  required
  string
  deploymentEnvironment
  string
  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.
  
  Allowed values:
  "preview"
  "public"
  Additional properties are allowed.
  Examples
  { "projectId": "string", "sessionId": "string", "deploymentEnvironment": "preview" }
  
  This example has been generated automatically.
SEND /
Operation IDsendMessage
Available only on servers:
- local
Accepts the following message:
skillConversation
Message IDskillConversation
object
Payload schema for skillConversation messages. Conversation message emitted by the skill to be sent to the user.

text
required
string
object
Additional properties are allowed.
object
Intent object containing the matched intent name and the confidence of the match

name
string
Name of intent that handled the request or 'NO_MATCH' if a fallback is hit

confidence
number
Confidence of the intent matched in the range 0-1

Additional properties are allowed.
array<object>
object
Memory used to persist information between calls to /execute and between skills

name
required
string
Identifier for the memory value

value
required
any
Memory value (can be of any type)

session_id
string
Optional session ID to identify this memory value

scope
string
Memory scope:

PRIVATE - memory values tagged with this scope are not shared outside calls to this skill

PUBLIC - memory values tagged with this scope are viewable and modifiable by all skills

Allowed values:
"PRIVATE"
"PUBLIC"
object
tuple<object, object, object, ...optional<any>>
1 item:
object
object
name
memory1
scope
PRIVATE
value
value1
session_id
456ABC456
2 item:
object
object
name
memory2
scope
PUBLIC
object
name
string
3 item:
object
object
name
memory3
scope
PUBLIC
value
1
session_id
123ABC123
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "text": "string", "variables": {}, "intent": { "name": "MY_INTENT", "confidence": 0 }, "memory": [ { "name": "string", "value": null, "session_id": "string", "scope": "PRIVATE" } ] }

This example has been generated automatically.

Messages

#1SessionStart
Message IDSessionStart
object
Payload schema for sessionStart messages. Message sent to the skill at the start of the session, can be useful to do processing or caching on a per-session basis.

projectId
required
string
sessionId
required
string
required
object
Additional properties are allowed.
deploymentEnvironment
string
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.

Allowed values:
"preview"
"public"
Additional properties are allowed.
#2SessionEnd
Message IDSessionEnd
object
Payload schema for sessionEnd messages. Message sent to the skill at the end of the session, can be useful to clean up session resources or do end-of-session processing

projectId
required
string
sessionId
required
string
deploymentEnvironment
string
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.

Allowed values:
"preview"
"public"
Additional properties are allowed.
#3UserConversation
Message IDUserConversation
object
Payload schema for conversation messages. Conversation message from the user sent to the skill.

projectId
string
sessionId
string
object
Additional properties are allowed.
text
required
string
object
Additional properties are allowed.
array<object>
object
Memory used to persist information between calls to /execute and between skills

name
required
string
Identifier for the memory value

value
required
any
Memory value (can be of any type)

session_id
string
Optional session ID to identify this memory value

scope
string
Memory scope:

PRIVATE - memory values tagged with this scope are not shared outside calls to this skill

PUBLIC - memory values tagged with this scope are viewable and modifiable by all skills

Allowed values:
"PRIVATE"
"PUBLIC"
object
tuple<object, object, object, ...optional<any>>
1 item:
object
object
name
memory1
scope
PRIVATE
value
value1
session_id
456ABC456
2 item:
object
object
name
memory2
scope
PUBLIC
object
name
string
3 item:
object
object
name
memory3
scope
PUBLIC
value
1
session_id
123ABC123
Additional properties are allowed.
deploymentEnvironment
string
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.

Allowed values:
"preview"
"public"
Additional properties are allowed.
#4SkillConversation
Message IDSkillConversation
object
Payload schema for skillConversation messages. Conversation message emitted by the skill to be sent to the user.

text
required
string
object
Additional properties are allowed.
object
Intent object containing the matched intent name and the confidence of the match

name
string
Name of intent that handled the request or 'NO_MATCH' if a fallback is hit

confidence
number
Confidence of the intent matched in the range 0-1

Additional properties are allowed.
array<object>
object
Memory used to persist information between calls to /execute and between skills

name
required
string
Identifier for the memory value

value
required
any
Memory value (can be of any type)

session_id
string
Optional session ID to identify this memory value

scope
string
Memory scope:

PRIVATE - memory values tagged with this scope are not shared outside calls to this skill

PUBLIC - memory values tagged with this scope are viewable and modifiable by all skills

Allowed values:
"PRIVATE"
"PUBLIC"
object
tuple<object, object, object, ...optional<any>>
1 item:
object
object
name
memory1
scope
PRIVATE
value
value1
session_id
456ABC456
2 item:
object
object
name
memory2
scope
PUBLIC
object
name
string
3 item:
object
object
name
memory3
scope
PUBLIC
value
1
session_id
123ABC123
Additional properties are allowed.
Additional properties are allowed.

Async skill api 1.0.0

Overview

Servers

Operations

RECEIVE /

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

SEND /

Examples

This example has been generated automatically.

Messages