Pre-Built Routine API Reference

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

To offer an Alexa skill user a pre-built routine, you use skill connections. Skill connections is an Alexa feature that enables a skill to call another skill or service to perform a specific task.

In this case, Alexa provides the AMAZON.OfferAutomation managed task. Alexa interacts with the user to offer the routine, and then returns control to your skill.

To offer a user a pre-built routine, you must add the following code to your skill:

Initiate the pre-built routine offer flow by sending a Connections.StartConnection directive for AMAZON.OfferAutomation from a request handler.
Implement a SessionResumedRequestHandler to accept a SessionResumedRequest with the offerAutomationResponse.

Connections.StartConnection directive schema

To initiate the pre-built routine offer flow, send a Connections.StartConnection directive for the AMAZON.OfferAutomation task. The following example shows a Connections.StartConnection directive. For details about skill connections, see About Skill Connections.

{
   "type": "Connections.StartConnection",
   "uri": "connection://AMAZON.OfferAutomation/1",
   "input": {
     "automation": {"automation payload"},
     "renderingData": {"optional rendering information"}
   },
   "onCompletion": "RESUME_SESSION",
   "token": "example-token"
}

Copied to clipboard.

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.OfferAutomation/1",
  "onCompletion": "RESUME_SESSION",
  "token": "example-token",  
  "input": {  
     "automation": {
       "trigger": {
         "type": "Alexa.Automation.Trigger.Schedule.AbsoluteTime",
         "version": "1.0",
         "payload": {
            "schedule": {
               "triggerTime": "073000",
               "timeZoneId": "UTC",
               "recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
            }
         }
       },
       "operations": {
         "serial": [
           {
             "operation": {
                 "type": "Alexa.Automation.Operation.Weather.PlayForecast",
                 "version": "1.0",
                 "payload": { }
               }
           },
           {
             "operation": {
                 "type": "Alexa.Automation.Operation.Skill.StartConnection",
                 "version": "1.0",
                 "operationId": "playNewsOperation",
                 "payload": {
                    "connectionRequest": {
                       "uri": "connection://newsSkillId123.PlayNews/1?provider=newsSkillId123",
                       "input": {}                   
                    }
                 }
             }
           }
         ]
       }
    },
     "renderingData": {
        "operations": {
           "playNewsOperation": {
              "descriptionPrompt": "play your news update"
           }
        }
      }
    }
}

Connections.StartConnection object

The Connections.StartConnection object contains the following fields.

Name	Required?	Type	Description
`type`	Yes	String	Directive type. Set this to `Connections.StartConnection`.
`uri`	Yes	String	Resource that defines the task and the task version. Set this to `connection://AMAZON.OfferAutomation/1`.
`onCompletion`	Yes	String enum	Enum that indicates whether your skill receives control back after the user interacts with the offer. Must be set to `RESUME_SESSION`.
`token`	No	String	Token that is returned to the skill as-is in the `SessionResumedRequest`. You can use the token to resume the skill after the task is complete.
`input`	Yes	Object	An object that represents the request payload for the managed task. The `input` object contains two objects, the automation to offer and rendering data that Alexa uses to generate a voice prompt. For details, see `input` object.

input object

The request payload for AMAZON.OfferAutomation contains the following fields.

Name	Required?	Type	Description
`automation`	Yes	Object	Routine that the skill offers to the user. For details, see `automation` object.
`renderingData`	No. Only required if the routine contains a custom task.	Object	Information about your skill action. Alexa uses this information to generate the routine offer prompt.

automation object

The automation object contains the following fields.

Name	Required?	Type	Description
`trigger`	Yes	Object	Event that initiates the routine. For details, see `trigger` object.
`operations`	Yes	Object	Actions that run as part of the routine. For details, see `operation` object.

trigger object

The trigger object contains the following fields.

Name	Required?	Type	Description
`type`	Yes	String	Type of trigger. Examples are `Alexa.Automation.Trigger.Voice.CustomUtterance`, `Alexa.Automation.Trigger.Schedule.AbsoluteTime`, etc. For a list of triggers and their schemas, see Trigger schemas.
`version`	Yes	String	Version of the given trigger type.
`payload`	Yes	Object	JSON payload that conforms to the specified trigger's schema. For details, see Trigger schemas.

operations object

The operations object contains the following fields.

Name	Required?	Type	Description
`serial`	Yes	List of `operation` objects	List of operations to run serially. Maximum number of operations is two. You can only provide one of `Alexa.Automation.Operation.Skill.Launch` or `Alexa.Operation.StartConnection`, and it must be the last action in the list.

operation object

The operation object contains the following fields.

Name	Required?	Type	Description
`type`	Yes	String	Type of operation, which is an action. For a list of actions and their schemas, see Action schemas.
`version`	Yes	String	Version of the given operation type.
`operationId`	No	String	Your reference ID for the specific operation. Only required if the `type` is `Alexa.Operation.StartConnection`. The `renderingData` field of the `AMAZON.OfferAutomation` request payload references this ID.
`payload`	Yes	Object	JSON payload that conforms to the specified operation's schema. For details, see Action schemas.

