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
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.
{
"type": "Alexa.Automation.Trigger.Voice.CustomUtterance",
"version": "1.0",
"payload": {
"utterances": ["utterance A", "utterance B", "utterance C"],
"locale": "en-US"
}
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the custom utterance trigger. Valid value: |
|
Yes |
String |
Version of the custom utterance trigger payload. |
|
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.
|
|
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.
{
"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 |
---|---|---|---|
|
Yes |
Enum |
The name of the absolute time trigger. Valid value: |
|
Yes |
String |
Version of the absolute time trigger payload. |
|
Yes |
String |
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
For details, see RFC 5545, section 3.3.12. |
|
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. |
|
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:
For example, to have the routine recur on weekdays, use: |
Sunrise/sunset trigger
The sunrise and sunset triggers represent the sunrise and sunset time that can trigger a routine.
Sunrise schema
{
"type": "Alexa.Automation.Trigger.Schedule.Sunrise",
"version": "1.0",
"payload": {
"recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA",
"timeOffset": 1200
}
}
Sunset schema
{
"type": "Alexa.Automation.Trigger.Schedule.Sunset",
"version": "1.0",
"payload": {
"recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA",
"timeOffset": 1200
}
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
The name of the sunrise or sunset trigger. Valid values: |
|
Yes |
String |
Version of the sunrise or sunset trigger payload. |
|
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:
For example, to have the routine recur on weekdays, use: |
|
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
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.
{
"type": "Alexa.Automation.Operation.Notification.Notify",
"version": "1.0",
"payload": {
"notification": {
"variants": [{
"type": "Announcement",
"content": {
"variants": [{
"type": "SpokenText",
"values": [{
"locale": "en-US",
"text": "Example notification"
}]
}]
}
}]
}
}
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the announcement action. Valid value: |
|
Yes |
String |
Version of the announcement action payload. |
|
Yes |
Object |
Object contains the notification content. |
|
Yes |
Enum |
Notification delivery type. Valid value: |
|
Yes |
Object |
Object that specifies different variants of content for spoken and display purposes. |
|
Yes |
List |
Locale-specific notification content to deliver to the user. |
|
Yes |
Enum |
Localized text input. Valid value: |
|
Yes |
List |
Content values list. Each element in the list represents localized text input. |
|
Yes |
String |
The locale in which the spoken text is rendered, in IETF BCP 47 format. |
|
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.
{
"type": "Alexa.Automation.Operation.Time.PlayWhatDate",
"version": "1.0",
"payload": { }
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the date action. Valid value: |
|
Yes |
String |
Version of the date action 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.
{
"type": "Alexa.Automation.Operation.Time.PlayWhatTime",
"version": "1.0",
"payload": { }
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the time action. Valid value: |
|
Yes |
String |
Version of the time action 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.
{
"type": "Alexa.Automation.Operation.Weather.PlayForecast",
"version": "1.0",
"payload": { }
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the weather action. Valid value: |
|
Yes |
String |
Version of the weather action 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.
{
"type": "Alexa.Automation.Operation.News.PlayFlashBriefing",
"version": "1.0",
"payload": { }
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the flash briefing action. Valid value: |
|
Yes |
String |
Version of the flash briefing action payload. |
|
Yes |
Object |
Empty object. |
Skill-defined actions
Your skill can define the following actions:
descriptionPrompt
for Alexa to use to offer the routine.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.
{
"type": "Alexa.Automation.Operation.Skill.Launch",
"version": "1.0",
"payload": {
"skillId": "{example-skill-id}"
}
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the skill action. Valid value: |
|
Yes |
String |
Version of the skill action payload. |
|
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.
{
"type": "Alexa.Automation.Operation.Skill.StartConnection",
"version": "1.0",
"payload": {
"connectionRequest": {
"uri": "connection://AMAZON.{name}/{version_number}?provider={provider_skill_id}",
"input": {}
}
}
}
Name | Required? | Type | Description |
---|---|---|---|
|
Yes |
Enum |
Name of the task action. Valid value: |
|
Yes |
String |
Version of the task action payload. |
|
Yes |
Object |
Request to skill connections. |
|
Yes |
String |
URI of the task to be invoked by skill connections. Valid URI formats:
For details, see For managed skill connection in the skill connections documentation. |
|
No |
Object |
Request object forwarded to the invoked task. |
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: Jul 01, 2022