Dialogue API Reference

Last updated 3 months ago

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
Intent Classification
Key
Value
intentName
String - The name of the detected intent.
probability
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).
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 Session from the handler code was received in a timely manner
error: The session failed with an error.
error
Optional String - Error description if an error occurs during the session.
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.
​

Reference

Hermes Reference

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

Key	Value
`intentName`	String - The name of the detected intent.
`probability`	Number - The probability of the detection, between 0 and 1, 1 being sure.

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

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

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

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)

Key	Value
`type`	"notification"
`text`	String - Text the TTS should say

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 .

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 .

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

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.

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.