Custom Interface FAQ

This page contains frequently asked questions about using Custom Interfaces. For a list of known issues, see Known Issues.


Q: What are Custom Interfaces, and how do they relate to the Custom Interface Controller?
Custom Interfaces and the Custom Interface Controller work together to enable a skill and a gadget to exchange messages throughout an Alexa skill session. Custom Interfaces are the groups of gadget-specific directives and events that you define as a first step. For example, if your gadget is a robot that spins around when it wins a match, you might define an interface called Custom.Robot that includes a directive called Spin that instructs the robot to spin, and an event called SpinStatus for the robot to send when it has completed its spin. In your gadget's firmware, you include code to decode and encode these custom directives and events, respectively. By contrast, the Custom Interface Controller is the interface that you use within your skill code to send the custom directives, and receive the custom events, that you defined.
Q: What types of experiences can I create using Custom Interfaces?
You can use Custom Interfaces to design interactive gadget experiences alongside skill content. For example, you might tell a story, establish a play pattern, or simply relay information. Here are some examples:
  • A play jukebox that uses an RFID reader to trigger Alexa to play snippets of musical tunes. The jukebox also uses directives to send light animations while music is playing.
  • A mini keyboard that turns Alexa into a piano teacher, lighting up keys that correspond to a given play sequence and providing the user feedback on whether they have played the right sequence of keys.
  • An interactive brain-teaser game where Alexa offers customers a set of clues, and they must use a keypad to reveal the contents of a mystery vault.
Q: What types of gadget experiences are NOT a good match for Custom Interfaces?
We do not recommend using Custom Interfaces as a primary means to voice-control your gadget. For example, do not use Custom Interfaces to control your gadget with commands like "turn on", "turn off", or "set to low power mode". These will conflict with Alexa's native voice user interface for controlling other connected device types, and result in delivery failure of your gadget message. If you want to enable users to voice-control the state of a device, consider building an Alexa smart home device, where you can use pre-built voice interaction models for common device commands (for an example, see the Alexa.PowerController interface).
Q: I would like to create skill experiences for a kid-directed gadget. Can I use Custom Interfaces?
Not currently. If your company specializes in kid-directed devices, reach out to your Amazon representative for additional guidance.
Q: Can I share my custom directives and events with other developers to create skills for my gadget?
No. At this time, your skill can only use custom directives and events with gadgets that are registered under your Alexa developer account. Skills that are not registered under your account will not have authorization to interact with your gadget.
Q: Along with custom events and directives, can I access any of the other Alexa Gadgets Toolkit interfaces from my skill?
No. The interfaces defined by the Alexa Gadgets Toolkit, such as wake-word detection, notifications, music data, and so on, are not accessible from a skill.

Echo device compatibility

Q: How do I ensure that my Echo device has a software version that works with Custom Interfaces?
First, view this compatibility list to make sure that your Echo device supports gadgets. If so, then check whether your Echo device has the latest software version by doing the following:
  • For Echo devices without a screen – Say "Alexa, update your software."
  • For Echo devices with a screen – On the Echo device, go to Settings > Device Options > Check for Software Updates.

Also note that the minimum software versions that work with the Alexa Gadgets Toolkit are listed in Before you get started. To find the software version of your Echo device, go to the Alexa app under Settings > Device Settings > [device] > About > Device Software Version.

Gadget preparation

Q: How does my gadget prepare to communicate with a skill that uses the Custom Interface Controller?
Upon connection to the Echo device over Bluetooth, your gadget must declare support for the custom interface that you defined. After this declaration is complete, the gadget can send the associated custom events to, and receive directives from, the skill via the Echo device and the Alexa cloud.

Skill creation

Q: How do I set up my skill to send custom directives and receive custom events?
When you set up your skill using the Alexa Skills Kit developer console or the Alexa Skills Kit Command-Line Interface (ASK CLI), make sure to select the Custom Interface Controller interface. This will enable your skill to send custom directives to the gadget and receive custom events from the gadget.

