playbackSession > joinOrCreateSession

Use the joinOrCreateSession command in the playbackSession namespace to join an existing session in the group, if the appId and appContext match the existing session’s. If there is no current session and no other source is playing, joinOrCreateSession creates a new session and joins it.

While this same behavior can be achieved by first calling joinSession and then conditionally calling createSession, using joinOrCreateSession guarantees that another app cannot create a session in between the two commands.

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.

Endpoint

POST

Request Parameters

This command requires a groupId to determine the target of the command. See the Control documentation for details.

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 “”. 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 the parameters do not match or if there is another source playing, the player returns ERROR_SESSION_JOIN_FAILED, similar to the joinSession command. See sessionError for details.

Example

Request

Responses

If there is no current session and no other source is playing, the player creates a new session. Here is the response:

If your appId and appContext match an existing session, the player joins your app to the session. This allows multiple apps to connect to the same session. Here is the response: