Sonos - Serval Documentation

What you can automate

The Sonos integration controls speakers through the Sonos cloud Control API. It includes typed API requests and a Play Sonos Favorite workflow that groups selected rooms, loads a saved favorite, optionally sets each room’s volume, and starts playback. A phone or computer does not need to stay on while the workflow runs. Speakers must already be set up, registered to the authorizing Sonos account, connected to the internet, and compatible with cloud playback. You can connect a streaming service through Sonos; a separate Serval Spotify connection is not required.

Connect Sonos

Open the Sonos connection dialog in Serval

Go to Integrations, choose Connect new, and select Sonos. Copy the Redirect URI shown in the dialog.

Create a Control Integration in Sonos

Sign into the Sonos Developer Portal. Under Control Integrations, create an integration, or open your existing draft. Enter your application details and register the exact Redirect URI from Serval. Create and save a client credential key, then copy its Client ID and Client secret.This is a Control Integration for controlling existing speakers. An event callback is not needed for this connector because it does not subscribe to Sonos events. Sonos documents that cloud control integrations may be released when ready; the separate Works with Sonos certification program is optional. See Sonos’s release guidance.

Enter the app credentials in Serval

Enter a unique Connection name, such as “Office Sonos”, and your Client ID and Client secret. The connection name distinguishes accounts and should stay the same when you reconnect.

Authorize the account that owns the speakers

Select Connect Sonos and sign into the Sonos account that owns your office system. Approve access and return to Serval. Finish within ten minutes; otherwise start the connection again.Creating a new Sonos account does not transfer existing speakers to it. If you cannot see the office system, check which account registered it with your office administrator.

Serval stores the credentials and refreshes access automatically. If the client secret changes or consent is revoked, reconnect with the current credentials.

Sonos offers one scope, playback-control-all: read playback information, control music and volume, manage groups, and play favorites. It covers the account’s authorized systems. A floor name in Serval does not limit that permission; target specific household and player IDs in your workflows. See Sonos authorization.

Check the connection and select speakers

Run these read-only checks from the integration:

Check	What it tells you
Test Sonos Connection	Whether the API accepts the credentials and how many connected households it finds.
List Sonos Players	Room names, primary player IDs, and household IDs.
List Sonos Favorites	Playable favorite names, IDs, and household IDs.

None of these checks changes grouping, music, or volume. A successful credential check with zero households does not prove that your speakers are online. A household is a Sonos system on one network. Rooms in different households cannot be grouped together. Use the stable player IDs from discovery to select rooms. A room may represent bonded stereo or surround speakers; those devices follow the room’s primary player. Group IDs can change when anyone regroups speakers, so the playback workflow discovers and creates its group each run. To list the whole account, query every household. Selecting households[0] only searches one system and can omit rooms and favorites from other systems. Keep household and player IDs in the result so a playback workflow can target the intended rooms. If partial is true, retry after regrouping settles before treating the room list as complete.

Read rooms and favorites across all households

import { workflow } from "serval/core";
import * as sonos from "serval/integrations/sonos";

export const main = workflow({
  fn: async (_args: {}, ctx: sonos.context.SonosIntegration) => {
    const response = await sonos.apiRequest(
      { path: "/control/api/v1/households", method: "GET" },
      ctx,
    );
    const systems = [];

    for (const household of response.households ?? []) {
      const householdId = household.id;
      const groups = await sonos.apiRequest(
        {
          path: "/control/api/v1/households/{householdId}/groups",
          method: "GET",
          pathParams: { householdId },
        },
        ctx,
      );
      const favorites = await sonos.apiRequest(
        {
          path: "/control/api/v1/households/{householdId}/favorites",
          method: "GET",
          pathParams: { householdId },
        },
        ctx,
      );
      systems.push({
        householdId,
        partial: groups.partial ?? false,
        rooms: (groups.players ?? []).map((player) => ({
          playerId: player.id,
          name: player.name,
          capabilities: player.capabilities,
        })),
        favorites: favorites.items.map((item) => ({
          favoriteId: item.id,
          name: item.name,
        })),
      });
    }

    return { households: systems };
  },
});

