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. This page only handles registering speaker devices. Writing the script, generating audio, and test-broadcasting are done on the Messages tab (Notification Workflow); when it plays is set on the Workflows tab.
| Setting | Where |
|---|---|
| When it plays (timing) | The Workflows tab of the Notification Workflow page |
| What it plays (script, audio generation, test broadcast) | The Messages tab of the Notification Workflow page |
| Which device it plays on (device registration) | This page (/notifications/channels/speaker) |
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
At /notifications/channels/speaker, 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.
Assigning a room
Automatic delivery plays on the speaker in the room assigned to that reservation. A speaker with no room cannot be selected in a delivery rule (it can still be used for test broadcasts).
Assign rooms under Settings → Rooms → the "Speaker Assignment" tab (/settings?tab=rooms). It lists your rooms so you can pick which speaker sits in each one — the same layout as lock assignment.
- One speaker per room. Picking a speaker that is already in another room moves it there
- A speaker in use by a delivery rule cannot be removed from its room or deleted. Deselect it in the rule first
Feature 2: Writing and generating the voice script
Writing the script, generating audio, previewing it, and test-broadcasting it are all done on the Messages tab of Notification Workflow. The steps:
- On the Workflows tab, link the target device to a workflow whose channel is "Speaker" (create a new one if needed)
- On the Messages tab, open the message linked to that workflow (create one and link it if it doesn't exist yet)
- Enter the text you want spoken in the "Voice script" field
- If the workflow is on the speaker channel, an audio-generation block appears below the script field. Choose a voice there (from a voice catalog UnlockOS has already curated from ElevenLabs — you don't need your own ElevenLabs contract)
- 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 error is shown (see Troubleshooting).
The first time you generate audio, the result is automatically linked back to that workflow — there's no separate screen where you pick an ID.
The voice script can't contain variables like
{{guest_name}}. The audio is pre-generated from the script text, and at playback time it is never expanded — it would be read out literally — so scripts containing a placeholder can't be generated. Use fixed wording only.
Test broadcast
The "Test broadcast" button in the audio-generation block plays the generated audio on the workflow's linked device 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: Setting when it plays
"At what timing" playback happens is configured on the Workflows tab of Notification Workflow, using the same anchor event + offset mechanism as the other channels (LINE, Email, SMS) — timed against the reservation's start/end or the actual check-in/check-out moment. See the Notification Workflow help for anchor details.
Selecting speakers means choosing which rooms the rule covers
The selected devices do not all play. For each reservation, only the speaker in that reservation's own room plays. With 101, 102 and 103 selected, a check-in for room 102 plays on 102 only.
- Select the speakers for every room the rule should cover — you do not need a separate rule per room
- Deselect rooms you do not want covered, such as staff rooms
- When you add a new room, add its speaker to the rules that should cover it (this does not happen automatically)
Checking delivery results
Delivery history (played / skipped / failed, etc.) is available on the Notification Workflow History tab, listed under channel "Speaker" with cost information.
Reservations that were not delivered to at all are recorded as not covered (not an error, and not billed). Each row shows the reason:
| Shown | Meaning | What to do |
|---|---|---|
| Not covered | That reservation's room is not among the rooms this rule selected | Nothing, if that is intended. Otherwise add that room's speaker to the rule |
| Room not assigned | The reservation reached its delivery time with no room assigned | Assign a room to the reservation |
Play condition (combining with presence detection)
For workflows on the Speaker channel, you can also choose a play condition in addition to the anchor event and offset. This narrows down whether the announcement actually plays at the scheduled time based on whether anyone is present in the room (the device's presence detection).
| Play condition | Behavior |
|---|---|
| Always | Plays unconditionally at the scheduled time, regardless of presence (the previous behavior) |
| Only if present | Plays if someone is present at the scheduled time; skips silently if no one is present |
| Only on first presence | Waits after the scheduled time and plays once, the first moment presence is detected. If no presence is detected before the reservation ends, it never plays |
Example use cases:
- A cleanup reminder before check-out → anchor "Reservation end" + "before" offset + play condition "Only if present" (so it doesn't announce into an already-empty, checked-out room)
- A welcome message on entry → anchor "Reservation start" + play condition "Only on first presence" (plays when the guest actually walks in, even if that's later than when they completed check-in)
If you don't choose a play condition, it behaves the same as "Always".
Feature 4: 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.
One rule bills at most once (¥3) per reservation. It does not scale with how many speakers the rule selected. Reservations shown as "not covered" are not billed.
Troubleshooting
Audio doesn't play
- Check the status on the Notification Workflow History tab. "Not covered" means the cause is a room setting (see the table under "Checking delivery results" above)
- 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 on the same History tab. 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 in the audio-generation block on the message 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. If the script contains a variable placeholder like {{guest_name}}, generation is blocked outright — replace it with fixed wording.
I want to change a speaker's voice
In the message edit screen's audio-generation block, pick a different voice and click "Generate audio" to regenerate.
FAQ
Q: Can one rule play on multiple speakers at the same time?
A: No. A single reservation plays on one speaker — the one in that reservation's room. Selecting several speakers chooses which rooms the rule covers, not simultaneous playback. Building-wide announcements are not supported today.
Q: A speaker I registered doesn't appear in the delivery rule
A: It has no room assigned. Go to Settings → Rooms → the "Speaker Assignment" tab and put it in the room it is installed in.
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: Can I use variables in the voice script?
A: No, not for the Speaker channel. Variables normally expand per-guest at send time, but speaker audio is generated once from the script text and played back as-is afterward, so the expansion never takes effect. Use fixed wording only.
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.