Dialogue System

Text/Audio requestes served in Text/Audio responses

Text Query

POST /query/text

Ask Sherpa.ai about something, using text.

Headers

Request HeaderMandatoryDescription
AuthorizationAn authentication type followed by an access token.
ex: Basic 73dbb14a-50d9-4277-897e-6cb48258d258
See Authentication section.
Sherpa-Request-InfoSpecific 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

FieldSourceMandatoryTypeDescription
qBodyStringQuery

If the request refers to a previous conversation, the reference will be communicated through the request headers.

Response

CodeName
200OK
400Bad Request
401Unauthorized
403Forbidden
429Too Many Requests
500Internal 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

FieldSourceMandatoryTypeDescription
idqueryIntegerID of audio to be played

Response

CodeName
200OK
204No Content
400Bad Request
401Unauthorized
403Forbidden
500Internal 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 HeaderMandatoryDescription
AuthorizationAn authentication type, followed by an access token.
ex: Basic 73dbb14a-50d9-4277-897e-6cb48258d258
See Authentication section.
Content-TypeAllowed values are audio/x-wav;codec=pcm;bit=16;rate=8000, audio/x-wav;codec=pcm;bit=16;rate=16000
Sherpa-Request-InfoSpecific 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

FieldSourceMandatoryTypeDescription
dataBodyAudio bytesAudio in wav format

Response

CodeName
200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal 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 HeaderMandatoryDescription
AuthorizationAn authentication type, followed by an access token.
ex: Basic 73dbb14a-50d9-4277-897e-6cb48258d258
See Authentication section.
Content-TypeAllowed values are audio/x-wav;codec=pcm;bit=16;rate=8000, audio/x-wav;codec=pcm;bit=16;rate=16000
AcceptAllowed values are application/octet-stream
Sherpa-Request-InfoSpecific 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

FieldSourceMandatoryTypeDescription
dataBodyAudio bytesAudio in wav format

Response

CodeName
200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal 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

HeaderValue
Chunked1
Transfer-encodingchunked
Content-Typeapplication/octet-stream
Sherpa-Response-Infojson

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:

FieldTypeDescription
contextDialogue context data
 idStringSherpa.ai's response-unique ID
 refLongDialogue's reference ID
responsesAlternative response formats. The response content is dependent upon the API’s users.
 htmlStringResponse html
 textStringText to be written
 speechStringText to be spoken using the TTS
 audioStringURL of the audio/mp3 that will contain audio response
next_actionNext action to execute on the client side (optional)
 actionStringNext Actions code
 dataNecessary 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.

DomainActionContext
*OPEN_ASRWhen 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.
AlarmSET_ALARM
DELETE_ALARM
Set / delete an alarm
TimerSET_TIMERSet / reset timer
CronoSET_CRONOSet / reset stopwatch
RESET_CRONO
CalendarSET_APPOINTMENTNew calendar event
Music SearchPLAY_MUSICPlay a song
Device ControlPOWERTurn on / off a device
CHANNEL_SELECTChange TV channel
MAKE_CALLName of contact to call
VOLUME_UPDATEChange the volume settings
BRIGHTNESS_UPDATEChange the brightness settings
ACTIVATE
DEACTIVATE
Activate / deactivate specific device controller (webcam, wifi, etc.)
AppsOPEN_APPApp to be opened
OPEN_BROWSEROpen browser
OPEN_URLOpen URL
NAVIGATEDestination
SMSSEND_SMSSMS content
EmailSEND_EMAILEmail content