Hold a Conversation

This page describes the necessary steps to hold a conversation using the Conversational AI API.

In order for the Conversational AI API to maintain context, a reference of all dialog requests must be retained. In the first request, no reference parameters will be sent in the Sherpa-Request-Info request header, and in its response, a reference will be assigned in the response context object. All following requests must send the returned reference on the Sherpa-Request-Info request header.

Every time a conversation is started a new reference will be created.

Step 1: First dialog with the assistant

Do not enter a value in the Sherpa-Request-Info request header.

As an example, let's ask about the weather in Madrid:

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}" \
-H  "Accept-Language: en-US" \
-H  "Time-Zone: Europe/Madrid" \
-H  "accept: application/json" \
-H  "content-type: application/json" \
-d "{\"q\":\"What's the weather like in Madrid?\"}"

In the response, a numeric reference will be assigned in the ref field of the context object of the response. In this case, the value is 406367287.

{
    "nextActions": [
        {}
    ],
    "context": {
        "id": "ca74f2ca-f44b-4b59-83ad-2065f9390375",
        "ref": 406367287,
        "data": {
            "place": {
                "names": [
                    "Madrid"
                ],
                "weatherId": "cityid:308526"
            }
        }
    },
    "responses": {
        "audio": "https://api.sherpalive.com//v2/query/audio/315857",
        "html": "<!DOCTYPE html> <html> .... </html>",
        "query": "What's the weather like in Madrid?",
        "speech": "It is currently 89 degrees and mostly sunny in Madrid. The temperature will rise in the coming hours. Make sure to wear something lightweight and protect yourself from the strong sun today",
        "text": "It is currently 89 degrees and mostly sunny in Madrid. The temperature will rise in the coming hours. Make sure to wear something lightweight and protect yourself from the strong sun today"
    }
}

Step 2: Continue the dialog with the assistant

In the following requests, the reference will be included in the ref field of the Sherpa-Request-Info request header, so the dialogue can continue with the previous context.

In this example, weather intent was triggered in the first question, and now an ambiguous question ("And in Dublin?") is asked about another location. The intent is preserved by the context of the previous question and the slot place is updated to the new requested weather location, Dublin.

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\":406367287}" \
-H  "Accept-Language: en-US" \
-H  "Time-Zone: Europe/Madrid" \
-H  "accept: application/json" \
-H  "content-type: application/json" \
-d "{\"q\":\"and in Dublin?\"}"
{
    "nextActions": [
        {}
    ],
    "context": {
        "id": "f0fff368-43bc-457b-bb51-fd40a36152d4",
        "ref": 406367287,
        "data": {
            "place": {
                "names": [
                    "Dublin"
                ],
                "weatherId": "cityId:207931"
            }
        }
    },
    "responses": {
        "audio": "https://api.sherpalive.com//v2/query/audio/316327",
        "html": "<!DOCTYPE html> <html> ... </html>",
        "query": "and in Dublin?",
        "speech": "It is currently 57 degrees and cloudy in Dublin city. The temperature will rise in the coming hours",
        "text": "It is currently 57 degrees and cloudy in Dublin city. The temperature will rise in the coming hours"
    }
}