Offer Pre-Built Routines from Your Skill

You can offer pre-built Alexa routines to your users during voice interactions with your skill. Alexa routines enable users to automate a sequence of actions based on a trigger event. For example, a user can set up a routine that turns on the lights, reads the news briefing, and tells the weather update on weekdays at 7 AM (the trigger event).

User experience

This feature enables your skill to offer pre-built routines to users as they interact with your skill. When the user verbally provides their consent, Alexa enables the routine.

A horoscope skill might offer to create a routine for the user in the following way.

User: Alexa, ask Daily Horoscopes for my horoscope.
Alexa: Welcome to Daily Horoscopes. Here's your horoscope for today: You will hear some great news.
Alexa: By the way, I can create a routine for you where I automatically give you your horoscope on weekdays at a time you choose. Would you like that?
User: All right.
Alexa: Great! What time would you like the routine to execute at?
User: How about at 6:50 in the morning?
Alexa: I heard you say 6:50 AM. Is that correct?
User: Yup!
Alexa: Ok. I created a routine for you. You can make changes to it, and create new routines, in the Alexa app.

Users can view the routines they've accepted by navigating to More > Routines in the Alexa app. Routines appear in the routine list as "Your Skill Name : Accepted Date" to inform users how and when the routine was created.

Routine examples

The following table shows some examples of routines.

Skill category Example prompt from Alexa

Business and Finance

"Oh! Here's an idea. I can create a routine for you where I automatically play the news and then read the Amazon stock quote from <skill name> every day at a time you choose. Would you like that?"

Lifestyle

"Oh! Here's an idea. I can create a routine for you where I automatically announce 'Let's start the day by finding calm' and then begin your daily activity from <skill name> every day at 7:30 AM. Would you like that?"

Games

"Oh! Here's an idea. I can create a routine for you where I automatically play the news and then play your daily quiz from <skill name> when you say 'Alexa, start my commute.' Would you like that?"

Radio and News

"Oh! Here's an idea. I can create a routine for you where I automatically tell you the weather, and then play news from <skill name> every day at 7:30 AM. Would you like that?"

Sports

"Oh! Here's an idea. I can create a routine for you where I automatically announce 'It's game day!', and then your fantasy update from <skill name> every Sunday at 9:30 AM. Would you like that?"

Prerequisites

For your skill to offer pre-built routines to users by voice, you must meet the following requirements:

  • Your skill must support at least one of the English (en-US, en-CA, en-IN, en-GB, en-AU), Spanish (es-ES, es-US, es-MX), German (de-DE), French (fr-FR, fr-CA), Portuguese (pt-BR), or Italian (it-IT) locales.
  • Your skill must not be a child-directed skill or a Health Insurance Portability and Accountability Act (HIPAA) skill.
  • Your skill must be a custom skill or at least support the custom interface. To add the custom interface to a non-custom skill, such as a radio or video skill, perform the following steps.

How it works

To make pre-built routine offers, you use skill connections. When you initiate an AMAZON.OfferAutomation connection, your skill passes control to Alexa. Alexa constructs the offer prompt and creates the routine in the user's account before handing the session back to your skill.

The following example shows what happens behind the scenes when a skill offers to create a pre-built routine for the user. The skill passes control to Alexa, which then passes control back to the skill. This example is for demonstration purposes only. When you implement this feature, you can alter the dialog for the skill, but Amazon controls the dialog for Alexa.

Step Actor Speaker Speech or action

1

N/A

User

"Alexa, ask Daily Horoscopes for my horoscope."

2

Skill

Alexa

"Welcome to Daily Horoscopes. Here's your horoscope for today: You will hear some great news."

3

Skill

N/A

The skill sends a Connections.StartConnection directive to AMAZON.OfferAutomation with the automation in the payload.

4

Alexa

N/A

The skill session pauses and control passes to Alexa.

5

Alexa

Alexa

"Oh! Here's an idea. I can create a routine to give you your horoscope at 9 AM every morning. Would you like me to enable this routine?"

6

N/A

User

"Yes."

7

Alexa

Alexa

