Note: Sign in to the developer console to build or publish your skill.
Note: The use of custom triggers for routines is offered as a developer preview and might change as Amazon receives feedback and iterates on the feature. If you have published an Alexa skill and would like to participate in developer preview, contact Amazon and get a sneak peek into the workings of the custom triggers for routines.
With dynamic parameters, you can use custom triggers and parameters that aren't predefined in the trigger definition file. Instead these parameters are returned through the interfaces that your skill supports. One common use case is to use dynamic parameters to show options that are specific to a customer.
Important:
• Amazon doesn't enforce that the dynamic parameters you return are backward compatible. If you change the format of the values that you return in your dynamic parameters or change the values that refer to the same parameter and your customers created routines based on your previous values, their routines will stop working unless you continue to send events that use the previous values and format. Make sure not to change any values in a backward incompatible way so that your customers have an uninterrupted experience.
• Dynamic parameter GET responses don't accept iconUrl. If you send an iconUrl attribute in the response, it is ingored.
The following examples use dynamic parameters to send triggers in a routines skill.
Trigger for battery low alerts
The following example shows how to set the radio battery low as a custom trigger. In the example, the fictitious radio is named MyRadioPlayer. Because this trigger requires that you specify the device for which a trigger instance should be published when the battery is low, this trigger needs to use dynamic parameters.
Trigger definition
The following example shows the trigger definition for MyRadioPlayerBatteryLow.
Copied to clipboard.
>skill-package/>routines/>triggers/>MyRadioPlayerBatteryLow/>en-US.json>skills.json//en-US.json{"name":"MyRadioPlayerBatteryLow","display":{"title":"Battery Low","description":"Start a routine when your My Radio Player's battery is low.","iconUrl":"https://<url-to-MyRadioPlayer-icon>"},"parameters":[{"name":"deviceId",//endpointIDforMyRadioPlayerdevice"schema":{"type":"enum",//UseenumbecausealistofpossibledevicesisreturnedinRoutines.TriggerParameter.Getrequest"dynamicConfig":{//DefinethisobjectbecausepossibledeviceIdvaluesmustberetrievedforeachuniquecustomer.ItisnormaltohaveanemptydynamicConfig.}},"display":{"title":"Device","description":"Your MyRadioPlayer device",//Allenumoptionsshouldhaveadescription,ornoneofthemshouldhaveadescription.Youcan'tmixandmatch."iconUrl":"https://<url-to-MyRadioPlayer-icon>"}}],"accountLinkingRequired":"REQUIRED",//MustbeREQUIREDifanydynamicparametersexistthatrequireaccountspecificinformation"delivery":"UNICAST","displayCategories":["RADIO"],"keywords":["radio","player","smarthome"]}
Routines.TriggerParameter.Get Service Provider Interface (SPI) handler
The endpoint in the skill manifest for a UNICAST skill for handling Routines.Trigger.Create and Routines.Trigger.Delete requests must also be able to handle Routines.TriggerParameter.Get requests.
For this trigger, the custom triggers platform sends the following request to retrieve the possible values for the MyRadioPlayer device ID.
When the customer saves a routine with your trigger with dynamic parameters, you should expect the parameters in the SPI callback to contain those dynamic values. For example,
After the customer saves the routine, you send trigger instances with parameter values that match what was in the Routines.Trigger.Create SPI callback. The following example shows instances with values that match what was in the Routines.Trigger.Create SPI callback.
The following example shows how to set a maintenance reminder as a custom trigger. Because this trigger requires that you specify the device for which a trigger instance should be published and has a second parameter for the maintenance type, which is dependent on the device, this trigger needs to use dynamic parameters.
Trigger definition
The following example shows the trigger definition for MyRadioPlayerMaintenanceReminder.
Copied to clipboard.
>skill-package/>routines/>triggers/>MyRadioPLayerMaintenanceReminder/>en-US.json>skills.json//en-US.json{"name":"MyRadioPlayerMaintenanceReminder","display":{"title":"Maintenance Reminders","description":"Start a routine when any of these maintenance reminders occur with you MyRadioPlayer device.","iconUrl":"https://<url-to-MyRadioPlayer-icon>"},"parameters":[//Orderofparametersmatters.Thisistheordercustomersselectthemin.{"name":"deviceId",//DynamicParameter"schema":{//BEGINNEWFIELDSFORdynamicparameters"type":"enum",//enum,int(internallyrepresentedasString)"dynamicConfig":{//addingthisfieldmakesthisparameterdynamic"dependsOn":[]//Optional.Defaultstoempty.Listofparameternameswhoseselectedvaluesthisparameterdependsonfordeterminingitspossiblevalues.MustbeemptyforfirstparameterintheparameterslistforaTrigger.}//ENDNEWFIELDSFORdynamicparameters},"display":{"title":"Device","description":"Your MyRadioPlayer device","iconUrl":"https://<url-to-MyRadioPlayer-icon>"}},{"name":"maintenanceReminderType",//ParameterwithconditionalENUMvalues."schema":{"type":"enum","dynamicConfig":{"dependsOn":["deviceId"]//SpecifiesthatthepossiblevaluesforthisparameterdependonthevalueselectedbycustomerfordeviceId.CanonlycontainparameternamesthatappearbeforethisparameterintheparameterslistforthisTrigger.},},"display":{"title":"Maintenance Reminder","description":"The type of maintenance reminder","iconUrl":"https://<url-to-MyRadioPlayer-icon>"}}],"accountLinkingRequired":"REQUIRED","delivery":"UNICAST","displayCategories":["RADIO"],"keywords":["radio","player","smarthome"]}
Routines.TriggerParameter.Get SPI handler
The endpoint in the skill manifest for a UNICAST skill for handling Routines.Trigger.Create and Routines.Trigger.Delete requests must also be able to handle Routines.TriggerParameter.Get requests.
For this trigger, the custom triggers platform sends two requests: one for getting the possible DeviceId for the device, the other for getting the possible maintenance reminder options for the device selected by the customer.
1. The following example shows the request to retrieve possible values for the MyRadioPlayerDeviceId.
2. The following example shows the request to retrieve the possible values for the maintenanceReminderType based on the customer’s selection for amzn1.alexa.endpoint.uniqueMyRadioPlayerId2.
StatusCode200OkayContent-Type:application/json{"requestId":"<uuid0>","triggerParameter":{"schema":{"values":[//Orderofvaluesisorderinwhichtheyaredisplayedtocustomer//Thelistofselectableparametervaluesreturnedbyyouarebasedonselectionsmadebycustomerforparametersin"dependsOn"list{"value":"cleanSensors","display":{"title":"Clean Sensors","description":"Reminder for when your MyRadioPlayer's sensors need to be cleaned"}},{"value":"replaceBattery","display":{"title":"Replace Battery""description":"Reminder for when your MyRadioPlayer's battery needs to be replaced"}}]}}}
Trigger for charging status changed alerts
The following example shows how to set a charging status changed as a custom trigger. Because this trigger requires that you specify the device for which the trigger instance should be published, this trigger needs to use dynamic parameters. The second parameter chargingStatus is a static enum parameter to indicate the available charging statuses.
Trigger definition
The following example show the trigger definition for MyRadioPlayerChargingStatusChanged.
Copied to clipboard.
>skill-package/>routines/>triggers/>MyRadioPlayerChargingStatusChanged/>en-US.json>skills.json//en-US.json{"name":"MyRadioPlayerChargingStatusChanged","display":{"title":"Chargin Status Changed","description":"Start a routine when the charging status of your MyRadioPlayer reaches the specified status.","iconUrl":"https://<url-to-MyRadioPlayer-icon>"},"parameters":[//Orderofparametersmatters.Thisistheordercustomersselectthemin.{"name":"deviceId",//DynamicParameter"schema":{//BEGINNEWFIELDSFORdynamicparameters"type":"enum",//enum,int(internallyrepresentedasString)"dynamicConfig":{//addingthisfieldmakesthisparameterdynamic"dependsOn":[]//Optional.Defaultstoempty.Listofparameternameswhoseselectedvaluesthisparameterdependsonfordeterminingitspossiblevalues.MustbeemptyforfirstparameterintheparameterslistforaTrigger.}//ENDNEWFIELDSFORdynamicparameters},"display":{"title":"Device","description":"Your MyRadioPlayer device","iconUrl":"https://<url-to-MyRadioPlayer-icon>"}},{"name":"chargingStatus",//ParameterwithENUMvalues."schema":{"type":"enum",//NotethatnodynamicConfigispresentsincethisisnotadynamicparameter."values":[{//Allpossiblevaluesforthisparameter."value":"batteryHalfChargedId","display":{"title":"Half-charged","description":"MyRadioPlayer battery is halfway charged.","iconUrl":"https://<url-to-MyRadioPlayer-icon>"}},{"value":"fullyChargedId","display":{"title":"Fully=charged","description":"MyRadioPlayer battery is fully charged.","iconUrl":"https://<url-to-MyRadioPlayer-icon>"}}]},"display":{"title":"Charging Status","description":"The charging status of the MyRadioPlayer device","iconUrl":"https://<url-to-MyRadioPlayer-icon>"}}],"accountLinkingRequired":"REQUIRED","delivery":"UNICAST","displayCategories":["RADIO"],"keywords":["radio","player","smarthome"]}
Routines.TriggerParameter.Get SPI handler
The endpoint in the skill manifest for a UNICAST skill for handling Routines.Trigger.Create and Routines.Trigger.Delete requests must also be able to handle Routines.TriggerParameter.Get requests.
For this trigger, the custom triggers platform sends the following request to retrieve possible values for the MyRadioPlayerDeviceId. For the chargingStatus field, it is a static enum whose possible values are the same so no request is needed.
The following example shows how to set up a mechanism to post weather messages. You can set up triggers based on specific conditions on messages, but not all conditions are available to all users. Some are exclusive to users with the premium subscription only. Because this trigger must dynamically restrict the options available based on the user's subscription, this trigger needs to use dynamic parameters.
Trigger definition
The following example shows the trigger definition for MyWeatherMessagePosted.
Copied to clipboard.
>skill-package/>routines/>triggers/>MyWeatherMessagePosted/>en-US.json>skills.json//en-US.json{"name":"MyWeatherEvent","display":{"title":"MyWeather Event","description":"Start a routine when any these types of MyWeather events happen.","iconUrl":"https://<url-to-MyWeather-icon>"},"parameters":[//Orderofparametersmatters.Thisistheordercustomersselectthemin.{"name":"eventType","schema":{"type":"enum","dynamicConfig":{"dependsOn":[]//Thisonlydependsontheuser'saccount,nototherparameters}},"display":{"title":"Event Type","description":"The type of event","iconUrl":"https://<url-to-MyWeather-icon>"}}],"accountLinkingRequired":"REQUIRED","delivery":"UNICAST","displayCategories":["OTHER"],"keywords":["weather","messaging"]}
Routines.TriggerParameter.Get SPI handler
The endpoint in the skill manifest for a UNICAST skill for handling Routines.Trigger.Create and Routines.Trigger.Delete requests must also be able to handle Routines.TriggerParameter.Get requests.
For this trigger, the custom triggers platform sends the following request to retrieve the values that the customer should have access to based on whether they have the MyWeather subscription.
You send the following response for a customer with the premium subscription for MyWeather.
Copied to clipboard.
StatusCode200OkayContent-Type:application/json{"requestId":"<uuid0>","triggerParameter":{"schema":{"values":[{"value":"callout","display":{"title":"@ Messages","description":"When you're included in an @ in someone's message."}},{"value":"yourEmote","display":{"title":"Your Emote","description":"When someone uses an emote you made. (MyWeather Only)"}},{"value":"activity","display":{"title":"Activity Start","description":"When an Activity starts in a server you own. (MyWeather only)"}}]}}}
You send the following response for a customer who doesn't subscribe to MyWeather.
Copied to clipboard.
StatusCode200OkayContent-Type:application/json{"requestId":"<uuid0>","triggerParameter":{"schema":{"values":[{"value":"callout","display":{"title":"@ Messages","description":"When you're included in an @ in someone's message."}}]}}}