Sonos Cloud API - Better alerts & TTS

The 0.1.0 release adds support for stereo pair & home theater configurations with the new play_on_bonded parameter. Previously playback was limited to the “primary” speaker (left speaker in a pair, soundbar/amp in a HT setup).

This is accomplished by calling the API multiple times simultaneously and unfortunately does not guarantee synchronized playback (but it’s usually pretty close). Because of this, it’s not enabled by default.

Great addon, Thx! I tried it out my Arc calling the service from the developer tools using inbuilt the CHIME when nothing else was playing and it worked great. However, afterwards the Arc couldnt play sound from the TV, it didnt recognize the source at all, although the TV did recognize the Arc. I ended up having to factory reset.

Is this something you have seen before?


Sorry, I haven’t heard that reported before. Hopefully it was an unrelated fluke.

I try to install this integration from HACS. But it is not showing up in HACS under integrations. When I try to add the repository via HACS, I get an error that it already exists in the HACS store.

What am I doing wrong?

Update: it seems that it is not visible in my country (NL), when I change country filter to US, I do see it in the store. After installing it also works in my country. It is not clear to me why there is a country restriction on it.

Has anyone come up with an approach to this issue?

I haven’t posted an update in a while, but there have been a few new features added recently:

Added in 0.1.2:

  • Default volume support: This is handled by enabling the volume slider on the media_player entities. If set, all clips that that are played without an explicit volume parameter will use this slider volume. If set to 0 (the default) the clip will be played at the speaker’s actual current volume. Note: this slider only affects clip playback from this custom integration.

Added in 0.2.0:

  • Only supported on HA 2022.3.0 or newer (including the current beta!)
  • Media Browser support: This allows browsing local media and the new TTS interface. Can be opened using either the “Media” tab on the left, or by hitting the media browser icon in the bottom-right of a media control card.
  • Media Source support: This is a somewhat more advanced feature, but it allows you to provide special media_content_id URLs in scripts/automations to play local files or TTS messages. This will finally allow per-clip volume control of TTS messages!
  • Play Button support: This is mostly a workaround to ensure the Media Browser button is drawn correctly. Pressing the Play button will simply replay the previous clip. This may be removed in a future release. This was removed in 0.2.1.

Example of TTS volume control:

service: media_player.play_media
  media_content_id: media-source://tts/cloud?message=Hello there friend
  media_content_type: music
    volume: 35
1 Like

Thank you so much for the updates, loving the ability to set volume through the slider!

1 Like

Hi @jjlawren,

Just wanted to say thankyou for the brilliant work!

Today I’ve been playing with a few different integration types for Sonos and found they were too clunky for my needs. The ability to call a single action that: a) lowers the volume of current playing, b) plays a sound at a specific volume over the top, c) seamlessly return to increase original playing volume makes this a standout integration.

Its early days but it seems reliable so far. I havent tried text to speech yet but I’m already happy to have a usable doorbell sound. Best of luck with getting required changes to HA in order to integrate this better.

Thanks, Elton.


I am getting a weird error message when trying to use the plugin. Ideas would be appreciated!

When executing this:

service: media_player.play_media
  media_content_id: CHIME
  media_content_type: music

I get an error message:
Failed to call service media_player.play_media. Unknown error

Logs show:

Logger: homeassistant.helpers.script.websocket_api_script
Source: components/media_player/
First occurred: 9:34:51 PM (7 occurrences)
Last logged: 9:44:27 PM

