Understand contentId

To build a high-quality music or podcast skill, you must use the contentId field correctly. The contentId identifies a music track, an editorial playlist of popular songs, a custom (artist-based or genre-based) station, an album, or a podcast episode, season, or series.

Attributes of the contentId

The contentId assigned to each item must be unique, persistent, and consistent. The stability of the contentId ensures that your service remains reliable and provides the same experience to all users.

Uniqueness

Each contentId you assign must be globally unique within your skill. For example, imagine that a user says, "Alexa, play the album Bat Out of Hell, by Meatloaf." Your skill returns a contentId of 123 to represent the album. This contentId identifies this album and only this album. The uniqueness of the ID ensures that when another user asks for the same album, your skill returns the same content in response to the GetPlayableContent request.

Persistence

An item's contentId must persist even if the content itself changes. For example, imagine that your music service offers a Top Weekly Songs playlist that changes from week to week, as new tracks reach the top the charts. A user says, "Alexa, play the Top Weekly Songs playlist." Your skill responds with a contentId of 321, which represents the requested playlist. When Alexa sends this contentId in an Initiate request, your skill returns the first track of the playlist, such as "Shallow," by Lady Gaga. A month later, the user says, "Alexa, play the Top Weekly Songs playlist". Your skill again responds with a contentId of 321, because that contentId always represents the Top Weekly Songs playlist. The first track in the playlist is different, however, because a different song is in the top spot that week.

When a user sets a podcast alarm (for example, "Alexa, wake me up to the Today Explained podcast at 8 AM"), Alexa saves the contentId returned in the GetPlayableContent response. Alexa then sends your skill a daily Initiate request with the same saved contentId every time. The program played is different from day to day, because the podcast episode changes daily, but the user still hears the Today Explained podcast series associated with the saved contentId.

Consistency

The contentId ensures that all users with the same request have the same experience, no matter where they are or when they make the request. For example, when a user in Naperville, Illinois, sets a music alarm ("Alexa, wake me up at 6 AM to 'Don't Stop Believing,' by Journey."), Alexa saves the contentId returned in the GetPlayableContent response. Your skill uses this contentId to execute the alarm every morning until the user cancels or changes it. When a user in Napa, California, asks Alexa to wake them up to the same Journey song eight months later, Alexa sends your skill an Initiate request with the same contentId it returned for the Naperville user's alarm.

Was this page helpful?

Last updated: Nov 27, 2023