createSession

post

{protocol}://api.ws.sonos.com/control/api/{version}/groups/{groupId}/playbackSession

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.

Path Params

groupId

string

required

Target groupId

Body Params

appId

string

required

length ≤ 127

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.

appContext

string

required

length ≤ 127

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.

accountId

string | null

(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.

customData

string | null

(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.

Headers

X-Sonos-Api-Key

uuid

deprecated

Client API Key for the integration. Required in V1 but deprecated in V2.

X-Sonos-Corr-Id

uuid

Correlation UUID for data tracking purposes

Responses

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

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

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

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

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

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

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

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