websocket_api script: Error executing script. Unexpected error for call_service at pos 1: URL is relative, but does not start with a /
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/helpers/", line 447, in _async_step
    await getattr(self, handler)()
  File "/usr/src/homeassistant/homeassistant/helpers/", line 680, in _async_call_service_step
    await service_task
  File "/usr/src/homeassistant/homeassistant/", line 1704, in async_call
  File "/usr/src/homeassistant/homeassistant/", line 1741, in _execute_service
    await cast(Callable[[ServiceCall], Awaitable[None]],
  File "/usr/src/homeassistant/homeassistant/helpers/", line 204, in handle_service
    await service.entity_service_call(
  File "/usr/src/homeassistant/homeassistant/helpers/", line 680, in entity_service_call
    future.result()  # pop exception if have
  File "/usr/src/homeassistant/homeassistant/helpers/", line 964, in async_request_call
    await coro
  File "/usr/src/homeassistant/homeassistant/helpers/", line 717, in _handle_entity_call
    await result
  File "/usr/src/homeassistant/homeassistant/components/media_player/", line 768, in async_play_media
    await self.hass.async_add_executor_job(
  File "/usr/local/lib/python3.9/concurrent/futures/", line 58, in run
    result = self.fn(*self.args, **self.kwargs)
  File "/usr/src/homeassistant/homeassistant/components/sonos/", line 67, in wrapper
    result = funct(self, *args, **kwargs)
  File "/usr/src/homeassistant/homeassistant/components/sonos/", line 616, in play_media
    media_id = async_process_play_media_url(self.hass, media_id)
  File "/usr/src/homeassistant/homeassistant/components/media_player/", line 46, in async_process_play_media_url
    raise ValueError("URL is relative, but does not start with a /")
ValueError: URL is relative, but does not start with a /

It looks like you’re using the built-in sonos integration. The sonos_cloud integration creates separate entities (for now).

I also think the format is incorrect, at least I have it different :slight_smile:

service: media_player.play_media
  media_content_id: CHIME
  media_content_type: music
  entity_id: media_player.livingroom_sonos_tts

Either format is valid. The entity_id needs to be updated.

wow. I feel dumb now. THANK YOU. I somehow cross named them. ( Was aware they are different, and named them differently intentionally - but somehow mixed up my naming convention :frowning: )

1 Like

For anyone using the great Google Cloud TTS with this, this is how it works, even for selecting language, voices, …:

service: media_player.play_media
entity_id: media_player.yourplayer
media_content_id: >-
media_content_type: music
volume: 30
play_on_bonded: true or false

Replace de-DE-Wavenet-B with your Google voice of choice.

You can say the content of an entity with this:
states.sensor.yoursensorhere.state }}’

1 Like

Since upgrading to HA 2022.6 and Sonos Cloud 0.3.0, I’ve had a few times when the integration suddenly stops working with error message “invalid access token”.

The first time it happened, I noticed log message “…Application Credentials have been imported and can be removed from configuration.yaml” - so I removed them. This didnt fix the issue so I deleted the integration (and restarted HA just in case). When I added the integration again, I wasnt prompted to enter a client ID or key (even after deleting from configuration.yaml and deleting the integration). But it remember them and the problem was fixed.

Today it failed again, after working fine for about 2 weeks.

2022-08-04 17:54:59.500 ERROR (MainThread) [custom_components.sonos_cloud] Household request failed (401): {"fault":{"faultstring":"Invalid Access Token","detail":{"errorcode":"keymanagement.service.invalid_access_token"}}}

This time I deleted the integration, then created new credentials in Sonos Dev account (even though the old ones hadn’t changed). When adding the integration again, it STILL didn’t ask for client credentials so I was forced to enter the new client ID and key in configuration.yaml. Now its working again.

  • Has anyone else had this problem after upgrading from configuration.yaml version?
  • Where are the client ID and key stored now and is there any way to delete them?


I’ve had that a few times now as well, no particular pattern identified. On each occasion I have removed the Integration, rebooted and then re-added it. This has always prompted to re-authentication which I have done with the original details. Interesting I’m being prompted to re-authenticate and your not…

One difference is I have the client credentials commented out in my configuration.yaml

It’s definitely not obvious, but they’re on the Integrations page hidden behind the top-right “…” button as “Application Credentials”:

This will hold the credentials imported from configuration.yaml or ones you add during the new onboarding flow.

I haven’t hit these 401 errors myself and I’m wondering if they’re transient. If you leave the credentials as-is and wait some time, does login with the same credentials later succeed?

1 Like

I have this issue too, starting with the same upgrade to Sonos Cloud 0.3.0.

It does not start working again if I wait, at least after 24 hours.

Edit: I created a fresh Sonos Developer API key and deleted/reinstalled the integration. We’ll see how long it lasts…

Thanks @jjlawren. I wasn’t aware HA stored OAuth credentials there. Makes perfect sense now.

To answer your question, both times when it stopped working I left it for about 24 hours and it continued to fail. So it doesnt appear to be transient and has been 100% reliable for many days leading up to those moments.

The first time I used the same OAuth credentials to get it working again, so I’m not sure where the 401 is coming from. Maybe HA itself? Let me know if you want me to enable verbose logging or check anything if it happens again. Happy to help because this is the best Sonos integration by far.

Interesting. To clarify, after re-adding I was not prompted for the Sonos Dev Application credentials, but I was prompted for my main Sonos Account credentials. Next time I can try deleting the OAuth credentials from the Application Credentials page. Then I’ll see how long it lasts if the credentials aren’t imported from config.yaml.