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
  • Request body syntax
    • arguments object
    • slots object
  • Example 1
  • Example 2
• Response format
  • Response body syntax
  • Examples
  • Response handling
• Related topics

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

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.
• Alexa Conversations follows the same slot-type extension rules as other custom skills. For details, see Slot types that you extend.
• Entity resolutions are present in the slots object only for simple slot types and only if they are spoken.

Example 1

The following example is a complete Dialog.API.Invoked request that you can use for testing.

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.12345678",
    "application": {
      "applicationId": "amzn1.ask.skill.12345678"
    },
    "attributes": {},
    "user": {
      "userId": "amzn1.ask.account.testUser"
    }
  },
  "context": {},
  "request": {
    "type": "Dialog.API.Invoked",
    "requestId": "amzn1.echo-api.request.1234",
    "timestamp": "2021-05-25T21:06:28Z",
    "locale": "en-US",
    "apiRequest": {
      "name": "PlaceholderAPI",
      "arguments": {
        "argument1": "Test"
      }
    }
  }    
}

Example 2

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": []
       },
       "shouldEndSession": true|false|null       
   } 
}

Response body syntax

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"
          }
        ]
      },
     "shouldEndSession": false      
   } 
}

Example 2

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

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": {..}
        ..
      }
    ]
  }
}

Related topics

• About Alexa Conversations
• Handle API Calls for Alexa Conversations
• Hand off Dialog Management to and from Alexa Conversations

Last updated: Nov 27, 2023