Messaging
Introduction
Want to give your users a way to share music while they’re chatting with friends & family? This guide will show you how easy it is to make music-sharing and discovery a seamless part of your messaging experience.
Features
 |
Render music object shared from Spotify or from within an extension. |  |
open.spotify.com Previews The preferred method is for the shared object to deeplink into the Spotify app based on our Content Linking Guide. |
 |
Search and Share Extension Allow users to easily search for and share Spotify music from within the messaging app. |
 |
@Mention Bot This is an alternative to building a messaging extension. If your app supports bots that can be invoked by / or @ commands, you can make sharing music easy. |
How To
Render the shared music object
The music object can be shared into the messaging thread in three ways:
- The user shares from within the Spotify app using the share flow
- The user copy-pastes the track URL into the messaging thread
- The user shares the music using an extension or an @mention-bot from within the messaging app
When a song is shared from Spotify or the Song URL is copy-pasted into the messaging thread, the app should unfurl the link using metadata from the Web API.
Here’s an example open.spotify.com URL: https://open.spotify.com/track/55fmthmn3rgnk9Wyx7G5dU
To get the metadata for a Spotify entity, you need to use the correct Web API endpoint. Look at the following table for a quick reference on how the open.spotify.com links match to Web API endpoints. There are other entities that follow the same mapping logic.
| open.spotify.com link | Web API endpoint | Documentation |
|---|---|---|
| https://open.spotify.com/track/55fmthmn3rgnk9Wyx7G5dU | https://api.spotify.com/track/55fmthmn3rgnk9Wyx7G5dU | Get a Track |
| https://open.spotify.com/artist/2JFiletIm3BQ5bhx19Vusf | https://api.spotify.com/artist/2JFiletIm3BQ5bhx19Vusf | Get an Artist |
| https://open.spotify.com/album/3KTmPBBCNumrdtPvInavde | https://api.spotify.com/album/3KTmPBBCNumrdtPvInavde | Get an Album |
| https://open.spotify.com/user/spotify/playlist/37i9dQZF1DXb1Pd8XAlALS | https://api.spotify.com/users/spotify/playlist/37i9dQZF1DXb1Pd8XAlALS | Get a Playlist |
When the track is shared into the thread from an extension or using an @mention-bot, the preferred way to get the track metadata is through the Web API call. The metadata is available in the search response or you can get it from the track endpoint.
Refer to the design section below to get a better idea of how this music object should be rendered.
Inline Previews in the shareable music object
The preview_url field in the Get a Track Endpoint response will have the link to the 30s preview of the selected track. This field is also returned as part of the Search response for tracks. Your app needs to be whitelisted by Spotify to get a 30s preview URL in the Web API response. Otherwise, preview_url will be null.
Note: Please make sure you adhere to our strict branding guidelines when rendering the music object.
Linking content to Spotify
Refer to our Content Linking Guide.
Build a Search Extension for Spotify
Search for music using Spotify Public API. The search endpoint will return songs, albums, artists and playlists.
Before the user has entered a search term, the “empty-state” results can be populated by the Spotify Featured Playlists endpoint. This endpoint returns playlists that change based on locale, day of week and time of day. For example, in the US, it would return “Throwback Thursdays” as one of the playlists on Thursday nights.
If possible, we highly recommend allowing the user to authenticate (documented for Android and iOS) and then showing their “now playing” and “recently played” tracks. Data from past messaging integrations has shown that users share these very often.
Browse
The browse endpoints can help you map categories (like featured, genre, and activities). You can then request playlists for each category to build out the browse tree.
Connecting accounts (optional)
To be able to play full songs or share recently played tracks, users need to authenticate their account and grant access to their data. To authenticate the user, you will need to integrate the Spotify auth SDK into your app. This is documented here for Android and here for iOS.
Design
All integrations using Spotify content must adhere to our Branding Guidelines:
Music card requirements
Displaying user’s current and recently played songs
Search results
Linking content to Spotify
Other Requirements
Spotify prohibits recording and sharing of audio and video. Do not synchronize playback of audio with any sort of visual or video content.