Proactive Events Schemas

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

The Proactive Events API supports the event schemas listed and described here. For information about setting up your skill service to use proactive events, see ProactiveEvents API.

Event name convention and template

All proactive event schemas use the same format. All event names start with the prefix AMAZON., which is the namespace name followed by a period (.). The second part of the name describes the type of event and uses camel case followed by a period (.). The third part of the name describes the state of the event. The following example shows the proactive event template.

{
  "event": {
    "name": "AMAZON.EventNamePartOne.EventNamePartTwo",
    "payload": {
      "sampleAttribute": {
        "nestedStringAttribute": "sampleValue"
      },
      "anotherSampleAttribute": {
        "nestedIntegerAttribute": 1,
        "nestedFloatAttribute": 10.5
      }
    }
  }
}

Event catalog

The following table lists the proactive event types you can use in your skill.

Event description	Example notification	Event name
Weather alert	There is a tornado alert for your area. Provided by Example Weather Corp.	`AMAZON.WeatherAlert.Activated`
Sports event update	TreeFruit League match update, Oranges 1, Apples 2.	`AMAZON.SportsEvent.Updated`
Message reminder	You have three new messages from Jane Doe.	`AMAZON.MessageAlert.Activated`
Order status update	Your preorder from Amazon has been received. Your order from Amazon has been received. Your order from Amazon is being prepared. Your order from Amazon has been shipped and will arrive by May 18, 2019. Your order from Amazon is out for delivery and will arrive by May 20, 2019. Your order from Amazon was delivered on May 2, 2019. Your order from Amazon has been delivered.	`AMAZON.OrderStatus.Updated`
Reservation confirmation	Your appointment at Dental XYZ for a root canal on May 10, 2019 has been confirmed.	`AMAZON.Occasion.Updated`
Trash collection reminder	This coming Tuesday is glass collection day.	`AMAZON.TrashCollectionAlert.Activated`
Media content availability notification	Salvage Hunters will air on January 3, 2019 on Amazon Video.	`AMAZON.MediaContent.Available`
Social game invitation notification	Your friend John Stiles has invited you to a game of chess.	`AMAZON.SocialGameInvite.Available`

AMAZON.WeatherAlert.Activated

Note: Currently AMAZON.WeatherAlert.Activated is supported only in the en-US locale.

Purpose: Weather alert.

User notification: "There is a <weatherAlert.alertType> alert for your area. Provided by <weatherAlert.source>."

If you don't provide a source, the Alexa service omits the sentence, "Provided by <weatherAlert.source>."

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`weatherAlert`	Yes	WeatherAlert	N/A	Object that contains weather alert information.
`weatherAlert.source`	No	string	Yes	Source of weather alert information.
`weatherAlert.alertType`	Yes	WeatherAlertType	N/A	One of: `EMERGENT_HEAVY_RAIN`, `EMERGENT_HEAVY_SNOW`, `EMERGENT_SNOW_STORM`, `EMERGENT_STORM`, `EMERGENT_STORM_SURGE`, `EMERGENT_WAVE`, `FLOOD`, `HEAVY_RAIN`, `HEAVY_SNOW`, `HURRICANE`, `SNOW_STORM`, `STORM`, `STORM_SURGE`, `THUNDER_STORM`, `TORNADO`, `WAVE`.

localizedAttributes parameters

Parameters used for each item in the localizedAttributes array. Each item includes a locale and source, so each supported locale has an item in the array. The only localizedAttrributes for which you provide locale-specific values are strings. Enum values are automatically localized.

Name	Required	Type	Description
`locale`	Yes	enum	One of the supported locales, such as "en-US".
`source`	Yes	string	Information source.

Example

