Integration documentation
Overview
Comandor is a SaaS with REST interface that allows to send voice or text messages in order to detect preconfigured Commands and run associated Actions. Voice or text should contain specific data, depending on the Command, in order for it to be detected.
If this data is missing Comandor will return clarification questions (configured) asking for this data. Otherwise, it will run associated Actions and return its’ output, success or error messages. It’s up to the consumer App, how to utilize returned data.
There are a set of rudimentary Actions (call API, Return text, send Email) that will run once appropriate Command is detected.
- To run more complex Command Actions (flows) we recommend calling API Action that will trigger it.
- To run chat conversation should be utilized Return text Action.
To make it work the following API should be consumed.
API
To process voice or text requests, should be used the following API:
POST api/command/parse/
Request
With the following parameters:
- session_id – bot user ID (if known) or null
- language – text or voice language (if known) or null
- file – audio file for parsing (if it’s available for sending)
- source_text – text for parsing (if it’s available for sending)
Response
This API returns a response in the following format:
{
"session_id": "string",
"language": "string",
"source_text": "string",
"result": {},
"errors": []
}
Usage
API response contains the following parameters, that can be utilized (marked with comment in the code) as follow:
- “session_id” – bot user Id / session Id that was sent or generated while processing the request
– this value should be sent with the following clarification requests (see details below about clarification)
- “language” – input text or voice detected language
– this value should be sent with all the following requests if conversation language will not change in time
- “source_text” – text parsed from the input audio or text
- “errors” returns a list of errors that occurred while processing the request or an empty list. It has the following structure:
"errors": [
{
"error_message": "string”, // can be utilized
"error_code": "string”
}
]
– “error_message” – message of the error, occurred while processing the request
– should be exposed in the interface for further user interaction.
– “error_code” – code of the error, occurred while processing the request
- “result” returns the result of processing the request. It has the following structure:
"result": {
"command": {
"name":"string",
"language":"string",
"params": [],
"actions": [
{
"name": "string",
"executed": "bool",
"result": {
"success_message":"string ", // can be utilized
"error_message":“string”, // can be utilized
"error_code": int,
"output":"string" // can be utilized
}
}
]
},
"clarifications":[] // can be utilized
}
- “error_message” – message of the Action error (configured string)
– should be exposed in the interface for further user interaction.
- “success_message” – message of the succeed Action (configured string)
– should be exposed in the interface for further user interaction.
- “output” – output result/response of succeed Action
– should be exposed in the interface for bot-type communication, for other cases can be exposed if output is valuable (should be defined according to the needs of the Application).
- “clarifications“ – questions to clarify missing parameters for the command
– should be exposed in the interface for further user interaction in order to detect Command and run appropriate Actions.
