Request and Response Reference for Alexa Conversations

With Alexa Conversations, the JSON requests and responses that Alexa uses to communicate with your skill are very similar to the format described in the Request and Response JSON Reference for custom skills, with a few differences.

Request format

The only difference between Alexa Conversations requests and custom skill requests is that for Alexa Conversations, the request object is of type Dialog.API.Invoked and contains an apiRequest object.

Request body syntax

{
   "version": "1.0",
   "session": {},
   "context": {},
   "request": {
      "type": "Dialog.API.Invoked",
      "requestId": "...",
      "timestamp": "...",
      "locale": "...",
      "apiRequest" : {
         "name" : "Example API name",   
         "arguments" : {
            ...
         },
         "slots": {
            ...
         }  
      }     
   }
}
Field Description Type

type

The type of the request. For Alexa Conversations, the value is Dialog.API.Invoked.

string

requestId

A unique identifier for the specific request.

string

timestamp

The date and time that Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service (to avoid a replay attack). For details, see timestamp.

string

locale

A string that indicates the user's locale. Example: en-US. For details about locale codes, see Supported locale codes.

string

apiRequest.name

The name of the API invoked.

string

apiRequest.arguments

An object that contains the API request payload as a plain data object. For details, see arguments object.

object

apiRequest.slots

An object that contains resolutions and their values for given API request arguments. For details, see slots object.

object

arguments object

The arguments object is a plain request data object. It has the following rules:

  • The arguments object contains primitive values of each slot type that the API uses.
  • The arguments object follows the same structure as defined in the API definition.
  • The data types of the values depend on the slot type you use.
  • If Alexa Conversations can't resolve a spoken value into the associated slot type format, the argument value for that slot isn't set. For example, if the user says "seattle" to a slot SlotA of slot type AMAZON.NUMBER, the arguments object doesn't contain any value for SlotA because "seattle" can't be resolved to a number value. Instead, the unresolved string value "seattle" would be present in SlotA of the slots object.

slots object

When sending values inside the apiRequest.slots object, Alexa Conversations follows existing slot and entity resolution rules for spoken values (if any). The slots object contains slot values and their corresponding resolutions.

Values are present in the slots object based on the following rules:

  • Slot values are present for all simple slots.

Resolutions are present in the slots object based on the following rules:

  • Alexa Conversations currently doesn't support resolutions for complex slots or list slots, so no entity resolutions are present for those types of slots.
  • No entity resolutions are present for formatter-based slot types like AMAZON.DATE and AMAZON.TIME.
  • No entity resolutions are present for built-in catalog-based slot types like AMAZON.US_CITY if there are no extended custom catalog values.
  • Entity resolutions are present in the slots object only for simple slot types and only if they are spoken.

Example

For this example, the skill API has the following schema:

// API schema 
{
    "apiName": "BookMovieTicket",
    "arguments": {
        "movie" : {
            "type" : "Movie"
        },
        "partySize" : {
            "type" : "AMAZON.NUMBER"
        },
        "preferredShowTimes" : {
            "type" : "List<AMAZON.TIME>"
        },
        "preferredTheaters": {
            "type": "List<Theater>"
        }
    },
    "returns": {
        "type" : "BookingResult"
    }
}

In this case, the Dialog.API.Invoked request to the skill is as follows.

{
    "version" : "1.0",          
    "session" : {
        "attributes" : {},
        ..
    },             
    "context" : {},             
    "request" : {               
        // Standard fields        
        "type" : "Dialog.API.Invoked",
        "requestId" : "...",
        "timestamp" : "..",
        "locale" : "..",
        // Alexa Conversations-specific
        "apiRequest" : {
            "name" : "BookMovieTicket",         // API Name
            "arguments" : {
              "movie" : "Example movie name",   // Custom slot type (Movie)
              "partySize" : 4,                  // AMAZON.NUMBER 
              "preferredShowTimes": [           // List<AMAZON.TIME>
                "12:00",
                "16:00",
                "21:00"
              ],
              "preferredTheaters": [            // List of custom slot type (Theater)
               {
                 "name": "myValue",
                 "address": "myValue"
               }
             ]
           },
           // A slot has a value if it's a simple 
           // slot type and the value is spoken. 
           "slots": {
             "movie": {
               "type": "Simple",
               "value": "Example movie name",
               "resolutions": { .. }
             },
             "partySize": {
               "type": "Simple",
               "value": "4"
             }
          }  
       }  
    }
}