{
  "event": {
    "name": "AMAZON.WeatherAlert.Activated",
    "payload": {
      "weatherAlert": {
        "source": "localizedattribute:source",
        "alertType": "TORNADO"
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "source": "Example Weather Corp"
    }
  ]
}

AMAZON.SportsEvent.Updated

Purpose: Soccer event score update

User notification: "<sportsEvent.eventLeague.name> match update, <update.teamName> scored! <sportsEvent.awayTeamStatistic.team.name> <sportsEvent.awayTeamStatistic.score>, <sportsEvent.homeTeamStatistic.team.name> <sportsEvent.homeTeamStatistic.score>"

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support
`update`	No	Goal	N/A
`update.scoreEarned`	Yes	integer	N/A
`update.teamName`	Yes	string	No
`sportsEvent`	Yes	SportsEvent	N/A
`sportsEvent.eventLeague`	Yes	Soccer	N/A
`sportsEvent.eventLeague.name`	Yes	string	Yes
`sportsEvent.homeTeamStatistic`	Yes	GameStatistic	N/A
`sportsEvent.homeTeamStatistic.team`	Yes	SportsTeam	N/A
`sportsEvent.homeTeamStatistic.team.name`	Yes	string	No
`sportsEvent.homeTeamStatistic.score`	Yes	integer	N/A
`sportsEvent.awayTeamStatistic`	Yes	GameStatistic	N/A
`sportsEvent.awayTeamStatistic.team`	Yes	SportsTeam	N/A
`sportsEvent.awayTeamStatistic.team.name`	Yes	string	No
`sportsEvent.awayTeamStatistic.score`	Yes	integer	N/A

localizedAttributes parameters

Parameters used for each item in the localizedAttributes array. Each item includes a locale and eventLeagueName, so each supported locale has an item in the array.

Name	Required	Type	Description
`locale`	Yes	enum	One of the supported locales, such as "en-US".
`eventLeagueName`	Yes	string	Name of the league for the event.

Example

{
  "event": {
    "name": "AMAZON.SportsEvent.Updated",
    "payload": {
      "update": {
        "scoreEarned": 1,
        "teamName": "Apples"
      },
      "sportsEvent": {
        "eventLeague": {
          "name": "localizedattribute:eventLeagueName"
        },
        "homeTeamStatistic": {
          "team": {
            "name": "Oranges"
          },
          "score": 1
        },
        "awayTeamStatistic": {
          "team": {
            "name": "Apples"
          },
          "score": 2
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "eventLeagueName": "TreeFruit League"
    }
  ]
}

AMAZON.MessageAlert.Activated

Purpose: Message reminder.

User notification: "You have <messageGroup.count> <state.freshness> <state.status> message/messages from <messageGroup.creator.name>."

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`state`	Yes	MessageState	N/A	Object that describes the message state.
`state.status`	Yes	MessageStatus	No	One of: `UNREAD`, `FLAGGED`.
`state.freshness`	No	MessageFreshness	N/A	One of: `NEW`, `OVERDUE`.
`messageGroup`	Yes	MessageGroup	N/A	Object that describes a message group.
`messageGroup.creator`	Yes	Person	N/A	Object that describes the creator of the message group.
`messageGroup.creator.name`	Yes	string	No	Name of the creator of the message group.
`messageGroup.count`	Yes	integer	N/A	Number of messages in the group.

Example

{
  "event": {
    "name": "AMAZON.MessageAlert.Activated",
    "payload": {
      "state": {
        "status": "UNREAD",
        "freshness": "NEW"
      },
      "messageGroup": {
        "creator": {
          "name": "Andy"
        },
        "count": 5
      }
    }
  }
}

AMAZON.OrderStatus.Updated

Note: Currently AMAZON.OrderStatus.Updated is supported only in the en-US locale.

Purpose: Order status update.

User notification: The user experience will depend on the OrderStatus enum value, as follows:

PREORDER_RECEIVED: Your preorder from <order.seller.name> has been received.
ORDER_RECEIVED: Your order from <order.seller.name> has been received.
ORDER_PREPARING: Your order from <order.seller.name> is being prepared.
ORDER_SHIPPED: Your order from <order.seller.name> has been shipped and will arrive by <state.deliveryDetails.expectedArrival>.
ORDER_OUT_FOR_DELIVERY: Your order from <order.seller.name> is out for delivery and will arrive by <state.deliveryDetails.expectedArrival>.
ORDER_DELIVERED: Your order from <order.seller.name> was delivered on <state.deliveredOn>.
ORDER_DELIVERED: Your order from <order.seller.name> has been delivered.

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`state`	Yes	OrderState	N/A	Object that describes the state of the order.
`state.status`	Yes	OrderStatus	N/A	One of: `PREORDER_RECEIVED`, `ORDER_RECEIVED`, `ORDER_PREPARING`, `ORDER_SHIPPED`, `ORDER_OUT_FOR_DELIVERY`, `ORDER_OUT_FOR_DELIVERY`, `ORDER_DELIVERED`.
`state.enterTimeStamp`	No	dateTime	N/A	Time of the event. Example value: `20190915T182219Z`.
`state.deliveryDetails`	No	ParcelDelivery	N/A	Object that describes delivery details.
`order`	Yes	Order	No	Object that describes the order.
`order.seller`	Yes	Seller	No	Object that describes the seller of the order.
`order.seller.name`	Yes	string	Yes	Name of the seller of the order.

localizedAttributes parameters

Parameters used for each item in the localizedAttributes array. Each item includes a locale and sellerName, so each supported locale has an item in the array.

Name	Required	Type	Description
`locale`	Yes	enum	One of the supported locales, such as "en-US".
`sellerName`	Yes	string	Name of the seller.

Examples

Your preorder from <order.seller.name> has been received:

{
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "PREORDER_RECEIVED"
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "sellerName": "Amazon"
    },
    {
      "locale": "de-DE",
      "sellerName": "Amazon"
    }
  ]
}

Your order from <order.seller.name> has been received:

{
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "ORDER_RECEIVED"
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "sellerName": "Amazon"
    },
    {
      "locale": "de-DE",
      "sellerName": "Amazon"
    }
  ]
}