"Ok. I created a routine for you. You can make changes to it, and create new routines, in the Alexa app."

8

Alexa

N/A

Alexa sends the skill a SessionResumedRequest request with an OfferAutomationResponse object to pass control back to the skill.

9

Skill

N/A

The skill handles the SessionResumedRequest request.

10

Skill

Alexa

"Thanks for using Daily Horoscopes. Have a great day."

Steps to offer a pre-built routine from your skill

To offer the user a pre-built routine from your custom skill, take the following steps:

  1. (Optional) Create and integrate a custom task.
  2. Design the routine experience.
  3. Add skill code to pass and receive control through skill connections.
  4. Test your implementation.
  5. Submit your skill for certification.
  6. Get metrics.

(Optional) Step 1: Create and integrate a custom task

If you only want the routine to launch your skill, you can skip this step. For details, see Launch skill action.

Otherwise, you can optionally create a custom task to expose specific functionality of your skill as an action in the routine. For details, see Implement Custom Tasks in Your Skill and Integrate a Custom Task with Alexa Routines.

Step 2: Design the routine experience

After you publish your custom task, you can design a routine experience by pairing the routine with a trigger. Currently, Alexa supports routines that adhere to the following rules:

  • The routine must contain one trigger.
  • The routine can contain up to two actions.
  • For routines with one action, your skill must perform the action by using the launch skill action or the custom task action.
  • For routines with two actions, the first action must be an Amazon-defined action. Your skill must perform the second action.

For inspiration on routine experiences, see the Alexa routines product page and the routine examples provided previously.

For a list of Amazon-defined triggers and actions that you can use to construct routines, see Pre-Built Routine Primitives.

Step 3: Add skill code to pass and receive control through skill connections

You can offer a routine to your user anytime during the skill interaction session. For best practices about when to offer a routine, see Best Practices. For the API reference, see Pre-Built Routine API Reference.

In your skill code, do the following:

  • To initiate the offer, send a Connections.StartConnection directive for the AMAZON.OfferAutomation managed task. This directive transfers control of the session to Alexa. For details about the directive, see Connections.StartConnection directive schema.
  • To receive control back from Alexa after the user accepts the offer, implement a handler for the SessionResumedRequest. For details about the responses, see SessionResumedRequest schema.

Step 4: Test your implementation

You must test the user experience of Alexa offering the user the pre-built routine. For example, make sure that your pre-built offer follows best practices.

Step 5: Submit your skill for certification

If you newly added the custom interface to your skill (as part of Prerequisites) or you added a new custom task, you must re-certify your skill. For details about how to submit your skill for certification, see Submit Skills for Certification in the Alexa Developer Console.

Otherwise, if you just added a pre-built routine offer, you don't need to re-submit your skill your certification. You just need to update your AWS Lambda skill handler code.

Step 6: Get metrics

You can use the Alexa Skill Management API (SMAPI) to get metrics on how users responded to your pre-built routine offers.

To get these metrics, call Get metrics with the properties and definitions detailed in the API documentation. The following settings highlight the distinct dimensions and options specific to routines offers:

  • Set metricQueries[*].name to one of the following values:
    • AUTOMATION_ORIGINATION – Metrics for offer initiation and user acceptances.
    • AUTOMATION_EXECUTION – Metrics for offers that users run.
  • Set metricQueries[*].metricNamespace to Alexa.Automation.
  • Set metricQueries[*].groupBy to one of the following values:
    • templateId – Aggregates metrics distributed across different template IDs.
    • origination – Aggregates metrics distributed across different origination types.
    • execution – Aggregates metrics distributed across different execution types.
  • Include one or more of the following dimensions:
    • Alexa.Automation.Origination – For this dimension, set value to one of the following values:
      • OFFER_INITIATED_BY_SKILL – Total number of offers that the skill initiated.
      • OFFER_SENT_TO_CUSTOMER – Total number of offers sent to users.
      • OFFER_ACCEPTED_BY_CUSTOMER – Total number of offers that users accepted.
      • OFFER_NOT_ACCEPTED_BY_CUSTOMER – Total number of offers that users didn't accept.
    • Alexa.Automation.TemplateId – For this dimension, set the value to a templateId that represents a routine you offered.
    • Alexa.Automation.Execution – For this dimension, use the following value:
      • AUTOMATION_EXECUTED – Total number of offers that users run.

