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
Email	SEND_EMAIL	Email content