Response Actions
Here are some examples of dialog response actions.
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.
curl --location --request POST 'https://api.sherpa.ai/v2/query/text' \
--header 'Accept-Language: en-US' \
--header 'authorization: Basic XXXX-SHERPA-TOKEN-XXXX' \
--header 'Content-Type: application/json' \
--header 'Time-Zone: Europe/Madrid' \
--data-raw '{
"q": "set an appointment"
}'
{
"nextActions": [{"action": "OPEN_ASR"}],
"context": {"ref": 12345},
"responses": {
"query": "set an appointment",
"text": "Please tell me the time and date of the event"
}
}
The following conversation requests must include the ref
attribute in the RequestInfo.
SET_ALARM
Set an alarm.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Set an alarm in 30 minutes\"}"
{ "context": {"ref": 12345},
"nextActions": [{
"action": "SET_ALARM",
"data": { "time": "1548762000000"}}],
"responses": {
"query": "Set an alarm in 30 minutes",
}}
DELETE_ALARM
Delete a previously set alarm.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Remove the 1 PM alarm\"}"
{ "context": {"ref": 12345},
"nextActions": [{
"action": "DELETE_ALARM",
"data": { "time": "1548763200000"}}],
"responses": {
"query": "Remove the 1 pm alarm",
}}
SET_TIMER
Set a timer.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Set the timer for 10 minutes\"}"
{ "context": {"ref": 12345},
"nextActions": [{
"action": "SET_TIMER",
"data": { "time": "00:10:00" }}],
"responses": {
"query": "Set the timer for 10 minutes",
}}
SET_CRONO
Use a stopwatch.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Start the stopwatch\"}"
{ "context": {"ref": 12345},
"nextActions": [{ "action": "SET_CRONO"}}],
"responses": {
"query": "Start the stopwatch",
"text": "Here you go."
}}
SET_APPOINTMENT
Appointments can be set in a single command or through a dialogue chain, where Sherpa.ai asks the user for details such as date, title, location, etc. Upon confirmation by the user, the action is received.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Create an appointment with the title Go to Vinyasa Yoga for today at 8\"}"
{"context": {"ref": 12345},
"nextActions": [{
"action": "SET_APPOINTMENT",
"data": {
"startDate": "1544076000000",
"endDate": "1544079600000",
"subject": "Go to Vinyasa Yoga",
"place": ""
}}],
"responses": {
"query": "Create an appointment with the title Go to Vinyasa Yoga for today at 8",
"text": "Done!"
}}
PLAY_MUSIC
Play music by title, artist, genre, etc.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Play a song by Prodigy\"}"
{"context": { "ref": 12345 },
"nextActions": [{
"action": "PLAY_MUSIC",
“data”: { “url”: “http://.../song.mp3"}}],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/19283426",
"query": "Play a song by Prodigy",
"text": "Playing music by \"Prodigy\"."
}}
MAKE_CALL
Make a phone call. Contact name or phone number must be provided, in order to perform the action.
curl --location --request POST 'https://api.sherpa.ai/v2/query/text' \
--header 'Accept-Language: en-US' \
--header 'authorization: Basic XXXX-SHERPA-TOKEN-XXXX' \
--header 'Content-Type: application/json' \
--header 'Time-Zone: Europe/Madrid' \
--data-raw '{"q": "Call john Smith"}'
{
"nextActions": [{
"action": "MAKE_CALL",
"data": {"contact": {"name": "john Smith"}}}],
"context": {"ref": 12345},
"responses": {"query": "Call john Smith"}
}
curl --location --request POST 'https://api.sherpa.ai/v2/query/text' \
--header 'Accept-Language: en-US' \
--header 'authorization: Basic XXXX-SHERPA-TOKEN-XXXX' \
--header 'Content-Type: application/json' \
--header 'Time-Zone: Europe/Madrid' \
--data-raw '{"q": "Call 666 777 888"}'
{
"nextActions": [{
"action": "MAKE_CALL",
"data": {"contact": {"number": "666777888"}}}],
"context": {"ref": 12345},
"responses": {"query": "Call 666 777 888"}
}
VOLUME_UPDATE
Increase, decrease, or set device volume to a specific percentage.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Increase volume\"}"
{ "nextActions": [{
"action": "VOLUME_UPDATE",
"data": {"value": "+1"}}],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/20803",
"query": "OK, I'll turn the volume up.",
"text": "OK, I'll turn the volume up."
}}
BRIGHTNESS_UPDATE
Increase, decrease, or set device brightness to a specific percentage.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"make it brighter\"}"
{ "nextActions": [{
"action": "BRIGHTNESS_UPDATE",
"data": { "value": "+1"}}],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/2019_03_26_f495ab5a-e73e-4f0d-aea6-bba72cdbdb77.mp3",
"query": "make it brighter",
"speech": "OK, I'll increase the brightness.",
"text": "OK, I'll increase the brightness."
}}
ACTIVATE
Toggles ON specific device controllers, such as wifi, webcam, etc.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"turn webcam on\"}"
{ "nextActions": [{
"action": "ACTIVATE",
"data": {
"value": "webcam"}}],
"responses": {
"audio": "https://sherpa-speech-audio.s3.amazonaws.com/2019_03_28_aaea0f98-4733-435d-9ae0-6690901b8c99.mp3",
"query": "turn webcam on",
"speech": "OK, I'll turn the webcam on.",
"text": "OK, I'll turn the webcam on."
}}
DEACTIVATE
Toggles OFF specific device controllers.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"turn wifi off\"}"
{"nextActions": [{
"action": "DEACTIVATE",
"data": {
"value": "wifi"}}],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/2019_03_26_c3233dfc-7619-406d-a006-74bde12530fc.mp3",
"query": "turn wifi off",
"speech": "OK, I'll turn the wi-fi off.",
"text": "OK, I'll turn the wi-fi off."
}}
OPEN_APP
Opens the specified application.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"open skype\"}"
{"nextActions": [{
"action": "OPEN_APP",
"data": { "value": "skype"}}],
"responses": {
"query": "open skype"
}}
OPEN_URL
Opens a URL in a browser.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Open marca.com\"}"
{ "nextActions": [{
"action": "OPEN_URL",
"data": "http://marca.com"}],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/20808",
"query": "Open marca.com",
"text": "OK, I'll load http://marca.com."
}}
NAVIGATE
Opens client navigation application to get directions.
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\":12345}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"q\":\"Take me to Bilbao by car.\"}"
{ "nextActions": [{
"action": "NAVIGATE",
"data": {
"destination": {
"destinationName": "bilbao",
"transportType": "d"
}}}],
"responses": {
"audio": "https://api.sherpa.ai/v2/query/audio/20800",
"query": "I want to go to Bilbao by car.",
"text": "Here is a route that you can take."
}}