Your Alexa Consoles
Sign In
Sign In

Proactive Events Schemas

See ProactiveEvents API for more information about setting up your skill service to use proactive events. This document describes event schemas that are supported by the ProactiveEvents API.

Standard event structure

{
    "name": "SampleEventName",
    "payload": {
        "sampleAttribute": {
            "nestedStringAttribute": "sampleValue"
        },
        "anotherSampleAttribute": {
            "nestedIntegerAttribute": 1,
            "nestedFloatAttribute": 10.5
        }
    }
}

Event name convention and template

The event name should always be prefixed with AMAZON. as the namespace. The event name itself should consist of two parts, with the two parts split with '.'. The first part of the event name specifies the subject that is described by the event, and the second part of the event name describes the reason that causes the event to be generated. The structure template is as follows:

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

Event catalog

This list the types of events you can use in your skill.

Event description Desired user experience Event name
Weather alert "There is an extreme weather alert for your area. Open AlexaWeather and ask for alerts to hear more details." AMAZON.WeatherAlert.Activated
Soccer score update MyLeague match update, Oranges 1, Apples 2 AMAZON.SportsEvent.Updated
Message reminder You have <number> <messageFreshness> <messageStatus> <urgency> <message/messages> from <sender> AMAZON.MessageAlert.Activated
Order status update Your preorder from <company> has been received
Your order from <company> has been received
Your order from <company> is being prepared
Your order from <company> has been shipped and will arrive <date>
Your order from <company> is out for delivery and will arrive <date>
Your order from <company> was delivered <date>
Your order from <company> has been delivered		 AMAZON.OrderStatus.Updated
Reservation confirmation Your <reservation/appointment> at <company> for <content of occasion> on <date> has been <confirmed/cancelled/rescheduled> AMAZON.Occasion.Updated
Trash collection reminder Tomorrow is <garbage_type> collection day AMAZON.TrashCollectionAlert.Activated
Social game invitation Your <friend/contact> <contactName> has <invited/challenged> you to a <match/rematch/game> of <gameName> AMAZON.SocialGameInvite.Available
Media content availability notification <programmingName> will <air/stream/release/premiere> on
<date> on <providerName>		 AMAZON.MediaContent.Available

AMAZON.WeatherAlert.Activated

Purpose: Weather alert

Desired user experience: "There is a <weatherAlert> alert for your area. Provided by <source>."

Payload parameters

Contains the parameters for the payload object.

Name Required Type Multi-Locale Support Description
weatherAlert Yes WeatherAlert    
weatherAlert.source No String Yes  
weatherAlert.alertType Yes WeatherAlertType   One of: TORNADO, HURRICANE, SNOW_STORM, THUNDER_STORM

Example

{
    "name": "AMAZON.WeatherAlert.Activated",
    "payload": {
        "weatherAlert": {
            "source": "localizedattribute:source",
            "alertType": "TORNADO"
        }
    }
}

AMAZON.SportsEvent.Updated

Purpose: Soccer event score update

Desired user experience: "MyLeague match update, Apples scored! Oranges 1, Apples 2"

Payload parameters

Parameters for the payload object.

Name Required Type Multi-Locale Support Description
update No Goal    
update.ScoreEarned Yes integer    
update.teamName Yes string No  
sportsEvent Yes SportsEvent    
sportsEvent.eventLeague Yes Soccer    
sportsEvent.EventLeague.name Yes string Yes  
sportsEvent.homeTeamStatistic Yes GameStatistic    
sportsEvent.homeTeamStatistic.team Yes SportsTeam    
sportsEvent.homeTeamStatistic.team.name Yes string No  
sportsEvent.homeTeamStatistic.score Yes integer    
sportsEvent.awayTeamStatistic Yes GameStatistic    
sportsEvent.awayTeamStatistic.team Yes SportsTeam    
sportsEvent.awayTeamStatistic.team.name Yes string No  
sportsEvent.awayTeamStatistic.score Yes integer    

Example

{
    "name": "AMAZON.SportsEvent.Updated",
    "payload": {
        "update": {
            "scoreEarned": 1,
            "teamName": "Arsenal"
        },
        "sportsEvent": {
            "eventLeague": {
                "name": "localizedattribute:eventLeagueName"
            },
            "homeTeamStatistic": {
                "team": {
                    "name": "Oranges"
                },
                "score": 1
            },
            "awayTeamStatistic": {
                "team": {
                    "name": "Apples"
                },
                "score": 2
            }
        }
    }
}

AMAZON.MessageAlert.Activated

Purpose: Message reminder

Desired user experience: "You have <number> <messageFreshness> <messageStatus> <urgency> message/messages from <sender>".

Payload parameters

Name Required Type Multi-Locale Support Description
state Yes MessageState    
state.status Yes MessageStatus   One of: UNREAD, FLAGGED
state.freshness No MessageFreshness   One of: NEW, OVERDUE
messageGroup Yes MessageGroup    
messageGroup.creator Yes Person    
messageGroup.creator.name Yes string No  
messageGroup.count Yes integer    
messageGroup.urgency No urgency   If used, the value is URGENT.

Example

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

AMAZON.OrderStatus.Updated

Purpose: Order status update

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

