Alexa.Media.Search Interface

Implement the Alexa.Media.Search interface to enable your Alexa skill to search for content that a user has requested.

When a user requests content from your skill, Alexa sends a GetPlayableContent request to your skill. For example, if a user says "Alexa, play Alive from the album Ten on skill name", the skill receives a GetPlayableContent request that contains information about the user and the requested content. The skill can respond with a content identifier that represents the song Alive from the album Ten. If the skill cannot satisfy the request—for example, the user's subscription tier does not support the content, or geographic streaming rights do not allow streaming to the user's location—the skill can respond with the appropriate error code.

The response does not initiate playback of audio on the device, it only indicates whether the skill has audio content that satisfies the request. If the Alexa service determines that the audio content should be played, a subsequent Initiate request is made.

Utterances

When you use the Alexa.Media.Search interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, play music on <skill name>.
Alexa, play Soundgarden on <skill name>.
Alexa, play Alive by Pearl Jam on <skill name>.
Alexa, play the album Nevermind by Nirvana on <skill name>.
Alexa, play the playlist Party Hits on <skill name>.
Alexa, play rock music on <skill name>.
Alexa, play the Summertime station on <skill name>.
Alexa, wake me up to rock music on <skill name> at seven-thirty AM.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Configure your skill to receive requests

You must configure your music skill to support this API before Alexa will send requests to it. You can configure your skill in the following ways:

Properties and Objects

The content object

The content object is the primary object for the Alexa.Media.Search interface. A content object includes an identifier and metadata. A content object can represent a single track, an album, a playlist, a custom station, or a live station. Content objects are global and can be shared between different users. For example, if Content object 1234 is the album "King Animal" by Soundgarden, this is true for any user who receives Content object 1234, and if a user receives Content object 1234 a year later, it should still represent the album "King Animal" by Soundgarden.

Understand ContentId

To build a high quality music skill, you must understand ContentId. ContentId identifies a music listening experience that a skill can return and play on a device. A ContentId can reference a track, an editorial playlist of popular songs, a custom (artist or genre seeded) station, or an album.

ContentId must be globally unique within your skill, long-lived, and always represent the same experience for all skill users. For example, imagine that Alice asks "Alexa, play the album Rainier Fog by Alice in Chains", and the skill returns a ContentId of "123" to represent the album. This same ContentId should represent this album for all users. When Bob asks "Alexa, play the album Rainier Fog by Alice in Chains", your skill should send the same ContentId of "123" in response to the GetPlayableContent request, even if the request happens one year after Alice's request.

Here is another example: Imagine that your music service has a "Top Weekly Songs" playlist, where the list of songs in the playlist changes from week to week to reflect the most popular songs on the charts. Alice asks "Alexa, play the top weekly songs playlist". Your skill responds with a ContentId of "321" which represents the "Top Weekly Songs" playlist. When Alexa sends this ContentId in an Initiate request, your skill returns the first track of the playlist, for example Shallow by Lady Gaga. One month later, Alice asks "Alexa, play the top weekly songs playlist". Your skill again responds with a ContentId of "321" because this ContentId always represents the "Top Weekly Songs" playlist. However, this time when Alexa sends this ContentId in an Initiate request, your skill returns, for example, the song Better Now by Post Malone, because the playlist contents change weekly.

When a user sets a music alarm (for example, "Alexa, wake me up to Can't Stop The Feeling by Justin Timberlake from skill name at 8 AM"), Alexa saves the ContentId returned in the GetPlayableContent response. Each time the alarm is triggered, which might be months later for a repeating alarm, Alexa sends an Initiate request to your skill with the saved ContentId, and the response should reflect the content the user requested when setting the alarm.

Similarly, when a user browses their history of music requests and selects an item to replay, Alexa calls Initiate with the saved ContentId. In the preceding example for "Top Weekly Songs", if the user sees "Top Weekly Songs" in their history and clicks to play it again, Alexa sends an Initiate request with a ContentId of "321". The resulting queue of songs might be different because the playlist changes weekly, but the user is still listening to the "Top Weekly Songs" playlist, so the result is correct.

Content object schema

