Hand off Dialog Management to and from Alexa Conversations

You can have Alexa Conversations handle all or part of the dialog management for a skill that uses intent-based dialog management.

To hand off dialog management, you send a Dialog.DelegateRequest directive in response to a request from Alexa. The details of this directive depend on whether you want to switch from the intent-based dialog manager to Alexa Conversations, or vice versa.

In any case, you can save session attributes, such as the dialog state, in the same response.

Hand off dialog management from your skill to Alexa Conversations

To hand off dialog management from your skill to Alexa Conversations, send a Dialog.DelegateRequest to Alexa from an intent handler. Specify the utterance set to which Alexa Conversations should map the intent, and pass the slots to Alexa Conversations.

Dialog.DelegateRequest has the following format.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
         "type": "Dialog.DelegateRequest",
         "target": "AMAZON.Conversations",
         "period": {
            "until": "EXPLICIT_RETURN"
         },
         "updatedRequest": {
            "type": "Dialog.InputRequest",
            "input": {
               "name": "<utteranceSetName>",  // Utterance set must use the Invoke APIs dialog act
               "slots": {
                  "<slotName1>": {
                     "name": "<slotName1>",
                     "value": "<slotValue1>"
                  },
                  "<slotName2>": {
                     "name": "<slotName2>",
                     "value": "<slotValue2>"
                  },
                  ...
               }
            }
         }
      }
    ]
  }
}

Hand off dialog management from Alexa Conversations to your skill

To hand off dialog management from Alexa Conversations to your skill, send a Dialog.DelegateRequest in response to a Dialog.API.Invoked request. Specify the intent to use as the entry point to your skill, and pass the slot values that the intent needs. In this case, Dialog.DelegateRequest has the following format.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
         "type": "Dialog.DelegateRequest",
         "target": "skill",
         "period": {
            "until": "EXPLICIT_RETURN"
         },
         "updatedRequest": {
            "type": "IntentRequest",
            "intent": {
               "name": "<intentName>",
               "slots": {
                  "<slotName1>": {
                     "name": "<slotName1>",
                     "value": "<slotValue1>"
                  },
                  "<slotName2>": {
                     "name": "<slotName2>",
                     "value": "<slotValue2>"
                  },
                  ...
               }
            }
         }
      }
    ]
  }
}

Dialog.DelegateRequest parameters

The parameters of Dialog.DelegateRequest are as follows.

Field Description Type Required

type

The name of this directive. Set to Dialog.DelegateRequest.

String

Yes

target

The dialog manager to switch to. Valid values:

  • AMAZON.Conversations: Hand off dialog management to Alexa Conversations.
  • skill: Hand off dialog management to the skill.

String

Yes

period

The delegation period.

Object

Yes

period.until

The end of the delegation period. Valid values:

  • EXPLICIT_RETURN: Delegation lasts until the skill sends a Dialog.DelegateRequest directive with a new target.

String enum

Yes

updatedRequest

The request to delegate. Set to null to delegate the current request.

Object

No

updatedRequest.type

The type of request to delegate. Valid values:

  • Dialog.InputRequest: Use this value when handing off dialog management to Alexa Conversations.
  • IntentRequest: Use this value when handing off dialog management to the skill.

String

Yes

updatedRequest.input

The utterance set to use for the Alexa Conversations dialog management model.

Object

Yes

updatedRequest.input.name

The name of the utterance set.

String

Yes

updatedRequest.input.slots

A map of input slots by slot name.

Object

No

updatedRequest.intent

The intent to use when switching the dialog manager to the skill.

Object

Yes

updatedRequest.intent.name

The name of the intent to use when switching the dialog manager to the skill.

String

Yes

updatedRequest.intent.slots

A map of input slots by slot name.

Object

No

Session attributes

You can save session attributes, such as the dialog state, by specifying sessionAttributes in the same response.

The following example shows how to pass session attributes when handing off dialog management to Alexa Conversations.

