Request Response (Alexa) v3.0.4 Help ​

Delivers a message, then waits for Alexa to recognize in the end user's response either an intent or a value for a specific slot in the selected intent.

Note: Steps of the Alexa toolkit work only with existing custom Alexa skills with the method to host your skill's backend resources selected as Provision your own. The skill interaction model must be built with intents and slots on the Amazon developer colsole prior to building solutions with the Alexa toolkit.

How can I use the Step? ​

You can use this Step either to take the Flow down a specific exit depending on the intent in the end user's response or to request a value for a specific slot.

Select the Intent option to make sure that the end user's intent is understood correctly. The Slot value option can be useful for defining a particular slot value of the selected intent.

How does the Step work? ​

First, you select an authorization and a skill. Then you define whether you request an intent or a slot value, and specify the respective values. After you define the message content.

When Alexa delivers the defined message to the end user and receives their response, the following happens:

For the Intent option:

• If Alexa recognizes the intent in the end user's response and it matches one of the specified intents in the Step, the Flow proceeds down the respective exit.
• If the recognized intent does not match a specified intent, the Flow proceeds down the other exit.

For the Slot value option:

• If a value for the specified slot is recognized in the end user's response, the Flow proceeds down the next exit.

This Step also allows handling situations when Alexa cannot understand the end user's response correctly or when Alexa or the end user ends the current session.

Prerequisites ​

Before building Flows using the Alexa toolkit, you must complete the following steps:

1. Create a Custom Alexa skill with at least one intent in the Amazon developers console. Read more on how to create Alexa skills here.
2. Install the Alexa Skill Adapter flow. See the instruction here.
3. Create an authorization of your OneReach.ai account with the Amazon developer account. See the instructions in the Add an authorization modal of the Authorization section of an Alexa Step.

Alexa Skill Adapter Flow ​

The Alexa Skill Adapter Flow is required to manage the interactions between OneReach.ai and the Amazon developer console. To install it take the following steps:

1. Add any gateway Step template from the Alexa toolkit to the Flow. For example, a Wait for Intent (Alexa) Step.
2. Go to the Details tab of the added Step. The Authorization collapsible group contains a warning message with the Install Adapter button. Click to install the adapter Flow. After the installation is completed, a respective message should appear.

Note: In case Alexa Skill Adapter Flow is deactivated or deleted, a respective alert will pop up in the gateway Step of the Flow with a button to fix the problem.

Authorization ​

To set up an authorization, select one of the two options:

• Click the Select authorization in current step option to select an authorization from the respective dropdown in this Step. Use this option when you need to:
  • Create new authorization;
  • Select a previously created authorization manually.
• Select the Inherit from previous step option to choose the authorization that was used in the last executed Step of the Alexa toolkit in the Flow. Use this option when you have already created an authorization and used it previously in the Flow.

Create a new authorization ​

To create a new authorization, do the following:

1. Click the Select authorization in current step button.
2. Click the Gear button, then Add, or select to Create new authorization in the dropdown.
3. A modal window for creating a new authorization will pop up. Follow the instructions in the modal's collapsible. When finished, the created Authorization name should be added to the list in the dropdown. Click Gear > Refresh to update the list of authorizations.
4. Select respective Authorization name in the Select authorization in current step dropdown.

Select authorization in current step ​

The Select authorization in current step dropdown lists every authorization added to your OneReach.ai account.

• To choose an authorization, select its name in the dropdown.

The Gear button contains options to Add a new or Delete an existing authorization, as well as to Refresh the list of added authorizations.

In case some changes were made to the authorization, an option to Reauthorize is available. To do that, click the respective button, then:

1. Click Reauthorize now in the modal window. A new Amazon tab will open.
2. Enter the login and password of the Alexa developer account.
3. Click Allow.

Inherit from previous step ​

When a Step from the Alexa toolkit is added to the Flow, you are expected to manually choose an authorization from the respective dropdown. If another Step from the toolkit is added to the Flow, the option to Inherit from previous step is chosen by default. When selected, it continues to use the same authorization as was defined in the previous Step of the toolkit without the need to select it manually.

