Pre-Built Routine API Reference

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

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

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.