SOsonos
playbackSession

createSession

Use the createSession command in the playbackSession namespace to unconditionally create a new session and clobber any existing sessions.

Use appContext to determine how multiple instances of your app can share control of a session. For example, if you provide a user account identifier as appContext, then two instances of your app logged into the same user account would be able to control the same session on a group. If you choose to implement your app to always provide an appContext that is unique for all app instances, then only one app instance can control a session at any time.

Use customData to save information in the session that your app finds useful. For example, your app could store a playlist identifier in customData, so that another app instance could automatically load the right playlist when joining a session.

post/groups/{groupId}/playbackSession

Request

  • Base URL
    https://api.ws.sonos.com/control/api/v1
  • URL
    https://api.ws.sonos.com/control/api/v1/groups/{groupId}/playbackSession
  • Auth
    OAuth 2 and HTTP bearer and API key in header X-Sonos-Api-Key
    Authorization code: https://api.sonos.com/login/v3/oauth
    Token URL: https://api.sonos.com/login/v3/oauth/access scopes: playback-control-all

Request body

appIdstring required

Identifies your app. This should be a reverse DNS name of the form “com.companyname.appname” or similar. It is used together with appContext to determine if a session can be joined or not. As a best practice, user-identifiable data should be hashed or encoded so that it is only useful to your app.

The sum total length of appId and appContext must be less than 255 bytes. Otherwise, the player will return an error.

appContextstring required

Instance data for your app, an opaque string that you can use to identify a particular user account, for example. It is used together with appId to determine if a session can be joined or not. As a best practice, user-identifiable data should be hashed or encoded so that it is only useful to your app.

The sum total length of appId and appContext must be less than 255 bytes. Otherwise, the player will return an error.

accountIdstring nullable

(Optional) The music service account to use on Sonos for playback in the session. See the MusicObjectId for more details about this parameter. If your app submits an invalid accountId, you will receive an ERROR_INVALID_PARAMETER error. An accountId is invalid when it doesn’t match a stored account on the player.

customDatastring nullable

(Optional) A blob of text stored by the player and passed back to any other clients that successfully join an existing session. This data (up to 1023 bytes) is stored within the session. The player truncates blobs of text that are longer than 1023 bytes and returns the truncated string in the command response. The default value is an empty string (“”). As a best practice, user-identifiable data should be hashed or encoded so that it is only useful to your app.

Response

See the x-muse-error-codes extension for a list of muse errors that generate this response

sessionIdstring nullable

Identifies the session created or joined.

sessionState'SESSION_STATE_CONNECTED'

No description available

sessionCreatedboolean

Indicates whether your app joined a newly-created session or an existing session. If true, the player created a new session. If false, the player joined your app to an existing session.

customDatastring nullable

Up to 1023 bytes of additional data provided when the session was created. Text longer than 1023 bytes is truncated.

Changes

No recorded changes to this operation across all 1 revision of this API.