Warning! If the Inherit from previous step option is selected, but there is no Step of the same toolkit in the Flow, the Step results in an error.

Alexa skill ​

If the authorization was successful, the Alexa skill dropdown should contain the list of available custom skills created in the connected Amazon developer console.

To choose a skill, select one of the two options:

• Choose the Skill name in the dropdown to manually select a skill in current step.
• Select the Use same skill as previous step option to choose the skill that was used in the last executed Step of the Alexa toolkit in the Flow.

Click the Refresh button to update the list of available skills. Click the Refresh skill interaction model to get the latest version of the selected skill.

Select skill in current step ​

After a skill has been selected, the Step checks the following settings:

• Endpoint URL
• Auto Delegation

Endpoint URL ​

Endpoint URL should be updated automatically by the Step. In case it fails, a link to copy the Endpoint URL becomes available. To set it manually do the following:

1. Open the Alexa developer console.
2. Select the respective skill.
3. Select Build > Endpoint, then select the HTTPS option as the Service Endpoint Type.
4. Paste the Endpoint URL value in the respective field of the required region.
5. Set the respective SSL certificate type as My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority.
6. Click Save.
7. Go to Build, then click Build Skill.
8. Return to the Flow after the skill has been updated and click Refresh skill interaction model.

Auto Delegation ​

Auto Delegation should be turned off automatically by the Step. In case it fails, a respective alert should pop up on Step UI. To turn it off manually do the following:

1. Open the Alexa developer console.
2. Select the respective skill.
3. Select Build > Interfaces.
4. Turn off the Auto Delegation toggle.
5. Click Save.
6. Go to Build, then click Build Skill.
7. Return to the Flow after the skill has been updated and click Refresh skill interaction model.

Use same skill as previous step ​

When a Step from the Alexa toolkit is added to the Flow, and an authorization is selected, you are expected to manually choose a skill from the respective dropdown. If another Step from the toolkit is added to the Flow, the option to Use same skill as previous step is chosen by default. When selected, it continues to use the same skill as was defined in the previous Step of the toolkit without the need to select it manually.

Warning! If the Use same skill as previous step option is selected, but there is no Step of the same toolkit in the Flow, the Step results in an error.

Request settings ​

This section defines what kind of data you expect the end user to provide in their response. The following options are available:

• Select the Intent option to take the Flow down an exit that matches the intent that Alexa understood from the end user's response.
• Select the Slot value option to ask for a value for the defined slot in a specified intent.

Warning! Switching between options updates other inputs of the Step, as well as its exits.

Intent ​

By default, if no intents were added in the Step but Alexa understands an intent in the end user's response, the Flow proceeds down the other exit. To take the Flow down a specific exit that matches the recognized intent, do the following:

1. Click the Add intent button.
2. Provide the Intent name.
3. Define the Exit name.
4. To add multiple intents, repeat steps 1-3.

Slot value ​

Use this option if you need to ask the end user for a specific slot value. To define the slot, do the following:

1. Provide the Intent name.
2. If necessary, update the Dialog Delegation Strategy
3. Define the Slot name.
4. Optional: turn off the Skip step execution if end user has provided value for selected slot

Intent name ​

The Intent name value is expected to exactly match an existing intent in the selected skill. The respective dropdown should contain all created intents in the selected skill. To provide the intent name manually or via a Merge field, enter its value, then click +.

Exit name ​

Each intent defined via the Add intent button adds a new exit to the Step. The Exit name is the label shown above the respective exit. It should not match existing exit names, such as next, other, session-end or error. Provide its value manually or via a Merge field.

Note: If you select the Intent name in the dropdown, the Step populates the Exit name automatically.

Dialog delegation strategy ​

To be able to use this Step, the Dialog delegation strategy option for the selected intent must be set as fallback to skill setting. To set it up manually, do the following:

1. Open the Alexa developer console.
2. Select the respective skill.
3. Select Build > Interaction model > Intents, then select the respective Intent.
4. Go to Dialog Delegation Strategy section of the intent, then select the fallback to skill setting in the dropdown.
5. Click Save, then click Build Skill.
6. Return to the Flow after the skill has been updated and click Refresh skill interaction model.

