groups

createGroup

Use the createGroup command in the groups namespace to create a new group from a list of players. The player returns a group object with the group ID. This may be an existing group ID if an existing group is a subset of the new group. In this case, Sonos may build the new group by adding new players to the existing group.

The group coordinator is chosen as follows. Sonos looks for existing groups whose members are all among the requested players (playerIds plus the players in areaIds), counting an ungrouped player as a group of one. It builds on the largest such group and keeps its coordinator, preferring the group that contains the first player in playerIds when sizes are equal. If there is no such group, the first player in playerIds becomes the coordinator.

post/households/{householdId}/groups/createGroup

Request

  • Base URL
    https://api.ws.sonos.com/control/api/v1
  • URL
    https://api.ws.sonos.com/control/api/v1/households/{householdId}/groups/createGroup
  • 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

playerIdsstring[] required

An array of player ID strings to group.

musicContextGroupIdstring nullable

(Optional) The group containing the audio that you want to use. If empty or not provided, the new group will not contain any audio.

areaIdsstring[] nullable

(Optional) List of source areaIds in the group. Emitted in groupInfo events. As of version 1.19.1, this can include the "Everywhere" area ID. If it does, this indicates that the group includes all visible players.

Response

Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future.

Muse v2 sends playerSetError which includes playerIds array since version 1.17.0

Changes

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