renderingData object

The renderingData object contains the following fields.

Name	Required?	Type	Description
`operations`	Yes	List of objects	Map of `operationId` to a description.
`operations[].descriptionPrompt`	Yes	String	String that describes the functionality of your custom task. Alexa uses this string to generate the routine offer prompt. This description should be a short phrase that starts with a verb and targets the user. Examples: `"tell you today's weather forecast"`, `"play your news briefing"`, `"play ocean sounds"`.

The following example shows how you can define renderingData to show a de_DE description of a custom task.

"renderingData": {
   "operations": {
      "playOceanSoundsOperation": {
         "descriptionPrompt": "meeresrauschen abspielen"
      }
   }
}

SessionResumedRequest schema

If the user accepts the offer, Alexa uses your automation definition to create a routine for the user.

The SessionResumedRequest contains a templateId for the generated automation. All automations that have the same combination of trigger and actions have the same templateId. Amazon recommends that you track these template IDs per user. Alexa also maintains a set of rules on the maximum frequency of which you can offer the same routine to the same user.

If the user doesn't accept the offer, remains silent, or interrupts the offer, the routine isn't created. In either case, your skill still receives the results in a SessionResumedRequest. You can find the result of the offer in the cause object of the SessionResumedRequest. Parse the cause object, and then create your skill's response accordingly.

To resume your skill session after the routine offer, implement a SessionResumedRequestHandler to accept a SessionResumedRequest with the offerAutomationResponse. For details about SessionResumedRequest, see Implement a handler to receive a response from a skill connections request.

The following example shows a SessionResumedRequest for the AMAZON.OfferAutomation task.

{
  "version": "1.0",
  "session": {
     ...
  },
  "context": {
     "System": {
        ...
    }
  },
  "request": {
    "type": "SessionResumedRequest",
    "requestId": "example-request-id",
    "timestamp": "example-timestamp",
    "locale": "example-locale",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "...",
        "status": {
            "code": "200",
            "message": "Automation successfully enabled"
        },
        "result": {
         "offerAutomationResponse": {
               "templateId": "example-template-id"
            }
        }
    }
  }
}

cause object

The cause object contains the following fields.

Name	Type	Description
`type`	String	The type of `SessionResumedRequest`, which is `ConnectionCompleted` in this case.
`token`	String	A string that you included in the `Connections.StartConnection` directive, returned as-is. You can use this token to resume the skill after the task request is complete.
`status`	Object	A status code and message. For details, see `status` object.
`result`	Object	The outcome of the offer. For details, see `result` object.

status object

The status object contains the following fields.

Name	Type	Description
`code`	String	An HTTP status code that Alexa provides to your skill after fulfilling the task request. For a list of possible values, see Status codes.
`message`	String	A message that describes the outcome of the request. For a list of possible values, see Status codes.

result object

The result object contains the following fields.

Name	Type	Description
`offerAutomationResponse`	Object	Information about the offer. The fields depend on the status code.
`offerAutomationResponse.templateId`	String	ID that uniquely identifies the automation template. Only present for status codes 200 and 204 with reasons `REJECTED_BY_CUSTOMER`, `REJECTED_BY_GUARDRAILS`, or `AUTOMATION_ALREADY_ENABLED`.
`offerAutomationResponse.reason`	String	The reason the automation offer was rejected. Only present for status code 204. Valid values: `REJECTED_BY_CUSTOMER`, `REJECTED_BY_GUARDRAILS`, `AUTOMATION_ALREADY_ENABLED`, `CUSTOMER_MISSING_REQUIRED_DEVICE_SETTING`.
`offerAutomationResponse.errorMessage`	String	Message that describes the error. Only present for status codes 400 and 403. Example error message for status code 400: `automation.trigger.<field_name> is a required field`. Example error message for status code 403: `requester skill not allowed to invoke AMAZON.OfferAutomation task`.

Status codes

Status code	Message	Description
200	Automation successfully enabled	The offer was accepted and the routine was enabled. Returns a string that contains a `templateId` that uniquely identifies the automation template, which is a combination of a trigger and actions.
204	Automation offer rejected	The offer was rejected. Returns a string that contains the `reason` the automation offer was rejected and a `templateId` that uniquely identifies the automation template, which is a combination of a trigger and actions. Examples of `reason`: `REJECTED_BY_CUSTOMER`, `REJECTED_BY_GUARDRAILS`, `AUTOMATION_ALREADY_ENABLED`, `CUSTOMER_MISSING_REQUIRED_DEVICE_SETTING`.
400	Validation error	The server can't process the request due to a client error. Returns a string that contains an `errorMessage` that describes the validation error. Example: "automation.trigger. is a required field."
403	Authorization error	The skill doesn't have access to the resource. Returns a string that contains an `errorMessage` that describes the authorization error. Example: "requester skill not allowed to invoke `AMAZON.OfferAutomation` task."
500	Server error	A transient error occurred in the Alexa platform. The user didn't receive the routine prompt and you can retry the request in a future skill session.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023