Content Launcher Best Practices for Handling Voice Requests

Fire TV customers can use natural language commands to search for and play app content, control media playback, and more. The Content Launcher API enables apps to receive and process Alexa commands. The following are best practices to handle Alexa voice for searching and playing content.

Handling quickplay requests directly

A voice cliff is a voice experience that leads to the user needing to pick up the remote control. For any quickplay utterances, the app should avoid a voice cliff.

• Avoid intermediate UI: For quickplay utterances, start playback immediately without showing content detail pages or profile selection screens.
• Use last-used profile: If your app has user profiles, continue playback using the last active profile to minimize user interaction.
• Handle kids profile: If the requested content is not suitable for the current kids profile, show a profile selection screen.

Playing specific episodes

• Avoid showing TV show details pages: Play the requested episode directly without intermediate steps.
• Handle season and episode numbers: Retrieve the correct episode using the provided ID, season, and episode numbers.

• Play the requested episode: If a specific episode is requested, play it directly instead of starting from the beginning of the season.

• Handle season-only requests: If only a season is specified, continue the last watched episode in that season or play the next one. If the option to continue is not available, show a search result screen with all episodes in that season.
• Handle episode-only requests: If an episode is specified, play the episode from the last watched season or the latest season. You may also present a search result screen with options from different seasons.

Resuming partially watched content

If your app maintains the playback state of the content for your users, make sure your app resumes playback of the content using voice requests.

• Continue from the last watched point: Resume playing movies and episodes where the user left off.
• Handle TV shows without episode/season numbers: For TV show watch utterances, if the last episode was already completed, continue to play the last watched episode, or the next episode.

Handling nonspecific play requests

Customers can use generic utterances such as watch by genre name and watch by sports type. Then your app can play relevant content identified by the app-specific algorithm or show a search screen with a list of media results.

• Use app-specific algorithms: Identify relevant content based on the user's preferences or genre.
• Show search results: Present a search screen with relevant options if no specific content is found.
• Consider special pages: Leverage dedicated pages for genres like comedies, action movies, or sports titles to provide a more tailored experience.

Remember to prioritize a seamless user experience by avoiding unnecessary steps to use the Fire TV remote and provide intuitive responses to voice commands.

Consistent and user-friendly search experience

• Make sure the search result page is well-designed, easy to navigate, and presents results in a clear and concise manner.
• Consider incorporating features like filtering, sorting, and pagination to enhance the user experience.

Use Entity Type and Value for search

• Use the entity type and value provided in the search query to refine the search results when your app is invoked. For example, if the user searches for "Arnold Schwarzenegger movies," the app should search for movies featuring Arnold Schwarzenegger as an actor.
• Handle all specified entity types (Actor, Channel, Character, Director, Episode, Event, Franchise, Genre, League, MediaType, Production Company, Season, Sport, SportsTeam, Video, and Popularity) to provide relevant results.

Avoid broken customer experience

Always handle search requests to avoid a broken customer experience. If your app doesn't have in-app search, display a clear message indicating that search functionality isn't supported.

Handling Transport Control requests

Content Launcher does not deliver Transport Control. Handling transport control utterances is mandatory for catalog integrated apps.

• If your app’s media player uses the W3C media player API, use W3C Media integration with Vega Media Controls to handle all transport control utterances, except "Next" and "Previous". "Next" and "Previous" utterances are supported by overriding the media control handler using AppOverrideMediaControlHandler.
• If your app’s media player doesn't use the W3C media player API, use the Vega Media Control API to support transport controls.

---

Last updated: Sep 30, 2025