Speaker Notification Channel Help
Overview
Speaker is one of the channels in Notification Workflows that plays spoken announcements into a physical space using a dedicated device (M5Stack-based hardware). Use it for things like "play a cleanup reminder 5 minutes before the scheduled check-out" or "play a welcome message when presence is first detected in the room." Unlike LINE, Email, or SMS, it doesn't notify a person — it plays audio into the room or space itself.
Open it from the sidebar via "🔔 Notification Workflows" → the Channels tab → the Speaker card, which links to /notifications/channels/speaker. The page has 3 tabs.
| Tab | Content |
|---|---|
| Speaker | Register, edit, and delete the physical speaker devices installed at the facility |
| Announcements | Write scripts, generate audio, and test-broadcast them |
| Schedules | Per-plan automatic delivery rules, plus recent delivery history |
Only facility owners and organization owners can manage or edit (regular members can view only, or the page may be hidden).
Detailed features
Feature 1: Registering speaker devices
On the "Speaker" tab, register the physical devices installed at your facility.
| Field | Description |
|---|---|
| Device ID | Must exactly match the [SYS] Device ID shown in the M5 unit's serial log (letters, digits, and . _ - only, up to 128 characters) |
| Display name | The name shown in the UI (e.g., "1F Entrance") |
| Description (optional) | A note about where it's installed |
| Enabled | Turning this off temporarily stops delivery to this device (the record itself is kept) |
The device ID cannot be changed after creation — the edit screen shows it as read-only. To change it, delete the device and register it again with the correct ID.
Feature 2: Creating voice scripts (Announcements)
On the "Announcements" tab, pair the text you want spoken with a voice and pre-generate the audio.
- Choose a voice (from a voice catalog UnlockOS has already curated from ElevenLabs — you don't need your own ElevenLabs contract)
- Enter a title (up to 200 characters) and the script text (up to 5,000 characters)
- Click "Save" to save the script
- Click "Generate audio" to have ElevenLabs generate an MP3
Once generation finishes, a preview player appears so you can listen to it right there. Changing the text or voice shows a warning that regeneration is needed. If generation fails, the previous error is shown (see Troubleshooting).
Only scripts whose status is "ready" can be selected in schedules or test broadcasts below.
Test broadcast
From the Announcements list, you can pick one speaker and play a specific script immediately. This is independent of the automatic delivery tied to actual reservations — after sending, it waits up to 30 seconds for the device's response (played / skipped / failed, etc.) and shows the result. Test broadcasts are not billed.
Feature 3: Automatic delivery rules (Schedules)
On the "Schedules" tab, register rules for "which plan," "at what timing," "on which speaker(s)," and "which script" to play.
| Field | Description |
|---|---|
| Plan | The pricing plan this rule applies to |
| Anchor | The event playback is timed against (see table below) |
| Direction / offset | Before or after the anchor, by how many minutes (0–120; some anchors fix this) |
| Script | The audio to play (only scripts that are ready can be selected) |
| Speaker(s) | The device(s) to play on (multiple can be selected — one rule can play on several devices at once) |
| Enabled | Turning this off stops automatic delivery for this rule |
Available anchors
| Anchor | Fires | Offset |
|---|---|---|
| Reservation start time | N minutes before/after the reservation's start time | 0–120 min, direction selectable |
| Scheduled check-out time | N minutes before/after the reservation's scheduled end time | 0–120 min, direction selectable |
| Actual check-in time | N minutes before/after the moment check-in actually completed | 0–120 min, direction selectable |
| First presence detected (welcome) | Plays once, the first time presence is detected during the reservation window | Not configurable (fixed) |
| Overstay after end time | Plays N minutes after the scheduled check-out time, only if presence is still detected | 1–120 min after (direction fixed to "after") |
For the two presence-based anchors, whether playback actually happens is decided by the speaker device itself, not the server. The server only sends the command at the anchor time; if no one is present, the device skips playback rather than the server deciding not to send.
Feature 4: Delivery history and device responses
The bottom of the "Schedules" tab shows recent delivery history. Each row shows:
- Delivery time and status (played / skipped / failed / dispatched — awaiting response)
- The speaker, plan, script, and timing involved
- Command ID, device acknowledgment (ACK), presence state, and any error (if present)
Device acknowledgments are grouped as follows:
| Device response | Status shown | Meaning |
|---|---|---|
| Played | Played | Played back successfully |
| Absent/skipped, expired, or cancelled | Skipped | No one was present, the play window passed, or it was cancelled |
| Queue full, invalid command, or playback error | Failed | The device couldn't process it |
| (no response yet) | Dispatched — awaiting response | The command was sent but the device hasn't responded yet |
Separately from this history, the Notification Workflow History tab also shows Speaker deliveries, with cost information, under channel "Speaker."
Feature 5: Billing
The Speaker channel is metered at ¥3 per play. UnlockOS absorbs the actual ElevenLabs generation and MQTT delivery costs; customers are billed a flat per-play rate. Test broadcasts are not billed.
Troubleshooting
Audio doesn't play
- Check that the device's "Enabled" toggle is on (if off, commands are sent but nothing plays)
- Check that the script's generation status is "ready" (audio that hasn't generated, or failed to generate, can't be played)
- Check the error shown in the delivery history. Common ones:
| Error shown | Likely cause |
|---|---|
| Could not connect to the speaker | Check the device's power and network connection |
| Connection to the speaker was rejected | Check the device's registration (device ID) |
| Delivery to the speaker failed | Wait a bit and try again |
| Could not retrieve the audio file | Regenerate the script's audio |
| Could not retrieve the speaker's credentials | Ask support to check the device's provisioning |
| Delivery was cancelled because the play window had passed | Delivery delay; contact support if this happens often |
Audio generation fails
If there's an issue with the script text or voice selection, a generation error appears on the script's edit screen. Try shortening the text or removing unusual symbols, then click "Generate audio" again. If it's a temporary timeout, wait a bit and retry.
I want to change a speaker's voice
Create a new script on the "Announcements" tab (choosing a different voice and generating audio), then swap the script used in the relevant schedule rule.
FAQ
Q: Can one rule play on multiple speakers at the same time?
A: Yes. Selecting multiple speakers in a rule delivers to all of them at the same timing.
Q: My facility doesn't show a Speaker card or menu
A: Either the Notification Workflow feature flag or the Speaker feature flag may be disabled for your facility. Check with support.
Q: Are test broadcasts billed?
A: No. Only automatic delivery tied to actual reservations is billed.
Q: "First presence detected" didn't play
A: This anchor makes its final presence decision on the device itself. The device may not have detected presence (check sensor orientation and placement).
Q: I registered the wrong device ID
A: The device ID can't be changed on the edit screen. Delete the device and register it again with the correct ID.