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.

Request Parameters

This command requires a householdId and a groupId in the header to determine its targeted recipient. See the Control documentation for descriptions of parameters in the header.

See the table below for descriptions of parameters in the body.

Parameter Type Value
accountId string (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.
appContext string 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.
appId string 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.
customData string (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

Upon completion, returns a sessionStatus object type.

In the event of a failure, returns a sessionError or a globalError.

For example, if an app was connected to the old session, the group sends ERROR_SESSION_EVICTED. See sessionError for details.

Example

Request

Response