Dialogue System
Text Query
POST /query/text
Ask Sherpa.ai about something, using text.
Headers
Request Header | Mandatory | Description |
---|---|---|
Authorization | ✓ | An authentication type followed by an access token. ex: Basic 73dbb14a-50d9-4277-897e-6cb48258d258 See Authentication section. |
Sherpa-Request-Info | Specific Sherpa.ai header where parameters are grouped in the form of a RequestInfo JSON object. Header necessary if the request refers to a previous conversation. Also necessary in order to adjust results based on user location. |
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
q | Body | ✓ | String | Query |
If the request refers to a previous conversation, the reference will be communicated through the request headers.
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
429 | Too Many Requests |
500 | Internal Server Error |
The structure of the text response (JSON) corresponds to the format described in the response format section.
curl -X POST "https://api.sherpa.ai/v2/query/text" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX" \
-H "Sherpa-Request-Info:{\"lat\":43.3017218,\"lon\":-2.9735617,\"ref\":342673096}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d "{\"q\":\"Are there any concerts tonight?\"}"
{
"context": {
"ref": 342673096
},
"nextActions": [
{
"data": ""
}
],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/119275556",
"query": "Are there any concerts tonight?",
"text": "If you're looking to do something different, 2020 DATA SCIENCE&INTELLIGENT SYSTEMS CONFERENCE; The British Invasion; and iSing Summer Camp June 15 19 are happening in Palo Alto"
}
}
Get Audio
GET /query/audio/{id}
Although dialogue requests are carried out in text format (text is sent and text is received), the response format always includes an "audio" field with the streaming server URL, which will return audio of the text.
For this endpoint, it is not necessary to use a request header. This service response can be delegated directly to the multimedia player installed in the client device.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
id | query | ✓ | Integer | ID of audio to be played |
Response
Code | Name |
---|---|
200 | OK |
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
500 | Internal Server Error |
curl -X GET "https://api.sherpa.ai/v2/query/audio/2223"
Audio Query
POST /query/audio/data
With this endpoint, an audio request is made to Sherpa.ai and a text response is received.
Headers
Take into account the following request headers:
Request Header | Mandatory | Description |
---|---|---|
Authorization | ✓ | An authentication type, followed by an access token. ex: Basic 73dbb14a-50d9-4277-897e-6cb48258d258 See Authentication section. |
Content-Type | ✓ | Allowed values are audio/x-wav;codec=pcm;bit=16;rate=8000 , audio/x-wav;codec=pcm;bit=16;rate=16000 |
Sherpa-Request-Info | Specific Sherpa.ai header where parameters are grouped in the form of a RequestInfo JSON object. Header necessary if the request refers to a previous conversation. Also necessary in order to adjust results based on user location. |
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
data | Body | ✓ | Audio bytes | Audio in wav format |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
500 | Internal Server Error |
The structure of the response in text format (JSON) corresponds to the format detailed in the response format section.
curl -X POST "https://api.sherpa.ai/v2/query/audio/data" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX" \
-H "Sherpa-Request-Info:{\"lat\":43.3017218,\"lon\":-2.9735617}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: audio/x-wav;codec=pcm;bit=16;rate=16000" \
--data-binary "concerts.wav"
{
"context": {
"ref": 342673096
},
"nextActions": [
{
"data": ""
}
],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/19275556",
"query": "Are there any concerts tonight?",
"text": "If you're looking to do something different, 2020 DATA SCIENCE&INTELLIGENT SYSTEMS CONFERENCE; The British Invasion; and iSing Summer Camp June 15 19 are happening in Palo Alto"
}
}
Streaming Query
POST /query/audio/stream
Using this endpoint, an audio request is made to Sherpa.ai and an audio response is received.
Headers
Request Header | Mandatory | Description |
---|---|---|
Authorization | ✓ | An authentication type, followed by an access token. ex: Basic 73dbb14a-50d9-4277-897e-6cb48258d258 See Authentication section. |
Content-Type | ✓ | Allowed values are audio/x-wav;codec=pcm;bit=16;rate=8000 , audio/x-wav;codec=pcm;bit=16;rate=16000 |
Accept | ✓ | Allowed values are application/octet-stream |
Sherpa-Request-Info | ✓ | Specific Sherpa.ai header where parameters are grouped in the form of a RequestInfo JSON object. Header necessary if the request refers to a previous conversation. Also necessary in order to adjust results based on user location. |
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
data | Body | ✓ | Audio bytes | Audio in wav format |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
500 | Internal Server Error |
The response will be in audio streaming format, which can be sent directly to the media player installed in the client device.
In this case, the text format response will also be received within the response header.
curl -X POST "https://api.sherpa.ai/v2/query/audio/stream" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX" \
-H "Sherpa-Request-Info:{\"lat\":43.3017218,\"lon\":-2.9735617}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/octet-stream" \
-H "Content-Type: audio/x-wav;codec=pcm;bit=16;rate=8000" \
--data-binary "@QueHoraEs_8000.wav"
Response Headers
Header | Value |
---|---|
Chunked | 1 |
Transfer-encoding | chunked |
Content-Type | application/octet-stream |
Sherpa-Response-Info | json |
Response
The responses from conversations with Sherpa.ai will always return information in a hierarchical JSON structure.
In text format requests, the response will be turned over directly to the client. In the event of audio requests, the hierarchical structure will be included in the response header (Sherpa-Response-Info). In both cases, the structure will follow a single format:
Field | Type | Description |
---|---|---|
context | Dialogue context data | |
id | String | Sherpa.ai's response-unique ID |
ref | Long | Dialogue's reference ID |
responses | Alternative response formats. The response content is dependent upon the API’s users. | |
html | String | Response html |
text | String | Text to be written |
speech | String | Text to be spoken using the TTS |
audio | String | URL of the audio/mp3 that will contain audio response |
next_action | Next action to execute on the client side (optional) | |
action | String | Next Actions code |
data | Necessary data to execute the action. See Next Actions section. |
Next Actions
The possible Next Actions are dependent upon the client that is using the Sherpa.ai API.
Domain | Action | Context |
---|---|---|
* | OPEN_ASR | When this action occurs, it means the dialogue is to continue and that Sherpa.ai requires some client-side interaction in order to proceed. The following conversation requests must include the ref attribute in the RequestInfo. |
Alarm | SET_ALARM DELETE_ALARM | Set / delete an alarm |
Timer | SET_TIMER | Set / reset timer |
Crono | SET_CRONO | Set / reset stopwatch |
RESET_CRONO | ||
Calendar | SET_APPOINTMENT | New calendar event |
Music Search | PLAY_MUSIC | Play a song |
Device Control | POWER | Turn on / off a device |
CHANNEL_SELECT | Change TV channel | |
MAKE_CALL | Name of contact to call | |
VOLUME_UPDATE | Change the volume settings | |
BRIGHTNESS_UPDATE | Change the brightness settings | |
ACTIVATE DEACTIVATE | Activate / deactivate specific device controller (webcam, wifi, etc.) | |
Apps | OPEN_APP | App to be opened |
OPEN_BROWSER | Open browser | |
OPEN_URL | Open URL | |
NAVIGATE | Destination | |
SMS | SEND_SMS | SMS content |
SEND_EMAIL | Email content |