Pre-Built Routine Primitives

Note: Sign in to the developer console to build or publish your skill.

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).

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

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

Note: The offered routine can't contain more than two actions, and it must contain at least one skill-defined action (custom task or skill launch) that you own.

Amazon-defined actions

Amazon provides the following actions:

Note: For these actions, Amazon provides the description that Alexa uses to offer the routine.

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.

Note: If the locale of the announcement doesn't match that of the device, Alexa might not pronounce the announcement correctly.

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

Note: For these actions, you must provide a descriptionPrompt for Alexa to use to offer the routine.

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.

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

Provide feedback

Last updated: Apr 17, 2024