Dialogue API Reference

This API contains two types of messages:

  • Inbound Messages are produced by the platform, you should "subscribe" and react to them

  • Outbound Messages are sent to the platform, you should "publish" them and the platform will react accordingly

Intent

Inbound Message

MQTT Topic
Android Listener
iOS Closure

You should subscribe tohermes/intent/<intentName>.

Replace <intentName> by the name of the intent you want to handle. You can use the MQTT wildcard # to receive all intents.

You should register a listener using setOnIntentDetectedListeneron SnipsPlatformClient.

You can write your closure in the onIntentDetected property on SnipsPlatform client.

let snips = SnipsPlatform(...)
snips.onIntentDetected = { intent in
// Your code here
}

This is the main message the handler code should subscribe to. It is sent by the Dialogue Manager when an intent has been detected.

Note that it is the handler's responsibility to inform the Dialogue Manager of what it should do with the current session by sending either a Continue Session or an End Session with the current sessionId

Payload

Key

Value

sessionId

String - Session of the intent detection. The client code must use it to continue or end the session.

customData

Optional String - Custom data provided in the Start Session or a Continue Session.

siteId

String - Site where the user interaction took place.

input

String - The user input that has generated this intent.

intent

Object - Structured description of the intent classification, see Intent Classification below.

slots

Optional Array of Objects - Structured description of the detected slots for this intent if any, see Slot below.

asrTokens

Optional Double Array of Objects - Structured description of the tokens the ASR captured on for this intent. The first level of arrays represents each invocation of the ASR, the second one are the tokens captured, see ASR Token below. Note that this is not mapped on Android and iOS yet

asrConfidence

Optional Number - ASR confidence score between 0 and 1, 1 being sure.

Intent Classification

Key

Value

intentName

String - The name of the detected intent.

confidenceScore

Number - The probability of the detection, between 0 and 1, 1 being sure.

Slot

Key

Value

confidence

Number - Confidence of the slot, between 0 and 1, 1 being confident.

raw_value

String - The raw value of the slot, as is was in the input.

value

String - The resolved value of the slot.

entity

String - The entity of the slot.

slotName

String - The name of the slot.

range

Optional Object - The range where the slot can be found in the input. The object contains 2 integer fields: start representing the beginning of the range (inclusive) and end representing the end (exclusive).

ASR Token

Key

Value

value

String - The value of the token

confidence

Number - Confidence of the token, between 0 and 1, 1 being confident

rangeStart

Integer - The start range in which the token is in the original input

rangeEnd

Integer -The end range in which the token is in the original input

time

Object - Time when this token was detected. The object contains 2 Number fields: start representing the start time and end representing the end time

Start Session

Outbound Message

MQTT Topic
Android Method
iOS Method

You should publish to hermes/dialogueManager/startSession.

You should send a message using dialogueStartSession on SnipsPlatformClient.

Three methods are at your disposal to start a session:

func startSession() throws
func startSession(message: StartSessionMessage) throws
func startSession(text: String? = nil, intentFilter: [String]? = nil, canBeEnqueued: Bool = true, sendIntentNotRecognized: Bool = false, customData: String? = nil, siteId: String? = nil) throws
// Usage
let snips = SnipsPlatform(...)
try? snips.startSession()

You can send this message to programmatically initiate a new session. The Dialogue Manager will start the session by asking the TTS to say the text (if any) and wait for the answer of the end user.

Payload

Key

Value

siteId

Optional String - Site where to start the session

init

Object - Session initialization description: Action or Notification. See below

customData

Optional String - Additional information that can be provided by the handler. Each message related to the new session - sent by the Dialogue Manager - will contain this data

Session Initialization: Action

Use this type when you need the end user to respond

Key

Value

type

"action"

text

Optional String - Text that the TTS should say at the beginning of the session.

canBeEnqueued

Boolean - if true, the session will start when there is no pending one on this siteId, if false, the session is just dropped if there is running one.

intentFilter

Optional Array of Strings - A list of intents names to restrict the NLU resolution on the first query.

sendIntentNotRecognized

Optional Boolean - Indicates whether the dialogue manager should handle non recognized intents by itself or sent them as an Intent Not Recognized for the client to handle. This setting applies only to the next conversation turn. The default value is false (and the dialogue manager will handle non recognized intents by itself)

Session Initialization: Notification

Use this type when you only want to inform the user of something without expecting a response.

Key

Value

type

"notification"

text

String - Text the TTS should say

Session Queued

Inbound Message

MQTT Topic
Android Listener
iOS Closure

You should subscribe tohermes/dialogueManager/sessionQueued.

You should register a listener using setOnSessionQueuedListeneron SnipsPlatformClient.

You can write your closure in the onSessionQueuedHandler property on SnipsPlatform client.

let snips = SnipsPlatform(...)
snips.onSessionQueuedHandler = { message in
// Your code here
}

This message is sent by the Dialogue Manager when it receives a Start Session message and the corresponding site is busy. Only Start Session messages with a notification initialisation or an action initialisation with the canBeEnqueued flag set to true can be enqueued. When the site is free again, this session will be started.

Payload

Key

Value

sessionId

String - Session identifier that was enqueued.

siteId

String - Site where the user interaction will take place.

customData

Optional String - Custom data provided in the Start Session .

Session Started

Inbound Message

MQTT Topic
Android Listener
iOS Closure

You should subscribe to hermes/dialogueManager/sessionStarted.

You should register a listener using setOnSessionStartedListener on SnipsPlatformClient.

You can write your closure in the onSessionStartedHandler property on SnipsPlatform client.

