The official Zapier integration for Castbreeze, enabling you to control your speakers through automated workflows. Stream audio files, play notifications, and integrate your speaker system with thousands of apps via Zapier.
Currently Supported Speakers: Sonos (support for additional speaker brands coming soon)
Play audio clips (music, podcasts, notifications) on Sonos without interrupting current playback. Perfect for one-time audio clips that stop automatically.
- Use Cases: Doorbell notifications, TTS announcements, alert sounds
- Clip Types:
- Custom Audio: Upload your own MP3/WAV files
- Built-in Chime: Use Sonos' built-in chime sound
- Options:
- Select specific Sonos player
- Set volume (0-100)
- Priority levels (LOW/HIGH) for managing overlapping clips
Start continuous streaming of an audio file that plays indefinitely until stopped.
- Use Cases: Background music, radio streams, continuous audio playback
- Features:
- Stream to one or multiple speaker groups
- Supports MP3, M4A, WAV, FLAC, and other common formats
- Optional volume control
- Play on all groups or select specific ones
The integration includes hidden triggers used for dynamic dropdowns:
- Sonos Players: Dynamically populate available Sonos players
- Speaker Groups: Dynamically populate available speaker groups
- Supported Speakers: Currently requires Sonos speakers connected to your network (support for additional brands coming soon)
- Castbreeze Account: Sign up at castbreeze.com
- Zapier Account: Free or paid Zapier account
- Visit the Castbreeze Zapier Integration page
- Click "Use this Zap" or create a new Zap
- Search for "Castbreeze" when adding an action
- Connect your Castbreeze account via OAuth
- Configure your desired action
# Install dependencies
pnpm install
# Build the integration
pnpm run build
# Validate the integration
pnpm run validate
# Run tests
pnpm run test# Watch mode for development
pnpm run watch
# Clean build artifacts
pnpm run clean
# Push to Zapier (requires authentication)
pnpm run pushThe integration uses OAuth 2.1 with PKCE for secure authentication:
- Authorization URL:
https://api.castbreeze.com/oauth/authorize - Token URL:
https://api.castbreeze.com/oauth/token - Client ID:
zapier-client-1 - Scope:
playback-control-all
- Access tokens are automatically refreshed when expired
- Refresh tokens are preserved across token refreshes
- The integration handles 401 errors and triggers automatic token refresh
The integration communicates with the Castbreeze API:
- Base URL:
https://api.castbreeze.com - API Version: v2
- Key Endpoints:
/oauth/authorize- OAuth authorization/oauth/token- Token exchange and refresh/api/v2/whoami- Authentication test/api/v2/sonos/households- List households/api/v2/sonos/groups- List speaker groups/api/v2/sonos/players/{playerId}/audioClip- Play audio clip/api/v2/sonos/play-url- Stream audio URL
zapier-integration/
├── src/
│ ├── index.ts # Main integration entry point
│ ├── authentication.ts # OAuth 2.1 configuration
│ ├── types.ts # TypeScript type definitions
│ ├── creates/ # Zapier actions
│ │ ├── sonosPlayAudioClip.ts
│ │ └── sonosStreamFile.ts
│ ├── triggers/ # Dynamic dropdown triggers
│ │ ├── sonosGroups.ts
│ │ └── sonosPlayers.ts
│ └── common/ # Shared utilities
│ ├── sonosData.ts
│ └── sonosPlayback.ts
├── package.json
├── tsconfig.json
└── .zapierapprc # Zapier CLI configuration
CASTBREEZE_API_URL- Override the default API URL (default:https://api.castbreeze.com)
The integration is configured in src/index.ts:
- Platform Version: Uses latest Zapier platform core
- Auto Refresh: Enabled for automatic token refresh
- PKCE: Enabled for enhanced security
- Request Middleware: Adds Authorization headers automatically
- Response Middleware: Handles errors and token refresh
Trigger: Ring Doorbell pressed
Action: Castbreeze - Play Audio
Configuration:
- Player: Front Room Speaker
- Clip Type: Custom Audio
- File: doorbell-chime.mp3
- Priority: HIGH
Trigger: Schedule (Every day at 7 AM)
Action: Castbreeze - Stream File/URL
Configuration:
- Speaker Groups: Kitchen, Bedroom
- File: news-briefing.mp3
- Volume: 40
Trigger: Smart Home - Motion detected
Action: Castbreeze - Play Audio
Configuration:
- Player: All Players
- Clip Type: CHIME
- Priority: LOW
The integration includes comprehensive error handling:
- 401 Unauthorized: Automatically triggers token refresh
- 403 Forbidden: Returns permission error
- 4xx/5xx Errors: Extracts and returns detailed error messages
- Token Expiration: Automatic refresh with retry logic
The integration includes test utilities:
# Run all tests
pnpm run test
# Test authentication
zapier test --auth
# Test specific action
zapier test --action=sonosPlayAudioClipUpdate version in package.json:
{
"version": "1.0.17"
}# Build and validate
pnpm run build
pnpm run validate
# Push to Zapier
pnpm run push
# Promote to production (via Zapier dashboard)
zapier promote 1.0.17- Documentation: castbreeze.com/docs
- Issues: Report bugs via GitHub issues
- Email: support@castbreeze.com
The integration is written in TypeScript with strict type checking:
- Node.js >= 24.0.0
- TypeScript 5.7+
- ES Modules (type: "module")
zapier-platform-core: ^18.0.1 - Zapier platform SDK@types/node: ^22.10.1 - Node.js type definitionsjest: ^29.7.0 - Testing framework
Currently Supported:
- ✅ Sonos (all models with API support)
Coming Soon:
- 🔜 Additional speaker brands and systems
We're actively working on expanding support to more speaker systems. Check back for updates or contact us if you'd like to request support for a specific brand.
Play Audio (audioClip):
- MP3
- WAV
Stream File/URL:
- MP3
- M4A
- WAV
- FLAC
- Other common audio formats supported by Sonos
MIT License - see LICENSE file for details
Copyright (c) 2025 Sem Postma spostma@castbreeze.com
Sem Postma
- Email: spostma@castbreeze.com
- Website: castbreeze.com
Part of the Castbreeze ecosystem:
- Zapier Integration: Castbreeze for Zapier
- API: Castbreeze API
- Chrome Extension: Cast to Sonos - Chrome Web Store