Your order from <order.seller.name> has been shipped and will arrive <date>:

{
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "ORDER_SHIPPED",
        "deliveryDetails": {
          "expectedArrival": "2018-11-23T18:25:43.511Z"
        }
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "sellerName": "Amazon"
    },
    {
      "locale": "de-DE",
      "sellerName": "Amazon"
    }
  ]
}

Your order from <order.seller.name> is out for delivery, and will arrive by <datetime>:

{
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "ORDER_OUT_FOR_DELIVERY",
        "deliveryDetails": {
          "expectedArrival": "2018-11-23T18:25:43.511Z"
        }
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "sellerName": "Amazon"
    },
    {
      "locale": "de-DE",
      "sellerName": "Amazon"
    }
  ]
}

Your order from <order.seller.name> was delivered <date>:

{
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "ORDER_DELIVERED",
        "deliveredOn": "2018-11-23T18:25:43.511Z"
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "sellerName": "Amazon"
    },
    {
      "locale": "de-DE",
      "sellerName": "Amazon"
    }
  ]
}

Your order from <order.seller.name> has been delivered:

{
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "ORDER_DELIVERED"
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "sellerName": "Amazon"
    },
    {
      "locale": "de-DE",
      "sellerName": "Amazon"
    }
  ]
}

AMAZON.Occasion.Updated

Purpose: Reservation confirmation.

User notification: "Your <occasion.occasionType> at <occasion.provider.name> for <occasion.subject> on <occasion.bookingTime> has been <state.confirmationStatus>. Please say 'ask <skill name> to review'."

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`state`	Yes	ConfirmationState	N/A	Object that describes the state of the order.
`state.confirmationStatus`	Yes	ConfirmationStatus	No	One of: `CONFIRMED`, `CANCELED`, `RESCHEDULED`, `REQUESTED`, `CREATED`, `UPDATED`.
`occasion`	Yes	Occasion	N/A	Object that describes the occasion.
`occasion.occasionType`	Yes	OccasionType	No	One of: `RESERVATION_REQUEST`, `RESERVATION`, `APPOINTMENT_REQUEST`, `APPOINTMENT`.
`occasion.subject`	Yes	string	Yes	Subject of the occasion.
`occasion.provider`	Yes	Organization	N/A	Object that describes the provider of the occasion.
`occasion.provider.name`	Yes	string	Yes	Name of the provider of the occasion.
`occasion.bookingTime`	Yes	dateTime	No	Booking time of the occasion. Example: `20190415T162219Z`.
`occasion.broker`	No	Skill	N/A	Object that describes the broker of the occasion.
`occasion.broker.name`	Yes	string	Yes	Name of the broker of the occasion.

localizedAttributes parameters

Parameters used for each item in the localizedAttributes array. Each supported locale has an item in the array.

Name	Required	Type	Description
`locale`	Yes	enum	One of the supported locales, such as "en-US".
`subject`	Yes	string	Description of the appointment or reservation, such as "root canal".
`providerName`	Yes	string	Name of the provider, such as the doctor's or restaurant's name.
`brokerName`	Yes	string	Name of the broker, which may be the same as `providerName`, or a third party.

Example

