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.
  • 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).
{
    "type": "Alexa.Automation.Trigger.Voice.CustomUtterance",
    "version": "1.0",
    "payload": {
        "utterances": ["utterance A", "utterance B", "utterance C"],
        "locale": "en-US"
    }
}
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.

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.

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

{
    "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

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

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

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.

{
  "type": "Alexa.Automation.Operation.Time.PlayWhatDate",
  "version": "1.0",
  "payload": { }
}
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.

{
  "type": "Alexa.Automation.Operation.Time.PlayWhatTime",
  "version": "1.0",
  "payload": { }
}
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.

{
  "type": "Alexa.Automation.Operation.Weather.PlayForecast",
  "version": "1.0",
  "payload": { }
}
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.

{
  "type": "Alexa.Automation.Operation.News.PlayFlashBriefing",
  "version": "1.0",
  "payload": { }
}
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

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

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.

{
  "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

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.


Was this page helpful?

Last updated: Apr 17, 2024