Play a favorite when a deal closes

In the Sonos app, find Eye of the Tiger by Survivor through your connected music service. Save the playable track as a Sonos favorite and confirm that it plays on the office system. A saved radio station or multi-track playlist can continue playing beyond one song.
Run List Sonos Favorites and save the exact favorite ID. Favorites do not include non-playable pinned containers or Sonos playlists; use a playable music-service favorite.
Run List Sonos Players. Confirm which primary player IDs belong to the 25th floor and record their household ID. Select only those rooms.
Add Play Sonos Favorite to the existing Salesbricks deal-closed workflow and configure:

Input	Value
`householdId`	The discovered household containing the office rooms.
`playerIds`	The explicit list of 25th-floor primary player IDs.
`favoriteId`	The ID for the saved track.
`volume`	`100` for the maximum allowed level on every selected player, or a lower integer from `0` to `100`. Omit to keep each player’s current volume.

Keep the existing webhook authentication and check that the event means the deal transitioned to closed-won. Deduplicate repeated notifications by deal/event ID and serialize runs targeting these speakers so celebrations do not interrupt each other. The Sonos workflow itself does not deduplicate Salesbricks events.
The installable workflow requires installer approval by default. Configure your team’s approval policy for unattended deal-triggered runs, then perform a controlled playback test on the selected rooms.

Playing a favorite regroups the selected rooms, replaces their queue, and starts music. It does not restore prior music, grouping, or volume afterward. Volume 100 still respects each Sonos product’s configured Volume Limit. Fixed-volume outputs cannot accept a volume setting.

The workflow checks that the favorite exists and all selected players belong to the household before changing anything. It loads the favorite without starting playback, sets volume if requested, rechecks group membership, and starts playback. A failure stops later steps but does not undo completed steps. Other Sonos controllers can still change a group during a run.

API requests

Use Sonos API request for discovery, grouping, favorites, playback status and controls, play modes, and player or group volume/mute. Authentication is supplied by Serval; never include credentials in workflow inputs.

import * as sonos from "serval/integrations/sonos";

const systems = await sonos.apiRequest(
  { path: "/control/api/v1/households", method: "GET" },
  ctx,
);

await sonos.playFavorite(
  {
    householdId: "YOUR_HOUSEHOLD_ID",
    playerIds: ["YOUR_PRIMARY_PLAYER_ID"],
    favoriteId: "YOUR_FAVORITE_ID",
    volume: 30,
  },
  ctx,
);

Group volume is an average across rooms. Use the playback workflow’s volume input to set every selected room to the same level.

Troubleshooting

Redirect URI mismatch: copy the current URI from Serval and register it verbatim in the Sonos app. Deployment environments have different callbacks.
Expired authorization session: reopen Connect Sonos and finish within ten minutes.
No households or players: verify the owning Sonos account, speaker internet connectivity, and cloud compatibility. Merely seeing registered products on the account website does not establish online status.
Favorite unavailable: list favorites again; a removed and re-added favorite may have a new ID. Confirm the music service is signed into Sonos and the content is playable in that account and region.
Sonos is regrouping: discovery returned an incomplete list. Wait for the groups to settle, then retry the check.
Group changed: another controller may have regrouped rooms. The favorite may already have replaced the queue and requested volume changes may already have been applied. These changes are not undone. Check the rooms, queue, and volumes before retrying. Avoid concurrent workflows for the same speakers.
Fixed volume: omit volume or choose players with controllable outputs.
Authorization revoked or secret rotated: reconnect the same Serval connection with current app credentials and approve Sonos access again.
Refreshed credentials could not be saved: Serval retries saving the replacement credentials. If all retries fail, reconnect the connection before running the workflow again.

This connector does not add a streaming catalog search, audio hosting, Sonos event subscriptions, or automatic restoration of an interrupted queue. Music availability and service subscription requirements are controlled by Sonos and the connected music provider.

​What you can automate

​Connect Sonos

​Check the connection and select speakers

​Play a favorite when a deal closes

​API requests

​Troubleshooting

What you can automate

Connect Sonos

Check the connection and select speakers

Play a favorite when a deal closes

API requests

Troubleshooting