@jovotech/output-alexa NPM

title: 'Alexa Output'

excerpt: 'Learn more about Jovo output templates for Alexa.'

Alexa Output

Learn more about output templates for Alexa.

Introduction

Jovo offers the ability to create structured output that is then translated into native platform responses.

This structured output is called output template. Its root properties are generic output elements that work across platforms. Learn more about how generic output is translated into an Alexa response below.

{
  message: `Hello world! What's your name?`,
  reprompt: 'Could you tell me your name?',
  listen: true,
}

You can also add platform-specific output to an output template. Learn more about Alexa output below.

{
  // ...
  platforms: {
    alexa: {
      // ...
    }
  }
}

Generic Output Elements

Generic output elements are in the root of the output template and work across platforms. Learn more in the Jovo Output docs.

Below, you can find a list of generic output elements that work with Alexa:

message

The generic message element is what Alexa is saying to the user:

{
  message: 'Hello world!',
}

Under the hood, Jovo translates the message into an outputSpeech object (see the official Alexa docs):

{
  "outputSpeech": {
    "type": "SSML",
    "ssml": "<speak>Hello world!</speak>"
  }
}

reprompt

The generic reprompt element is used to ask again if the user does not respond to a prompt after a few seconds:

{
  message: `Hello world! What's your name?`,
  reprompt: 'Could you tell me your name?',
}

Under the hood, Jovo translates the reprompt into an outputSpeech object (see the official Alexa docs) inside reprompt:

{
  "reprompt": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>Could you tell me your name?</speak>"
    }
  }
}

listen

The listen element determines if Alexa should keep the microphone open and wait for a user's response.

By default (if you don't specify it otherwise in the template), listen is set to true. If you want to close a session after a response, you need to set it to false:

{
  message: `Goodbye!`,
  listen: false,
}

Under the hood, Jovo translates listen: false to "shouldEndSession": true in the JSON response.

The listen element can also be used to add dynamic entities for Alexa. Learn more in the $entities documentation.

quickReplies

Alexa does not natively support quick replies. However, Jovo automatically turns the generic quickReplies element into buttons for APL:

{
  // ...
  quickReplies: [
    {
      text: 'Button A',
      intent: 'ButtonAIntent'
    }
  ]
}

For this to work, genericOutputToApl needs to be enabled in the Alexa output configuration.

For these buttons, you need to pass a target intent. When the button is clicked, the Jovo Router automatically maps this to the specified intent.

It's also possible to add entities:

{
  // ...
  quickReplies: [
    {
      text: 'Button A',
      intent: 'ButtonIntent',
      entities: {
        button: {
          value: 'a',
        }
      },
    }
  ]
}

card

Jovo automatically turns the generic card element into a detail screen for APL:

{
  // ...
  card: {
    title: 'Hello world!',
    content: 'Welcome to this new app built with Jovo.'
  },
}

For this to work, genericOutputToApl needs to be enabled in the Alexa output configuration.

Note: If you want to send a home card to the Alexa mobile app instead, we recommend using the nativeResponse property.

carousel

Alexa does not natively support carousels. However, Jovo automatically turns the generic carousel element into a card slider for APL:

{
  // ...
  carousel: {
    items: [
      {
        title: 'Element 1',
        content: 'To my right, you will see element 2.'
      },
      {
        title: 'Element 2',
        content: 'Hi there!'
      }
    ]
  },
}

For this to work, genericOutputToApl needs to be enabled in the Alexa output configuration.

You can make it clickable by adding a selection object. Once an element is selected by the user, the Jovo Router will automatically map the request to the provided intent (and potentially entities):

{
  // ...
  carousel: {
    items: [
      {
        title: 'Element A',
        content: 'To my right, you will see element B.',
        selection: {
          intent: 'ElementIntent',
          entities: {
            element: {
              value: 'A',
            },
          },
        },
      },
      {
        title: 'Element B',
        content: 'Hi there!',
        selection: {
          intent: 'ElementIntent',
          entities: {
            element: {
              value: 'B',
            },
          },
        },
      }
    ]
  },
}

In the example above, a tap on an element triggers the ElementIntent and contains an entity of the name element.

Alexa Output Elements

It is possible to add platform-specific output elements to an output template. Learn more in the Jovo output documentation.

For Alexa, you can add output elements inside an alexa object:

{
  // ...
  platforms: {
    alexa: {
      // ...
    }
  }
}

Native Response

The nativeResponse property allows you to add native elements exactly how they would be added to the Alexa JSON response.

{
  // ...
  platforms: {
    alexa: {
      nativeResponse: {
        // ...
      }
    }
  }
}

For example, an APL RenderDocument directive (see official Alexa docs) could be added like this:

{
  // ...
  platforms: {
    alexa: {
      nativeResponse: {
        response: {
          directives: [
            {
              type: 'Alexa.Presentation.APL.RenderDocument',
              token: 'helloworldToken',
              document: { /* ... */ },
              datasources: { /* ... */ },
            }
          ]
        }
      }
    }
  }
}

Learn more about the response format in the official Alexa documentation.

Alexa Output Configuration

This is the default output configuration for Alexa:

const app = new App({
  // ...

  plugins: [
    new AlexaPlatform({
      output: {
        genericOutputToApl: true,
      },
    }),
  ],
});

It includes the following properties:

genericOutputToApl: Determines if generic output like quickReplies, card, and carousel should automatically be converted into an APL directive.