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
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.
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
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
contentId is immutable. Its state can't be mutated (that is, changed) after the
contentId is initialized. As data changes, new values are created, but the object itself persists.
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
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
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 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