Response format

For Alexa Conversations, the response object can either include an apiResponse object or a Dialog.DelegateRequest directive (not both). The schema for a response with an apiResponse object is as follows.

{
   "version" : "1.0",
   "sessionAttributes": {},
   "response" : {
      "apiResponse" : {
        "key1": "value1",
        "key2": {},
        "key3": []
       }
   } 
}

Response body syntax

Field Description Type Required

version

The version specifier for the response. Value: "1.0".

string

Yes

response

A response object that defines what to render to the user and whether to end the current session.

object

Yes

response.apiResponse

An API response entity object along with values defined by the skill during the build time.

object, list, string, or number

Yes

Examples

The following examples show responses that contain an apiResponse object.

Example 1

{
   "version" : "1.0",
   "sessionAttributes": {},
   "response" : {
      "apiResponse" : {
        "movieShows": [
          {
            "movieId" : "movie-1",
            "availableSeats" : 4,
            "movieTime" : "12:00"
          },
          {
            "movieId" : "movie-2",
            "availableSeats" : 2,
            "movieTime" : "16:00"
          }
        ]
      }
   } 
}

Example 2

{
   "version" : "1.0",
   "sessionAttributes": {},
   "response" : {
      "apiResponse" : {
        "orderStatus" : "submitted",
        "pickupOrDelivery" : "pickup",
        "toppings": [
            "olives", "green peppers", "pineapple"
        ],
        "orderTime": "14:00"
      }
   } 
}

Response handling

The only directive you can return with an apiResponse object is the Dialog.DelegateRequest directive. This way, you can delegate dialog management to your skill and return the standard custom skill response. For the next turn, the request goes to the skill, and you need to delegate back to Alexa Conversations if you want Alexa Conversations to handle the dialog.

When you return a response to Dialog.API.Invoked, follow the following rules:

  • For the Alexa Conversations model to keep predicting the next actions in a dialog, return an apiResponse object.
  • To transfer dialog management control to the skill, return a Dialog.DelegateRequest directive.
  • When returning a response to a Dialog.API.Invoked request, you must only return either an apiResponse object or a Dialog.DelegateRequest directive in the response object.
  • You must not return both an apiResponse object and a Dialog.DelegateRequest directive.
  • You can set data in the sessionAttributes object. The sessionAttributes object is outside of the response object in the response JSON envelope.
  • The apiResponse object must match the schema of the API that got invoked.
  • Values in the apiResponse object must match the slot type format you are using. For example, if you're returning a value to AMAZON.DATE (a formatter-based slot type), the value you return must be an AMAZON.DATE format such as 2020-01-01. Similarly, for catalog-based slots, you can return any string value.

The following example returns a normal API response:

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "apiResponse": {
      "orderStatus": "submitted",
      "pickupOrDelivery": "pickup",
      ...
    }
  }
}

If you want a directive or any other response objects during a dialog, you must first delegate back to your skill.

The following response delegates dialog management to your skill.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
        "type":"Dialog.DelegateRequest",
        ..
      }
    ]
  }
}

You then return the response you want to render as follows.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
        "type":"AudioPlayer.Play",
        ..
      }
    ]
  }
}

After you're finished, you can transfer control back to Alexa Conversations by using the same Dialog.DelegateRequest directive as follows.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
        "type":"Dialog.DelegateRequest",
        "target" : "AMAZON.Conversations",
        "period": {
           "until": "EXPLICIT_RETURN"
        },        
        "updatedRequest": {..}
        ..
      }
    ]
  }
}