Slot name ​

The Slot name value is expected to exactly match an existing slot in the selected intent. The respective dropdown should contain all created slots in the selected intent. To provide the slot name manually or via a Merge field, enter its value, then click +.

Skip Step ​

By default, if the defined slot has received a value from the end user before the Flow entered this Step, it proceeds down the next exit without executing the Step. Turn off the Skip step execution if end user has provided value for selected slot if you need to ask the end user to specify the defined slot value regardless of the existing slot value.

Message content ​

This section defines the message that Alexa delivers to the end user. It may include the following:

• The Outbound message is the message that Alexa delivers to the end user before waiting for their response. This message cannot be empty.

• The Reprompt message is the message that Alexa delivers to the end user in case they have not responded to the outbound message within 8 seconds. Leave it empty to skip sending a reprompt.

  Set up the outbound and reprompt messages using either Text to speech, Audio file or SSML option.

• The Card is shown on the end user's device when the outbound message is delivered.

Note: Regardless of the selected option, it is advisable to test the message in the Alexa development console to make sure it is reproduced correctly.

Text to speech ​

The Text to speech option allows you to define the outbound message as plain text that Alexa converts into speech and says to the end user.

Alexa allows adding speech templates you can use to define the text to speech input. Read more about it here.

The Speech variations dropdown lists the Alexa Speech Prompts defined in the Slot Filling section of the respective slot. Select one to use it in the Text to speech input, update it if necessary.

The Text to speech input should not exceed 600 characters. Unpronounceable Unicode characters, i.e. <, >, &, shouldn't be used.

Audio file ​

Use the Audio file option to make Alexa play prerecorded audio instead of narrating a text.

The Audio file URL input must begin with https:// and lead to a file in mp3 format. The outbound message can contain an audio of up to 240s, while the reprompt message audio limit is 90s. All audio file limits are described in the link under the ? icon.

SSML ​

SSML stands for Speech Synthesis Markup Language. The SSML option can be used to create a more complex, nuanced message using the built-in Alexa SSML. The message may contain text to speech and audio inputs, as well as other options allowed by Alexa. Use the SSML tags in the SSML field input. Unpronounceable Unicode characters, i.e. <, >, &, shouldn't be used in the <speak> tag.

Card ​

The end user's device must possess a screen for the defined card to be shown. Read more about cards here.

To set up a card, turn on the Add card to message toggle, then provide the Card title, the Card body and, optionally, the URLs to Small and Large images.

The cumulative characters count for these inputs cannot exceed 8000. Either URL cannot exceed 2000 characters and must begin with https://. The jpg and png image files with up to 500kB in size are supported. The different sizes are used when displaying cards on different-sized screens:

Note: If you only provide one URL, the Alexa app uses that image regardless of the screen size where it is displayed.

Other events handling ​

In this section you can define the Step behavior when the expected response was not received from the end user. You can select how to:

• Handle other end user input
• Handle session ended event

Handle other end user input ​

An other end user input event example is as follows: the Step expects the end user to provide data for a specified slot but receives a response that doesn't match the requested slotType. Select how to handle such an event from the following options:

• Ignore and end Alexa session
• Send message and end Alexa session
• Handle with flow logic

Ignore and end Alexa session ​

When this option is selected, the Step ends the session without replying to the end user. The Flow proceeds down the session-end exit.

Send message and end Alexa session ​

When this option is selected, Alexa replies with the defined Text to speech message to the end user, and the Step ends the session. The Flow proceeds down the session-end exit.

Note: the Text to speech input follows the same rules as the respective input from the Message content section.

Handle with flow logic ​

When this option is selected, the Step adds the other exit. The Step continues the Alexa session, and the Flow proceeds down this exit.

Handle session ended event ​

The session ended event include the following examples:

• The Step sends shouldEndSession = true to Alexa. This happens when Alexa recognized an other event, and you selected either the Ignore and end Alexa's session or the Send message and end Alexa's session option in the Step.
• Alexa sends the sessionEndedRequest to the Step. This may occur in the following cases:
  • The end user says exit or quit.
  • The end user does not respond.
  • The end user says something that does not match an intent defined in your voice interface while the device is listening for their response.
  • An error occurs.

