Discover
After the user authorizes your integration to connect with their Sonos account, you should get the list of households available in the account, get a list of groups and players that you can control, and check the firmware of the players to be sure that they have the minimum firmware version to handle the API calls that you're using. Use the getHouseholds command to get a list of households associated with the user's account. Use getGroups to find groups in the household. Check the firmware version supported by the players listed in the group.
Sending requests
Send requests to our API gateway at: api.ws.sonos.com/control/api
See Control for details about the full path.
Sonos object model
The diagram below shows the relationships between the Sonos objects that your integration can query or control. A Sonos account can include one or many households. A household can include one or many groups, and a group can include one or many players. Content partners can send content using playback sessions, which any integration can control using the Control API.
Get household
First, authorize your integration to access a user account (see Authorize for details). Then send a get household request to get a list of households associated with that user account. Users may have multiple households, for example, one at their home and one at their vacation home. If they do, you should offer an interface to choose households.
If a user has one household...
If a user has one household, you don't need to show them a list of households. Most users will have one household, so if you only get one household back, you don't need to offer an interface for users to choose households.
Here's an example of how to get households:
GET /control/api/v1/households HTTP/1.1
Content-Type: application/json
Authorization: Bearer <Access-Token>
Host: api.ws.sonos.com
Here's an example response for an account with one household:
{
"households": [
{
"id": "Sonos_HHID-4321"
}
]
}
And here's an example of what you might get back from the Sonos cloud for a user with more than one household:
{
"households": [
{
"id": "Sonos_HHID-4321"
},
{
"id": "Sonos_HHID-1234"
}
]
}
If a user has more than one household...
If a user has more than one household, determine the household that the user wants to control.
You should offer a way for the user to choose which household to control. Note that you can't group across households, so once the user chooses a household, you should only show players in that household.
We currently don't have a way to display the name of the household. Since users may not readily know their household ID, we recommend that you show a few room names for each household. For example:
Get players and groups
Once you connect to a household, get the players and groups on that household.
Groups are not physical devices, but abstract entities that are created and destroyed by users. All Sonos players are members of groups, even if there is only one player in the group. For example, a standalone player is a group of size 1.
Here's a sample request:
GET /control/api/v1/households/[Sonos_HHID]/groups HTTP/1.1
Content-Type: application/json
Authorization: Bearer <Access-Token>
Host: api.ws.sonos.com
Here's a sample response with added comments to show the player IDs. See the groups object for details.
{
"groups": [
{
"id": "RINCON_7BHBFF96BF5A34300", // PlayroomPlayerIdGroupId
"name": "Playroom",
"coordinatorId": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
]
},
{
"id": "RINCON_A8E9677G21B091499", // MasterBRPlayerIdGroupId
"name": "Master Bedroom + 1",
"coordinatorId": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"RINCON_B8E9377C21G061890" // BackPorchPlayerId
]
},
{
"id": "RINCON_Z4H7803J17K741322", // FamilyRoomPlayerIdGroupId
"name": "Family Room + 2",
"coordinatorId": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_A4E9395C21G061898", // KitchenPlayerId
"RINCON_C4T1256L09Q293216", // SunRoomPlayerId
"RINCON_D7Y5432M12H127890" // FamilyRoomPlayerId
]
},
],
"players": [
{
"id": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
"name": "Playroom",
"icon": "playroom",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"name": "Master Bedroom",
"icon": "masterbedroom",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_Y6C3211GJ59H88131" // MasterBRPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD",
"AIRPLAY"
]
},
{
"id": "RINCON_B8E9377C21G061890", // BackPorchPlayerId
"name": "Back Porch",
"icon": "livingroom",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_B8E9377C21G061890" // BackPorchPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_A4E9395C21G061898", // KitchenPlayerId
"name": "Kitchen",
"icon": "kitchen",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_A4E9395C21G061898", // KitchenPlayerId
"RINCON_B5R0432H68L104369" // KitchenRightPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_C4T1256L09Q293216", // SunRoomPlayerId
"name": "Sun Room",
"icon": "kitchen",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_C4T1256L09Q293216" // SunRoomPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"name": "Family Room",
"icon": "familyroom",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"RINCON_E6O0329J63L098571" // FamilyRoomSubPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD",
"AIRPLAY",
"HT_PLAYBACK",
"HT_POWER_STATE"
]
}
]
}
Check API version
Check the minimum API version supported by each player (the minApiVersion). If the minApiVersion is lower than the version you use in your integration, you may want to instruct the user to upgrade. If you have a mechanism to support lower API versions, you can use this as well. But be sure to inform the user about any limitations due to out-of-date player software so that they can upgrade to use the latest features. See How to update your Sonos system for more information about how users can update the software on their players.
Updated 5 days ago