Proactive Events Schemas


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

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

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

AMAZON.SocialGameInvite.Available

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?

Last updated: Nov 29, 2023