The groups namespace enables your app or hardware integration to retrieve information about how players are grouped in a household and to create or modify groups.
When creating or modifying groups, the group info response only includes the list of players in the final group. It doesn’t include a flag to show whether the changes match the original desired group or not. This could lead to partial successes.
Additionally, this command may trigger significant player-to-player communication over the LAN. In some cases, you may not receive a response.
As a best practice, check the final set of players returned by the command, either in the group info response, or by getting a list of players in the group.
The tables below list the commands and events available in the groups namespace.
Commands
| Command | Description |
|---|---|
createGroup |
Create a new group from a list of players. Return the group ID of the group. |
getGroups |
Get information about groups and players in a household. |
modifyGroupMembers |
Add players to and remove players from a group. |
setGroupMembers |
Replace the players in an existing group with a new set. |
subscribe |
Subscribe to events in the groups namespace. |
unsubscribe |
Unsubscribe from events in the groups namespace. |
Object
| Object | Description |
|---|---|
groups |
Describes the current set of logical players and groups in the household. |
Errors
If your app sends invalid player IDs in the createGroup or setGroupMembers commands, or the modifyGroupMembers command to add players to the group, it sends an ERROR_INVALID_PARAMETER error with the list of invalid player IDs.
If your app sends invalid player IDs in the modifyGroupMembers command to remove players from the group, the player does not respond with an error because Sonos ignores any player IDs that are not already in the group.