{
  "version": "1.0",
  "sessionAttributes": {
    "key-1": "value-1",
    "key-2": "value-2",  
    ... 
  },
  "response": {  
     "directives": [
       {
          "type": "Dialog.DelegateRequest",
          "target": "AMAZON.Conversations",
          "period": {
             "until": "EXPLICIT_RETURN"
          }
       }
     ]
  }     
}

The following example shows how to pass session attributes when handing off dialog management to your skill.

{
  "version": "1.0",
  "sessionAttributes": {
    "key-1": "value-1",
    "key-2": "value-2",  
    ... 
  },
  "response": {    
     "directives": [
       {
          "type": "Dialog.DelegateRequest",
          "target": "skill",
          "period": {
             "until": "EXPLICIT_RETURN"
          }
       }
     ]
  }  
}

Examples of handing off dialog managment from your skill to Alexa Conversations

The following examples show how to switch the dialog manager to Alexa Conversations with slots, without slots, and with the current utterance.

Example with slots

The following example delegates dialog management to Alexa Conversations and passes the slots to Alexa Conversations.

{
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
        "directives": [
            {
                "type": "Dialog.DelegateRequest",
                "target": "AMAZON.Conversations",
                "period": {
                    "until": "EXPLICIT_RETURN"
                },
                "updatedRequest": {
                    "type": "Dialog.InputRequest",
                    "input": {
                        "name": "SetAllFavoriteFoodsUtteranceSet",
                        "slots": {
                            "breakfast": {
                                "name": "breakfast",
                                "value": "waffles"
                            },
                            "lunch": {
                                "name": "lunch",
                                "slotValue": {
                                    "type": "Simple",
                                    "value": "p. b. and j."
                                }
                            },
                            "dinners": {
                                "name": "dinners",
                                "slotValue": {
                                    "type": "List",
                                    "values": [
                                        {
                                            "type": "Simple",
                                            "value": "stuffed peppers"
                                        },
                                        {
                                            "type": "Simple",
                                            "value": "pizza"
                                        },
                                        {
                                            "type": "Simple",
                                            "value": "chicken cacciatore"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        ]
    }
}

Example without slots

The following example delegates dialog management to Alexa Conversations, and there are no slots to pass.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
         "type": "Dialog.DelegateRequest",
         "target": "AMAZON.Conversations",
         "period": {
            "until": "EXPLICIT_RETURN"
         },
         "updatedRequest": {
            "type": "Dialog.InputRequest",
            "input": {
               "name": "<utteranceSetName>"
            }
         }
      }
    ]
  }
}

Example of sending the current utterance as input

The following example delegates dialog management to Alexa Conversations, and because updatedRequest isn't present, the current utterance is used as the input to Alexa Conversations.

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

Examples of handing off dialog management from Alexa Conversations to your skill

The following examples show how to switch the dialog manager to your skill with and without slots.

Example with slots

The following example delegates dialog management to your skill and passes slots to the intent.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
         "type": "Dialog.DelegateRequest",
         "target": "skill",
         "period": {
            "until": "EXPLICIT_RETURN"
         },
         "updatedRequest": {
            "type": "IntentRequest",
            "intent": {
               "name": "<intentName>",
               "slots": {
                  "<slotName1>": {
                     "name": "<slotName1>",
                     "value": "<slotValue1>"
                  },
                  "<slotName2>": {
                     "name": "<slotName2>",
                     "value": "<slotValue2>"
                  }
               }
            }
         }
      }
    ]
  }
}

Example without slots

The following example delegates dialog management to your skill to an intent without slots.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
         "type": "Dialog.DelegateRequest",
         "target": "skill",
         "period": {
            "until": "EXPLICIT_RETURN"
         },
         "updatedRequest": {
            "type": "IntentRequest",
            "intent": {
               "name": "<intentName>"
            }
         }
      }
    ]
  }
}
Was this page helpful?

Last updated: Nov 27, 2023