{
  "event": {
    "name": "AMAZON.Occasion.Updated",
    "payload": {
      "state": {
        "confirmationStatus": "CONFIRMED"
      },
      "occasion": {
        "occasionType": "APPOINTMENT",
        "subject": "localizedattribute:subject",
        "provider": {
          "name": "localizedattribute:providerName"
        },
        "bookingTime": "2018-11-20T19:16:31Z",
        "broker": {
          "name": "localizedattribute:brokerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "subject": "root canal",
      "providerName": "Dental XYZ",
      "brokerName": "Dental XYZ"
    }
  ]
}

AMAZON.TrashCollectionAlert.Activated

Purpose: Trash collection reminder.

User notification: "The coming <alert.collectionDayOfWeek> is <alert.garbageTypes*> collection day."

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`alert`	Yes	TrashCollectionAlert	N/A	Object that describes the trash collection alert.
`alert.garbageTypes`	Yes	GarbageType[]	No	A list of GarbageType values, with a size between 1-5. Possible values include: `BOTTLES`, `BULKY`, `BURNABLE`, `CANS`, `CLOTHING`, `COMPOSTABLE`, `CRUSHABLE`, `GARDEN_WASTE`, `GLASS`, `HAZARDOUS`, `HOME_APPLIANCES`, `KITCHEN_WASTE`, `LANDFILL`, `PET_BOTTLES`, `RECYCLABLE_PLASTICS`, `WASTE_PAPER`.
`alert.collectionDayOfWeek`	Yes	DayOfWeek	No	One of: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.

Event

{
  "event": {
    "name": "AMAZON.TrashCollectionAlert.Activated",
    "payload": {
      "alert": {
        "garbageTypes": [
          "COMPOSTABLE",
          "RECYCLABLE_PLASTICS"
        ],
        "collectionDayOfWeek": "TUESDAY"
      }
    }
  }
}

AMAZON.MediaContent.Available

Purpose: Provides information about when a particular creative work is available, and on which provider.

User notification: "<content.name> will <availability.method> on <availability.startTime> on <availability.provider.name>."

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`availability`	Yes	Availability	N/A	Object that provides availability information.
`availability.startTime`	Yes	dateTime	No	Start time of availability. Example: `2020-11-20T21:00:00Z`.
`availability.provider`	No	Thing	N/A	Object that describes provider information.
`availability.provider.name`	Yes	string	Yes	Name of the provider.
`availability.method`	Yes	DistributionMethod		Method of distribution. One of: `STREAM`, `AIR`, `RELEASE`, `PREMIERE`, `DROP`.
`content`	Yes	CreativeWork	N/A	Object that contains information about the creative work.
`content.name`	Yes	string	Yes	Name of the creative work.
`content.contentType`	Yes	MediaTypes	No	One of: `BOOK`, `EPISODE`, `ALBUM`, `SINGLE`, `MOVIE`, `GAME`.

localizedAttributes parameters

These parameters are used for each item in the localizedAttributes array. Each item includes a locale, providerName, and contentName, so each supported locale has an item in the array.

Name	Required	Type	Description
`locale`	Yes	enum	One of the supported locales, such as "en-US".
`providerName`	Yes	string	Content provider name, such as "Amazon Video".
`contentName`	Yes	string	Name of the content, such as "Salvage Hunters".

Event

{
  "event": {
    "name": "AMAZON.MediaContent.Available",
    "payload": {
      "availability": {
        "startTime": "2028-11-20T21:00:00Z",
        "provider": {
          "name": "localizedattribute:providerName"
        },
        "method": "AIR"
      },
      "content": {
          "name": "localizedattribute:contentName",
          "contentType": "EPISODE"
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "providerName": "Amazon Video",
      "contentName": "Salvage Hunters"
    }
  ]
}

Note: Currently AMAZON.SocialGameInvite.Available is supported only in the en-US locale.

Purpose: Send a notification of an invitation to a game.

"User notification: "Your <invite.inviter.relationshipToInvitee> <invite.inviter.name> has <invite.inviteType> you to a <game.offer> of <game.name>."

payload parameters

Parameters for the payload object.

Name	Required	Type	Multi-Locale Support	Description
`invite`	Yes	GameInvite	N/A	Object that contains invite information.
`invite.inviter`	Yes	Person	N/A	Object that contains information about the inviter.
`invite.inviter.name`	Yes	string	No	Name of the inviter.
`invite.inviter.relationshipToInvitee`	Yes	enum	No	One of: `FRIEND`, `CONTACT`.
`invite.inviter.inviteType`	Yes	enum	No	One of: `CHALLENGE`, `INVITE`.
`game`	Yes	Game	N/A	Object that contains game information.
`game.offer`	Yes	OfferType	No	One of: `MATCH`, `REMATCH`, `GAME`.
`game.name`	Yes	string	Yes	Name of the game.

localizedAttributes parameters

These parameters are used for each item in the localizedAttributes array. Each item includes a locale and gameName, so each supported locale has an item in the array.

Name	Required	Type	Description
`locale`	Yes	enum	One of the supported locales, such as "en-US".
`gameName`	Yes	string	Name of the game, which may vary by locale.

Event

{
  "event": {
    "name": "AMAZON.SocialGameInvite.Available",
    "payload": {
      "invite": {
        "relationshipToInvitee": "FRIEND",
        "inviter": {
          "name": "Max"
        },
        "inviteType": "CHALLENGE"
      },
      "game": {
        "offer": "GAME",
        "name": "localizedattribute:gameName"
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "en-US",
      "gameName": "The Red"
    },
    {
      "locale": "fr-FR",
      "gameName": "Le rouge"
    }
  ]
}

Was this page helpful?

Provide feedback

Last updated: Nov 29, 2023