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
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 setOnIntentDetectedListener
on 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
Key | Value |
| String - Session of the intent detection. The client code must use it to continue or end the session. |
| Optional String - Custom data provided in the Start Session or a Continue Session. |
| String - Site where the user interaction took place. |
| String - The user input that has generated this intent. |
| Object - Structured description of the intent classification, see Intent Classification below. |
| Optional Array of Objects - Structured description of the detected slots for this intent if any, see Slot below. |
| 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 |
| String - The name of the detected intent. |
| Number - The probability of the detection, between 0 and 1, 1 being sure. |
Key | Value |
| Number - Confidence of the slot, between 0 and 1, 1 being confident. |
| String - The raw value of the slot, as is was in the input. |
| String - The resolved value of the slot. |
| String - The entity of the slot. |
| String - The name of the slot. |
| Optional Object - The range where the slot can be found in the input. The object contains 2 integer fields: |
Key | Value |
| String - The value of the token |
| Number - Confidence of the token, between 0 and 1, 1 being confident |
| Integer - The start range in which the token is in the original input |
| Integer -The end range in which the token is in the original input |
| Object - Time when this token was detected. The object contains 2 Number fields: |
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() throwsfunc startSession(message: StartSessionMessage) throwsfunc startSession(text: String? = nil, intentFilter: [String]? = nil, canBeEnqueued: Bool = true, sendIntentNotRecognized: Bool = false, customData: String? = nil, siteId: String? = nil) throws// Usagelet 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.
Key | Value |
| Optional String - Site where to start the session |
| Object - Session initialization description: Action or Notification. See below |
| 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 |
Use this type when you need the end user to respond
Key | Value |
| "action" |
| Optional String - Text that the TTS should say at the beginning of the session. |
| 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. |
| Optional Array of Strings - A list of intents names to restrict the NLU resolution on the first query. |
| 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) |
Use this type when you only want to inform the user of something without expecting a response.
Key | Value |
| "notification" |
| String - Text the TTS should say |
You should subscribe tohermes/dialogueManager/sessionQueued
.
You should register a listener using setOnSessionQueuedListener
on 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.
Key | Value |
| String - Session identifier that was enqueued. |
| String - Site where the user interaction will take place. |
| Optional String - Custom data provided in the Start Session . |
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.
Key | Value |
| String - Session identifier that was started. |
| String - Site where the user interaction is taking place. |
| Optional String - Custom data provided in the Start Session . |
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]?) throwsfunc continueSession(message: ContinueSessionMessage) throws// Usagelet 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.
Key | Value |
| String - Identifier of the session to continue. |
| String - The text the TTS should say to start this additional request of the session. |
| 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. |
| Optional String - an update to the session's custom data. If not provided, the custom data will stay the same. |
| 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). |
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) throwsfunc endSession(message: EndSessionMessage) throws// Usagelet 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.
Key | Value |
| String - Identifier of the session to end. |
| 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.
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.
Key | Value |
| String - Session identifier of the ended session. |
| Optional String - Custom data provided in the Start Session or a Continue Session. |
| String - Site where the user interaction took place. |
| Object - Structured description of why the session has been ended. See below. |
Session Termination Type
Key | Value |
| String - the reason why the session was ended this can have the following values:
|
| Optional String - Error description if an error occurs during the session. |
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
Key | Value |
| String - Session identifier of the session that generated this intent not recognized event. |
| Optional String - Custom data provided in the Start Session or a Continue Session. |
| String - Site where the user interaction took place. |
| Optional String - The input, if any that generated this event. |