let snips = SnipsPlatform(...)
snips.onSessionStartedHandler = { message in
// Your code here
}

This message is sent by the Dialogue Manager when a new session is started, either following a wakeword or programmatically.

Payload

Key

Value

sessionId

String - Session identifier that was started.

siteId

String - Site where the user interaction is taking place.

customData

Optional String - Custom data provided in the Start Session .

Continue Session

Outbound Message

MQTT Topic
Android Method
iOS Method

You should publish to hermes/dialogueManager/continueSession.

You should send a message using dialogueContinueSession on SnipsPlatformClient.

Two methods are at your disposal to continue a session:

func continueSession(sessionId: String, text: String, intentFilter: [String]?) throws
func continueSession(message: ContinueSessionMessage) throws
// Usage
let snips = SnipsPlatform(...)
try? snips.continueSession(sessionId: "xxxx", text: "Next command")

You should send this after receiving received an Intent when you want to continue the session for example to ask additional information to the end user.

Be sure to use the same sessionId as the one in the Intent message.

Payload

Key

Value

sessionId

String - Identifier of the session to continue.

text

String - The text the TTS should say to start this additional request of the session.

intentFilter

Optional Array of String - A list of intents names to restrict the NLU resolution on the answer of this query. If this contains unknown intent names, the NLU will post an error message and the session will be closed.

customData

Optional String - an update to the session's custom data. If not provided, the custom data will stay the same.

sendIntentNotRecognized

Optional Boolean - Indicates whether the dialogue manager should handle non recognized intents by itself or sent them as an Intent Not Recognized for the client to handle. This setting applies only to the next conversation turn. The default value is false (and the dialogue manager will handle non recognized intents by itself).

slot

Optional String, requires intentFilter to contain a single value - If set, the dialogue engine will not run the the intent classification on the user response and go straight to slot filling, assuming the intent is the one passed in the intentFilter, and searching the value of the given slot

End Session

Outbound Message

MQTT Topic
Android Method
iOS Method

You should publish tohermes/dialogueManager/endSession.

You should send a message using dialogueEndSession on SnipsPlatformClient.

Two methods are at your disposal to end a session:

func endSession(sessionId: String, text: String? = nil) throws
func endSession(message: EndSessionMessage) throws
// Usage
let snips = SnipsPlatform(...)
try? snips.endSession(sessionId: "xxxx")

You should send this after receiving received an Intent when you want to end the session.

Be sure to use the same sessionId as the one in the Intent message.

Payload

Key

Value

sessionId

String - Identifier of the session to end.

text

Optional String - The text the TTS should say to end the session.

If the text is null, the Dialog Manager will immediately send a Session Ended after receiving this message, otherwise, the Session Ended will be sent after the text is said.

Session Ended

Inbound Message

MQTT Topic
Android Listener
iOS Closure

You should subscribe to hermes/dialogueManager/sessionEnded.

You should register a listener using setOnSessionEndedListener on SnipsPlatformClient.

You can write your closure in the onSessionEndedHandler property on SnipsPlatform client.

let snips = SnipsPlatform(...)
snips.onSessionEndedHandler = { message in
// Your code here
}

This message is sent by the Dialogue Manager when a session is ended.

Payload

Key

Value

sessionId

String - Session identifier of the ended session.

customData

Optional String - Custom data provided in the Start Session or a Continue Session.

siteId

String - Site where the user interaction took place.

termination

Object - Structured description of why the session has been ended. See below.

Session Termination Type

Key

Value

reason

String - the reason why the session was ended this can have the following values:

  • nominal: the session ended as expected (a endSession message was received).

  • abortedByUser: the session aborted by the user.

  • intentNotRecognized: the session ended because no intent was successfully detected.

  • timeout: The session timed out because no response from one of the components or no Continue Session or End Sessionfrom the handler code was received in a timely manner

  • error: The session failed with an error.

Intent Not Recognized

Inbound Message

MQTT Topic
Android Listener
iOS Closure

You should subscribe to hermes/dialogueManager/intentNotRecognized.

You should register a listener using onIntentNotRecognizedListener on SnipsPlatformClient.

You can write your closure in the onIntentNotRecognizedHandler property on SnipsPlatform client.

let snips = SnipsPlatform(...)
snips.onIntentNotRecognizedHandler = { message in
// Your code here
}

This message is sent by the dialogue manager when it failed to recognize and intent AND you requested the dialogue manager to notify you of such events using the sendIntentNotRecognized flag in the last Start Session or Continue Session

Payload

Key

Value

sessionId

String - Session identifier of the session that generated this intent not recognized event.

customData

Optional String - Custom data provided in the Start Session or a Continue Session.

siteId

String - Site where the user interaction took place.

input

Optional String - The input, if any that generated this event.

Configure

Outbound Message

MQTT Topic
Android Method
iOS Method

You should publish to hermes/dialogueManager/configure.

This feature is not available yet on Android.

This feature is not available yet on iOS.

You can send this message to programmatically configure the scope of intents that are enabled at a given time. By default, all intents are enabled by default unless specified otherwise in the console. Refers to the dedicated Console tutorial for further details. The behaviour implemented by the intentFilter attributes for the start session and continue session locally overwrites the set of enabled/disabled intents only for the next user turn.

Payload

Key

Value

siteId

Optional String - Site where to start the session

intents

Array of Intent configuration objects - see Intent configuration description below

Intent configuration

Key

Value

intentId

String - Intent name to configure

enable

Boolean - if true, the intent will be enabled which means that the Intent message for the related intent_name is enabled and will be triggered if the intent is detected.