Field Description Type Required
id An identifier for the content (e.g. album ID, playlist ID, track ID, etc.), that uniquely identifies the content in the skill's domain. String Yes
actions Whether the content is playable, browsable, or both. This field should only be present for content returned for display use cases. A ContentActions object. Yes
metadata Metadata for the content. A MediaMetadata object. Yes

Content object artist example

{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "ARTIST",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "macklemore"
      },
      "display": "Macklemore"
    },
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        }
      ]
    }
  }
}

Content object track example

{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "TRACK",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "remember high school"
      },
      "display": "Remember High School"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "macklemore"
          },
          "display": "Macklemore"
        }
      }
    ],
    "album": {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "the language of my world"
        },
        "display": "The Language of My World"
      }
    },
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48-000000-80-0-0.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        }
      ]
    }
  }
}

Content object album example

{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "ALBUM",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "the language of my world"
      },
      "display": "The Language of My World"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "macklemore"
          },
          "display": "Macklemore"
        }
      }
    ],
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        }
      ]
    }
  }
}

Directives

GetPlayableContent directive

Support the GetPlayableContent directive so that customers can request content.

The following example shows a customer utterance:

Alexa, play the song Poker Face by Lady Gaga.

GetPlayableContent directive payload details

Field Description Type
requestContext Context information about the request. A RequestContext object.
filters Filters to apply during content resolution. A Filter object.
selectionCriteria Attributes that you resolve to a content object by searching. A ResolvedSelectionCriteria object.

The entity types in the selectionCriteria property correspond to music catalogs associated with the skill as follows:

Entity Type Catalog Type
TRACK AMAZON.MusicRecording
ALBUM AMAZON.MusicAlbum
ARTIST AMAZON.MusicGroup
PLAYLIST AMAZON.MusicPlaylist
GENRE AMAZON.Genre
STATION AMAZON.BroadcastChannel

GetPlayableContent directive example

{
    "header": {
      "namespace": "Alexa.Media.Search",
      "name": "GetPlayableContent",
      "messageId": "<message id, a 25-character random alphanumeric string>",
      "payloadVersion": "1.0"
    },
    "payload": {
      "requestContext": {
        "user": {
          "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
          "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
        },
        "location": {
          "originatingLocale": "en-US",
          "countryCode": "US"
        }
      },
      "filters": {
        "explicitLanguageAllowed": true
      },
      "selectionCriteria": {
        "attributes": [
          {
            "type": "TRACK",
            "entityId": "138545995"
          },
          {
            "type": "MEDIA_TYPE",
            "value": "TRACK"
          }
        ]
      }
    }
}

GetPlayableContent response event

If you handle a GetPlayableContent directive successfully, respond with an Alexa.Response event.

Your skill code (AWS Lambda function) should generate and return a response in 0.5 seconds or less under moderate traffic (at least two transactions per second). Longer response times might result in your skill failing certification.

If your skill can successfully find playable content to satisfy the request, it should respond with GetPlayableContent.Response.

GetPlayableContent Response event payload details

Field Description Type Required
content The content to play, that satisfies the request. A content object. Yes

GetPlayableContent Response event example

The following example demonstrates a response that satisfies an example request from a user that said "Alexa, play the song Poker Face by Lady Gaga".

{
    "header": {
        "namespace": "Alexa.Media.Search",
        "name": "GetPlayableContent.Response",
        "messageId": "<message id, a 25-character random alphanumeric string>",
        "payloadVersion": "1.0"
    },
    "payload": {
      "content": {
        "id": "1021012f-12bb-4938-9723-067a4338b6d0",
        "metadata": {
          "type": "TRACK",
          "name": {
            "speech": {
              "type": "PLAIN_TEXT",
              "text": "poker face"
            },
            "display": "Poker Face"
          },
          "authors": [
            {
              "name": {
                "speech": {
                  "type": "PLAIN_TEXT",
                  "text": "lady gaga"
                },
                "display": "Lady Gaga"
              }
            }
          ],
          "art": {
            "sources": [
              {
                "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
                "size": "X_SMALL",
                "widthPixels": 48,
                "heightPixels": 48
              }
            ]
          }
        }
      }
    }
}

GetPlayableContent directive error handling

If your skill can't handle a GetPlayableContent directive successfully, it should respond with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For more information, see Alexa Music and Radio Skill API Error Responses.

If not, the skill should respond with a media-specific CONTENT_NOT_FOUND error response.