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

Example of a shared music object in messaging context Render music object shared from Spotify or from within an extension. Example of how open.spotify.com website would look open.spotify.com Previews

The preferred method is for the shared object to deeplink into the Spotify app based on our Content Linking Guide.
Example of a Search and Search extension in messaging thread Search and Share Extension

Allow users to easily search for and share Spotify music from within the messaging app.		 Example of Spotify @Mention bot in messaging thread @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.

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 Design Guidelines:

Music card requirements

Requirements for a music card: No advertising, album artwork cannot be manipulated in any way, song title and artist must be shown and there has to be a call to action to Spotify

Displaying user’s current and recently played songs

Example of search view with personalized content. Includes a search box,user's currently playing song and a list of recently played songs

Search results

Example of search view with search results. Note squared album cover, circle cropped artist image and custom playlist cover or a 2x2 playlist grid.

Linking content to Spotify

Clicking 'Play in Spotify' must bring users to open.spotify.com or deep-link into the app.

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.

Reference