Note: You can use the session-end exit for reporting, data collection, etc., but cannot use it to continue communication between Alexa and the end user.

When the Handle session ended event toggle is turned off, the session-end exit is removed from the Step. If the Step ends the Alexa session or Alexa sends the sessionEndedRequest, the Flow fails immeadiately after exceeding the Flow timeout.

Note: You can process sessionEndedRequest in another Flow using the Wait for Session Ended Request (Alexa) Step.

Output data ​

This section is available when you select the Intent option in the Request settings section. It is optional and allows setting up the properties of the input object that become available as the quick access Merge field values further in the Flow.

The Step outputs the full input JSON object sent by Alexa in its request property. The intent name and slot data are duplicated in the top-level as intentName and slots properties respectively.

To set up this section, do the following:

• Select which Slots to add to the output.
• Select the necessary Additional properties.

Slots ​

When you select an intent in the dropdown, all slots defined in the respective intent are added to the Step UI automatically. Each slot is defined by its name, which must exactly match the respective Slot name in the intent for Alexa to recognize and populate.

To add a slot manually, click the Add a slot button, then, provide the Slot name in the respective field.

Each defined slot becomes available as a Merge field value later in the Flow. To remove a slot, click the Bucket icon.

Note: If Alexa matches the end user's word or phrase with a slot, it populates the respective slot, and the Step adds it to the output. The slots defined in this section only provide quick access via Merge field values further in the Flow.

Additional properties ​

By default, the Step includes only the request property in its output. To include additional properties, select them in this section.

Merge field settings ​

The output data of the Step is stored in a JSON object under the name provided in the Merge field name. To learn more about Merge fields, their types, and how to work with them, follow this link.

Output example ​

The output depends on the selection in the Request settings section:

• For the Intent option, you can select which properties to include in the Output data section.
• For the Slot value option, if Alexa returns the requested slot value, the slotValue property is included.

See the list of properties:

See below the structure of the Merge field object:

{
  "request": {
    "type": "IntentRequest",
    "requestId": "",
    "locale": "en-US",
    "timestamp": "",
    "intent": {
      "name": "",
      "confirmationStatus": "NONE",
      "slots": {}
    },
    "dialogState": "IN_PROGRESS"
  },
  "session": {
    "new": false,
    "sessionId": "",
    "application": {
      "applicationId": ""
    },
    "attributes": {},
    "user": {}
  },
  "context": {
    "Viewports": [],
    "Viewport": {},
    "Extensions": {
      "available": {
        "aplext:backstack:10": {}
      }
    },
    "Advertising": {
      "advertisingId": "00000000-0000-0000-0000-000000000000",
      "limitAdTracking": true
    },
    "System": {}
  },
  "slotValue": "London"
}

{
  "request": {
    "type": "IntentRequest",
    "requestId": "",
    "locale": "en-US",
    "timestamp": "",
    "intent": {
      "name": "",
      "confirmationStatus": "NONE",
      "slots": {}
    },
    "dialogState": "IN_PROGRESS"
  },
  "session": {
    "new": false,
    "sessionId": "",
    "application": {
      "applicationId": ""
    },
    "attributes": {},
    "user": {}
  },
  "context": {
    "Viewports": [],
    "Viewport": {},
    "Extensions": {
      "available": {
        "aplext:backstack:10": {}
      }
    },
    "Advertising": {
      "advertisingId": "00000000-0000-0000-0000-000000000000",
      "limitAdTracking": true
    },
    "System": {}
  },
  "slotValue": "London"
}

Error handling ​

By default, the Step handles errors using a separate exit. If an error occurs during the Step execution, the Flow proceeds down the error exit, e.g. if the selected intent isn't found. For more information on error handling, follow this link.

Reporting ​

The Step automatically generates Reporting events during its execution, allowing for real-time tracking and analysis of its performance and user interactions. To learn more about Reporting events, follow this link.

Services dependencies ​

• Alexa Skill Adapter v3.0.0 or upper

Release notes ​