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."
  }}