Pre-Built Routine Primitives

---

You specify primitives when you initiate an AMAZON.OfferAutomation managed task request to offer your user a pre-built routine. For details, see Pre-Built Routine API Reference.

Trigger schemas

Skills can offer pre-built routines that use the following triggers:

• Custom utterance trigger
• Time/schedule trigger
• Sunrise/sunset trigger

Custom utterance trigger

This trigger represents a voice phrase that triggers a routine.

You can provide up to five utterances in order of preference. Alexa offers the routine with the first available utterance. If the user already has a routine with the first utterance, Alexa offers the routine with the second utterance, and so on.

Keep in mind the following rules:

• The utterance must conform to the Rules for sample utterances.
• The routine is created with only one utterance. Multiple utterances for a single routine aren't supported because multiple utterances make the offer prompt too verbose.
• The utterance locale must match the locale of the device.
• Utterances are supported in 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), and Italian (it-IT).

Name	Required?	Type	Description
type	Yes	Enum	Name of the custom utterance trigger. Valid value: Alexa.Automation.Trigger.Voice.CustomUtterance.
version	Yes	String	Version of the custom utterance trigger payload.
payload.utterances	Yes	String list	List of up to five utterances in order of preference. Alexa offers a routine with the first utterance that's not already in use. Note: You can't offer routines with multiple utterances combined with an "OR" operation.
payload.locale	Yes	String	Locale in which the custom utterance is uttered, in IETF BCP 47 format.

Time/schedule trigger

This trigger represents the specific time, with offset and recurring options, that triggers an automation. Although you can provide the time that the routine triggers, Amazon recommends that you have the user provide the time.

To get the time from the user, you must explicitly set the triggerTime parameter to "EMPTY", as in the following example.

{
    "type": "Alexa.Automation.Trigger.Schedule.AbsoluteTime",
    "version": "1.0",
    "payload": {
        "schedule": {
            "triggerTime": "EMPTY",
            "timeZoneId": "UTC",
            "recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
        }
    }
}

If you'd like to offer a specific time for the routine to run, you can specify the time in the triggerTime parameter, as in the following example.

{
    "type": "Alexa.Automation.Trigger.Schedule.AbsoluteTime",
    "version": "1.0",
    "payload": {
        "schedule": {
            "triggerTime": "193209",
            "timeZoneId": "UTC",
            "recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
        }
    }
}

Name	Required?	Type	Description
type	Yes	Enum	The name of the absolute time trigger. Valid value: Alexa.Automation.Trigger.Schedule.AbsoluteTime.
version	Yes	String	Version of the absolute time trigger payload.
payload.schedule.triggerTime	Yes	String	To get the time from the user, set the triggerTime parameter to "EMPTY", as in the following example. payload.schedule.triggerTime: "EMPTY" To make a fixed-time offer, use the local time formatted as RFC 5545 TIME, without the Z notation. Note: To be explicit that the specified time is local time, you must not use the Z notation. Time is in the format time-hour time-minute time-second, as in the following example. time-hour = 2DIGIT ;00-23 time-minute = 2DIGIT ;00-59 time-second = 2DIGIT ;00-60 For details, see RFC 5545 section 3.3.12.
payload.schedule.timeZoneId	Yes	String	Time zone for the automation. Required for automatically adjusting daylight saving time, if applicable. For details, see List of tz database time zones on Wikipedia. You must provide the time in the time zone of the user, which you can retrieve with the Settings API. For example, to schedule a routine for a football game that starts at 10 AM PST, you must provide 10 AM PST for users who reside in PST and 1 PM EST for users who reside in EST.
payload.schedule.recurrence	No	String	Recurrence of the schedule. The recurring expression must conform to the RFC 5545 pattern. This schema currently supports only weekly recurrences, so you must use the following values:   • FREQ=WEEKLY   • INTERVAL=1   • BYDAY=(?:SU|MO|TU|WE|TH|FR|SA)(?:,(SU|MO|TU|WE|TH|FR|SA)){0,6}) For example, to have the routine recur on weekdays, use: RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR

Sunrise/sunset trigger

The sunrise and sunset triggers represent the sunrise and sunset time that can trigger a routine.

Sunrise schema

Sunset schema