Depending on the OrderStatus enum value, the CX from this schema will be as follows:

  • PREORDER_RECEIVED: Your preorder from <company> has been received
  • ORDER_RECEIVED: Your order from <company> has been received
  • ORDER_PREPARING: Your order from <company> is being prepared
  • ORDER_SHIPPED: Your order from <company> has been shipped and will arrive by <date>
  • ORDER_OUT_FOR_DELIVERY: Your order from <company> is out for delivery and will arrive by <datetime>
  • ORDER_DELIVERED: Your order from <company> was delivered on <date>
  • ORDER_DELIVERED: Your order from <company> has been delivered

Payload parameters

Name Required Type Multi-Locale Support Description
state Yes OrderState    
state.status Yes OrderStatus   One of: PREORDER_RECEIVED, ORDER_RECEIVED, ORDER_PREPARING, ORDER_SHIPPED, ORDER_OUT_FOR_DELIVERY, ORDER_OUT_FOR_DELIVERY, ORDER_DELIVERED
state.enterTimeStamp No dateTime    
state.deliveryDetails No ParcelDelivery    
order Yes Order    

Examples

Your preorder from <company> has been received:


{
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
        "state": {
            "status": "PREORDER_RECEIVED"
        },
        "order": {
            "seller": {
                "name": "localizedattribute:sellerName"
            }
        }
    }
}

Your order from <company> has been received:


{
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
        "state": {
            "status": "ORDER_RECEIVED"
        },
        "order": {
            "seller": {
                "name": "localizedattribute:sellerName"
            }
        }
    }
}

Your order from <company> has been shipped and will arrive <date>:


{
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
        "state": {
            "status": "ORDER_SHIPPED",
            "deliveryDetails": {
                "expectedArrival": "2018-12-14T23:32:00.463Z"
            }
        },
        "order": {
            "seller": {
                "name": "localizedattribute:sellerName"
            }
        }
    }
}

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


{
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
        "state": {
            "status": "ORDER_OUT_FOR_DELIVERY",
            "deliveryDetails": {
                "expectedArrival": "2018-09-16T22:10:01.00Z"
            }
        },
        "order": {
            "seller": {
                "name": "localizedattribute:sellerName"
            }
        }
    }
}

Your order from <company> was delivered <date>:

{
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
        "state": {
            "status": "ORDER_DELIVERED",
            "enterTimestamp": "20180916T030000Z   2018-09-16T03:00:00.463Z"
        },
        "order": {
            "seller": {
                "name": "localizedattribute:sellerName"
            }
        }
    }
}

Your order from <company> has been delivered:


{
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
        "state": {
            "status": "ORDER_DELIVERED"
        },
        "order": {
            "seller": {
                "name": "localizedattribute:sellerName"
            }
        }
    }
}

AMAZON.Occasion.Updated

Purpose: Reservation confirmation

Desired user experience: "Your <reservation/appointment> at <company> for <subject> on <date> has been <requested/created/confirmed/cancelled/rescheduled>. Please say 'ask <skill name> to review'".

Payload parameters

Name Required Type Multi-Locale Support Description
state Yes ConfirmationState    
state.confirmationStatus Yes ConfirmationStatus One of: CONFIRMED, CANCELED, RESCHEDULED, REQUESTED, CREATED, UPDATED  
occasion Yes Occasion    
occasion.occasionType Yes OccasionType   One of: RESERVATION_REQUEST, RESERVATION, APPOINTMENT_REQUEST, APPOINTMENT
occasion.subject Yes string Yes  
occasion.provider Yes Organization    
occasion.provider.name Yes string Yes  
occasion.bookingTime Yes dateTime    
occasion.broker No Skill    
occasion.broker.name Yes string Yes  

Example

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

AMAZON.TrashCollectionAlert.Activated

Purpose: Garbage collection reminder

Desired user experience: "The coming <day_of_the_week> is <garbage_type> collection day"

Payload parameters

Name Required Type Multi-Locale Support Description
alert Yes TrashCollectionAlert   Contains information about the
alert.garbageTypes Yes GarbageType[]   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   One of: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY

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.

Desired user experience: "<programmingName> will <air/stream/release/premiere> on <date> on <providerName>"

payload parameters

Contains the parameters for the payload object.

Name Required Type Multi-Locale Support Description
availability Yes Availability   Provides availability information
availability.startTime Yes string    
availability.provider No Thing   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   Contains information about the creative work
content.name Yes string Yes Name of the creative work.
content.contentType Yes MediaTypes   One of: BOOK, EPISODE, ALBUM, SINGLE, MOVIE, GAME

Event

{
    "name": "AMAZON.MediaContent.Available",
    "payload": {
        "availability": {
            "startTime": "2018-11-20T21:00:00Z",
            "provider": {
                "name": "localizedattribute:providerName"
            },
            "method":"AIR"
        },
        "content": {
            "name": "localizedattribute:contentName",
            "contentType":"BOOK"
        }
    }
}

AMAZON.SocialGameInvite.Available

Purpose: Send an invitation to a game Desired user experience: "Your <friend/contact> <contactName> has <invited/challenged> you to a <match/rematch/game> of <gameName>"

payload parameters

These parameters are found in the payload object.

Name Required Type Multi-Locale Support Description
invite Yes GameInvite   Object that contains invite information.
invite.inviter Yes Person   Object that contains information about the inviter.
invite.inviter.name Yes string No Name of the inviter.
invite.inviter.relationshipToInvitee Yes enum   One of: FRIEND, CONTACT
invite.inviter.inviteType Yes enum   One of: CHALLENGE, INVITE
game Yes Game   Object that contains game information
game.offer Yes OfferType   One of: MATCH, REMATCH, GAME
game.name Yes string   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

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