Link Search Menu Expand Document

Sonos communication

To communicate with your Sonos speakers on your local network use:

  • SOAP to call the SONOS services at port 1400 and subscribe to events see services
  • HTTP requests at port 1400 to scrape the UPnP service information or get a simple device status information see http requests
  • UDP Datagram and Simple Service Discovery Protocol (SSDP) at port 1900 to discover SONOS player see auto discovery
  • New secure RestURL at https://{ip}:1443/api (not covered in this documentation)

Sonos Services

Each sonos speaker has several soap services defined. All which have several actions that can be executed. The documentation of these services is scraped from the discovery file that every sonos speaker has available at http://{ip}:1400/xml/device_description.xml.

Sonos SOAP remarks

  • Sonos communicates booleans as 1 for true and 0 for false. This is something to keep in mind if you see boolean somewhere.
  • Some actions (like ListAlarms) return encoded xml as string. Before you can read these, youโ€™ll have to decode them and then parse them as XML. Libraries like node-sonos-ts provide a way that already parses the the output so you donโ€™t have to.

SOAP call

A SOAP call is just a http request, with some special headers and some xml formatted body. Each request is a POST request to some endpoint.

In this sample we described the SetMute command.

What Sample
IP of speaker
Control endpoint /MediaRenderer/RenderingControl/Control
Service type urn:schemas-upnp-org:service:RenderingControl:1

You can find this information on the page describing one of many sonos services.

SOAP call Rendering control - SetMute

You do a HTTP POST request to the control endpoint of the RenderingControlService. This service has a service type of urn:schemas-upnp-org:service:RenderingControl:1 which is needed in the soapaction http header and in the soap body. Where you also specify the name of the action SetMute in this case.


Required HTTP headers:

soapaction: "urn:schemas-upnp-org:service:RenderingControl:1#SetMute"
Content-Type: text/xml; charset="utf-8"

The body of the request has to be specified as XML. We also added the correct action body for the SetMute action. As you see below, booleans are converted to 1 for true and 0 for false. This is just how Sonos works.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="" s:encodingStyle="">
    <u:SetMute xmlns:u="urn:schemas-upnp-org:service:RenderingControl:1">

SOAP response

All calls to sonos will return a xml object. Either with a success message of with a failure.

Success message (without output parameters) to above command:

<s:Envelope xmlns:s="" s:encodingStyle="">
    <u:SetMuteResponse xmlns:u="urn:schemas-upnp-org:service:RenderingControl:1"></u:SetMuteResponse>

Generic error (when deleting an alarm that doesnโ€™t exists) body (HTTP status code 500):

<s:Envelope xmlns:s="" s:encodingStyle="">
        <UPnPError xmlns="urn:schemas-upnp-org:control-1-0">

Sometimes youโ€™re getting a more specific error code, we tried describing all of them in the documentation.json

HTTP Endpoints

Apart from the soap services, sonos also has some http endpoints available where you can get extra information:

URL Description
http://{ip}:1400/status/info playerId, serialNumber, groupId, householdId, capabilities, versions and more (JSON format)
http://{ip}:1400/status several additional connection information
http://{ip}:1400/status/batterystatus battery status for devices with battery (JSON format)
http://{ip}:1400/region.htm to select a Wifi region out of USA/Canada, EU, CHINA, JAPAN, ISRAEL, RUSSIA, SOUTH KOREA
http://{ip}:1400/support/review a list of all players with playerID and links to more information
http://{ip}:1400/xml/device_description.xml Sonos services description, used by the generator

Auto discovery

Each sonos speaker can be discovered by the SSDP or Simple Service Discovery Protocol. In short each speaker listens for a ssdp:discovery command.

Which is actually just a simple UDP packet send to port 1900 on multicast address and with the following body:

MAN: ssdp:discover
MX: 1
ST: urn:schemas-upnp-org:device:ZonePlayer:1

By sending a this UDP multicast packet, you will get a response from all speakers available on your network. See sonos-device-discovery.ts for a sample on how to do that in TypeScript/Node. That should give you some pointers on how to do that in another language.