Name	Required?	Type	Description
type	Yes	Enum	The name of the sunrise or sunset trigger. Valid values: Alexa.Automation.Trigger.Schedule.Sunrise or Alexa.Automation.Trigger.Schedule.Sunset.
version	Yes	String	Version of the sunrise or sunset trigger payload.
payload.recurrence	Yes	String	Sunrise and sunset triggers must recur. The recurring expression must conform to the RFC 5545 pattern. This schema currently supports only weekly recurrences, so you must use the following values:   • FREQ=WEEKLY   • INTERVAL=1   • BYDAY=(?:SU|MO|TU|WE|TH|FR|SA)(?:,(SU|MO|TU|WE|TH|FR|SA)){0,6}) For example, to have the routine recur on weekdays, use: RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR
payload.timeOffset	No	Long	The time offset in seconds before the sunset or sunrise time. The default value is 0.

Action schemas

Skills can offer pre-built routines that use Amazon-defined actions and skill-defined actions.

Amazon-defined actions

Amazon provides the following actions:

• Announcement action
• Date action
• Time action
• Weather action
• Flash briefing

Announcement action

Alexa makes the specified announcement on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the announcement action. Valid value: Alexa.Automation.Operation.Notification.Notify.
version	Yes	String	Version of the announcement action payload.
payload.notification	Yes	Object	Object contains the notification content.
payload.notification.variants[].type	Yes	Enum	Notification delivery type. Valid value: Announcement.
payload.notification.variants[].content	Yes	Object	Object that specifies different variants of content for spoken and display purposes.
payload.notification.variants[].content.variants[]	Yes	List	Locale-specific notification content to deliver to the user.
payload.notification.variants[].content.variants[].type	Yes	Enum	Localized text input. Valid value: SpokenText.
payload.notification.variants[].content.variants[].values[]	Yes	List	Content values list. Each element in the list represents localized text input.
payload.notification.variants[].content.variants[].values[].locale	Yes	String	The locale in which the spoken text is rendered, in IETF BCP 47 format.
payload.notification.variants[].content.variants[].values[].text	Yes	String	Spoken text in plain text format. Maximum length is 1024 characters or 2048 bytes.

Date action

Alexa tells the user the current date on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the date action. Valid value: Alexa.Automation.Operation.Time.PlayWhatDate.
version	Yes	String	Version of the date action payload.
payload	Yes	Object	Empty object.

Time action

Alexa tells the user the current time on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the time action. Valid value: Alexa.Automation.Operation.Time.PlayWhatTime.
version	Yes	String	Version of the time action payload.
payload	Yes	Object	Empty object.

Weather action

Alexa tells the user the current weather on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the weather action. Valid value: Alexa.Automation.Operation.Weather.PlayForecast.
version	Yes	String	Version of the weather action payload.
payload	Yes	Object	Empty object.

Flash briefing action

Alexa plays the user a flash briefing on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the flash briefing action. Valid value: Alexa.Automation.Operation.News.PlayFlashBriefing.
version	Yes	String	Version of the flash briefing action payload.
payload	Yes	Object	Empty object.

Skill-defined actions

Your skill can define the following actions:

• Launch skill action
• Custom task action

Launch skill action

Alexa opens the specified skill on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the skill action. Valid value: Alexa.Automation.Operation.Skill.Launch.
version	Yes	String	Version of the skill action payload.
payload.skillId	Yes	String	Skill ID of the skill to open.

Custom task action

Alexa runs the specified custom task on the target device. The target device is the Alexa-enabled device with which the user consented to create the routine. An exception is the custom utterance trigger, where the target device is the Alexa-enabled device to which the user uttered the trigger.

Name	Required?	Type	Description
type	Yes	Enum	Name of the task action. Valid value: Alexa.Automation.Operation.Skill.StartConnection.
version	Yes	String	Version of the task action payload.
payload.connectionRequest	Yes	Object	Request to skill connections.
payload.connectionRequest.uri	Yes	String	URI of the task to be invoked by skill connections. Valid URI formats: Launch a predefined Amazon task: connection://AMAZON.{name}/{version_number}?provider={provider_skill_id} Launch a custom task: connection://{provider_skill_id}.{task_name}/${version_number}?provider={provider_skill_id} For details, see For managed skill connection in the skill connections documentation.
payload.connectionRequest.input	No	Object	Request object forwarded to the invoked task.

When you define a custom task, you should add descriptionPrompt as a part of rendering data. Add a description for every locale that the custom task supports. For details, see renderingData object.

Related topics

• Offer Pre-Built Routines from Your Skill
• Pre-Built Routine API Reference
• Understand Skill Connections
• Use Skill Connections to Request Tasks

---

---

Last updated: Apr 17, 2024