When your skill is in session, it will be able to receive events from your gadget after the skill has started an event handler to "listen" for the event(s). When your skill starts the event handler, it specifies how long to listen for events (maximum of 90 seconds), and how to filter for specific events (for example, from a particular gadget ID, or events under a specific namespace that you assign).

To send custom directives, your skill must first use the Endpoint Enumeration API to query which gadgets are available and connected. You then use the results of the query to target a directive towards one or more available gadgets. You can include directives to trigger behavior on your gadget at any time during the skill session, including upon skill opening, alongside Alexa content like text-to-speech (TTS), audio responses, and so on.
Q: What are the certification requirements for skills that communicate with gadgets?
Skills that use Custom Interfaces are subject to the same policy, security, and functional requirements that apply to all custom skills. As a best practice, you should also indicate in the skill description that your skill is intended to work with a gadget, and whether the gadget is required or optional. Although there are no additional considerations or gadget testing required for skill certification, it is your responsibility to ensure that your gadget functions as marketed to your customers.
Q: Can my skill use the Custom Interface Controller to control other connected devices like Smart Home or Alexa Built-In?
No. At this time, the Customer Interface Controller is only compatible with custom skills and gadgets, and cannot be used with other skill types to create multi-capability skills. If you're an AVS developer and interested in using the Custom Interface Controller to support unique hardware capabilities that are not offered by Alexa APIs, reach out to your Amazon representative.

Custom events

Q: Can a custom event trigger a skill?
No. The skill must already be running and have sent a directive to start an event handler.
Q: How do I keep my skill from automatically exiting after it receives an event from a gadget?
Do two things:
  • When you start the event handler, set filterMatchAction to SEND so that the skill keeps receiving custom events until the event handler expires. (Do not use SEND_AND_TERMINATE.)
  • In the skill's response, ensure that shouldEndSession is undefined (that is, remove it from the response completely).
Q: Can I use the same token for multiple event handlers?
Yes. Tokens do not need to be unique. However, consider your use case. If you want to extend the event handler expiration beyond 90 seconds, you might choose to reuse the token of the previous event handler. On the other hand, you might choose to use unique tokens if you want to make sure that an incoming event is not from an event handler that was recently stopped or replaced. For example, if you start an event handler with token GAME-2, but receive an event with token GAME-1, you might choose to ignore the event.

One approach you can take is to use unique tokens but to name them according to logical groupings, such as GAME-1.1, GAME-1.2, GAME-1.3 (the tokens for the first logical handler), GAME-2.1, GAME-2.2 (the tokens for the second logical handler), and so on.
Q: Do event handlers affect how long the skill session stays open?
Yes. An active event handler can extend the skill session as follows:
  • For Echo devices without a screen – If the user does not respond to Alexa, the session ends immediately, unless there is an active event handler or the skill responded with shouldEndSession equal to false. If an event handler is active, the session stays open until the skill calls StopEventHandler or the event handler times out.
  • For Echo devices with a screen – If the user does not respond to Alexa, the session stays open for 30 seconds, unless there is an active event handler or the skill responded with shouldEndSession equal to false. If an event handler is active, the session stays open until the skill calls StopEventHandler or the event handler times out.

As such, if the skill configures the event handler timeout to be longer than five seconds, the skill's response should include music or sound effects so that the user knows that the skill is still in session.

Custom directives

Q: Can I delay the sending of a directive until after Alexa is finished speaking?
No. However, you can start an event handler with a timeout that matches approximately how long it takes for Alexa to speak the desired speech. Then send the custom directive when the timeout event fires.


Q: Is there a limit on the size or rate of custom events that my gadgets can send, or directives it can receive?
Yes. For limits related to Custom Interfaces, see Limits.
Q: Are there any restrictions on what names I can use for custom events or custom directives?
Yes. For limits related to Custom Interfaces, see Limits.

Was this page helpful?

Last updated: Feb 14, 2022