Example queries

The following example shows the body of a Get metrics request and a response for a query that fetches the number of offers that users accepted between a start time and an end time, aggregated by day.

The following example shows the body of a Get metrics request and a response for a query that fetches the number of offers grouped by different origination status (OFFER_INITIATED_BY_SKILL, OFFER_SENT_TO_CUSTOMER, OFFER_ACCEPTED_BY_CUSTOMER, OFFER_NOT_ACCEPTED_BY_CUSTOMER).

The following example shows the body of a Get metrics request and a response for a query that fetches the number of offers that customers ran between the start time and end time, aggregated by day.

Best practices

When you offer a pre-built routine, consider the following best practices:

  • Limit the frequency of offers – Don't make frequent offers to a particular user. The user might find it interruptive. Alexa also enforces rules on the frequency at which a given user receives pre-built routine offers to protect user trust.
  • Personalize your offers – Tailoring the routine to a user's behavior can create more compelling experiences. It also increases the likelihood that the user accepts your offer. We encourage you to personalize the routine experience to be contextually relevant to the user. One way is by using dynamic offer properties to let the user decide what's right for them. Another way is to use user data to predict what they might want. For example, consider the scenario where a user often invokes your skill at 7 AM and a different user often invokes your skill at 8 AM. In that case, offer the first user a routine with a time/schedule trigger of 7 AM and offer the second user a routine with a time/schedule trigger of 8 AM, or you can allow the users to set the time when their routine runs. Similarly, if you have multiple custom tasks in your skill, you should offer the custom task that corresponds to the experience that the user often invokes.
  • Offer at the right moment during the interaction – To maximize your acceptance rate, initiate your routine offers when users are most receptive. For example, if your skill provides long-running audio content (for example, news, radio, or a soundscape), consider making the offer before starting the stream. If your skills provides a game or trivia experience, consider making the offer at the end when you normally invite users to play again the next day.
  • Pay attention to the voice prompt – Alexa generates the voice offer prompt by using the description of the actions you send as part of your skill connections request. Ensure that the descriptions you provide are grammatically correct and aren't verbose.

Pre-built routines FAQ

The following section contains frequently asked questions (FAQ) about pre-built routines.

Q: How many routine offers can I make to each user?
Users might perceive frequent routine offers to be spam. If a user declines your offer, you shouldn't offer a routine to the user for at least seven days.
Q: How do I keep track of routines my skill users have enabled?
If the user accepts your offer, you receive a Connection.Response with status code 200 and a templateId that represents the automation (that is, the combinations of triggers and actions). To prevent repeat offers of the same routine, Amazon recommends that you maintain a record of each templateId a user accepts.
Q: What happens if a user disables or deletes my offered routine?
After a user accepts a routine offer from your skill, they can access that routine from the Alexa app. The user can update, disable, or delete a routine at any time through the Alexa app. To protect user privacy, Amazon doesn't share the status of any routine after it's enabled during the interaction with your skill.
Q: Can I update the routine experience I previously offered to my users?
No. After a user accepts your routine offer, Alexa creates the routine in the user's account. Only the user can update, disable, or delete that routine.
Q: Are there any limits on offering routines to users?
To protect user trust, Amazon blocks offers based on certain criteria such as the time of day, frequency of offers that a user receives across skills, and the user's routine usage. When a limit is reached, your skill receives an HTTP 204 response with reason REJECTED_BY_GUARDRAILS. In these cases, try making the offer again after a few days.
Q: To provide the best user experience, can I enable users to set the time when their routine runs instead of me offering a specific time that might not be best for the user? For example, I might suggest a time of 7 AM, whereas the user prefers another time.
Yes. If you're unsure what time to offer to your users for their routines to run, we encourage you to let users set the time themselves. For details, see Time/Schedule Trigger.
Was this page helpful?

Last updated: Apr 17, 2024