Intercom
Say a short announcement aloud on the speakers of a hub, with every switch off until the household turns it on. Not a safety system.
Intercom lets a person, a script or an agent say a short sentence aloud on the speakers of a hub: “Dinner’s ready”, “The delivery is at the door”, “Time to leave for school”. Each speaker says the text with its own text-to-speech. It only announces: nobody can listen through a speaker, and there is no two-way audio.
What It Does And Doesn’t Do
Section titled “What It Does And Doesn’t Do”- It says a text of up to 280 characters on the speakers you choose, once or, if urgent, until someone answers.
- It does not record or store speech, and the platform never keeps the text that was said. While an urgent announcement sounds, the hub only checks whether a reply is an acknowledgement.
- It starts off, and each step that turns it on belongs to the household.
It Is Off Until You Turn It On
Section titled “It Is Off Until You Turn It On”Nothing is spoken in a home unless the household switched each step on:
| Step | Default | Who changes it |
|---|---|---|
| The hub’s Intercom | Off. Never available on a kids’ hub or a public hub, and only on plans that include it. | The hub’s owner or a manager, on the hub’s Intercom tab. |
| Each speaker’s Receive | Off. A speaker that doesn’t receive is never spoken to, not even by an urgent announcement. | The same people, speaker by speaker. |
| Do not disturb | Off. Quiet hours, in the speaker’s time zone (UTC when none is set), skip normal announcements. Urgent ones ignore it. | The same people, speaker by speaker. |
Any client of the hub can be a speaker: a voice satellite, a tablet, a browser tab. Give each one a room (free text such as “kitchen”) and up to eight groups (such as “downstairs” or “kids”), and you can announce to a room or a group instead of listing speakers.
- Open the hub’s Intercom tab and read the notice above. Switch Intercom on. Thalovant makes sure the hub runs the Intercom skill, which can take a short while the first time.
- Choose the speakers. Switch Receive on for the ones that should speak, and set their room, groups and quiet hours.
- Send a test. Type a short sentence, choose one speaker, and send it. The result lists each speaker: delivered, offline, skipped for do-not-disturb, or not receiving.
Turning Intercom off refuses every new announcement. To stop an urgent announcement that is already repeating, cancel it (the Stop button, or POST /announcements/{id}/cancel) or answer out loud (“I’m okay”, “stop”). The skill may stay installed on the hub; it answers “disabled” to every request.
What Happens To The Text
Section titled “What Happens To The Text”The text is spoken aloud and isn’t stored. Thalovant keeps the text’s length and a hash of it, who sent it, which speakers it went to and what happened on each, and nothing else: not in the database, not in logs, not in the audit trail. The text travels from the API to the hub and is said there. The result of an announcement therefore never shows what was said.
Normal And Urgent
Section titled “Normal And Urgent”A normal announcement is said once on each eligible speaker. The API waits up to ten seconds for the hub and answers with the result.
An urgent announcement needs the extra intercom:urgent scope and can repeat: up to 10 times, every 5 to 120 seconds, until someone on any speaker says they heard it (“I’m okay”, “got it”, “I heard”, “stop”). It ignores do-not-disturb, but never ignores Receive. The API answers at once with status sending; read the announcement again to follow it. The speaker that heard the acknowledgement is reported as acked_by.
A hub accepts 20 normal announcements a minute and 10 urgent ones an hour. Past that the API answers 429 with Retry-After.
Use It From The API
Section titled “Use It From The API”Everything is under /v1/hubs/{hub_id}/intercom, with a user or API token that can reach the hub:
| Call | What it does | Scope |
|---|---|---|
GET /settings |
Whether Intercom is on, whether the plan and hub allow it (unavailable_reason: plan, kid_hub, public_hub). |
intercom:read |
PUT /settings |
Turn it on or off: {"enabled": true}. Refused for a plan without it (403 plan_limit) and for kid or public hubs (422). |
hubs:write |
GET /speakers |
Every client of the hub with online, last_seen_at and its settings: receive, room, groups, dnd. |
intercom:read |
PATCH /speakers/{client_id} |
Change any of a speaker’s settings. | hubs:write |
POST /announce |
Say a text. Takes an optional Idempotency-Key header. |
intercom:send |
GET /announcements/{id} |
One announcement and the result for each speaker. | intercom:read |
GET /announcements?limit&cursor |
The hub’s announcements, newest first. | intercom:read |
intercom:read and intercom:send can be added to an API token on a plan that includes Intercom. An announcement that waits for its result (wait) also polls, so that token needs both scopes. They are separate on purpose: a token that can announce is one you give to an agent deliberately, and managing speakers and the switch stays with hubs:write.
The announce body:
{ "text": "Dinner is ready", "targets": { "rooms": ["kitchen", "living room"] }, "priority": "normal", "lang": "en-US"}textis 1 to 280 characters, trimmed, with no control characters.targetsis exactly one of{"all": true},{"speakers": [...]}(client ids or slugs, at most 50),{"rooms": [...]}or{"groups": [...]}.priorityisnormal(default) orurgent.repeat({"times": 1-10, "interval_seconds": 5-120}) applies to urgent only.
The answer is 200 for a normal announcement and 202 for an urgent one that repeats:
{ "id": "5b7d...", "status": "completed", "priority": "normal", "created_at": "2026-11-11T18:30:00Z", "deliveries": [ { "client_id": "c1", "slug": "kitchen-tablet", "name": "Kitchen", "status": "delivered", "at": "2026-11-11T18:30:01Z" }, { "client_id": "c2", "slug": "bedroom", "name": "Bedroom", "status": "skipped_dnd", "at": "2026-11-11T18:30:01Z" } ], "acked_by": null}status is completed, partial, failed or sending. Each delivery is delivered, acked, offline, skipped_dnd, skipped_not_receiving or failed. When nobody is eligible the answer is 200 with status failed and each delivery says why. If the hub itself doesn’t answer, the API returns 502 (hub_unreachable); if Intercom is off for the hub, 403 or 422 with intercom_disabled.
curl -sS -X POST "https://api.thalovant.com/v1/hubs/$HUB_ID/intercom/announce" \ -H "Authorization: Bearer $THALOVANT_API_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"text":"Dinner is ready","targets":{"rooms":["kitchen"]}}'from thalovant import IntercomTargets, ThalovantControlPlane
api = ThalovantControlPlane(access_token=token)result = api.announce( hub_id, "Dinner is ready", IntercomTargets.for_rooms("kitchen"), idempotency_key="dinner-2026-11-11",)print(result.status, [(d.slug, d.status) for d in result.deliveries])import { ThalovantControlPlane } from "@thalovant/sdk";
const api = new ThalovantControlPlane(undefined, { accessToken: token });const result = await api.announce(hubId, { text: "Dinner is ready", targets: { rooms: ["kitchen"] }, idempotencyKey: "dinner-2026-11-11",});console.log(result.status, result.deliveries.map((d) => [d.slug, d.status]));An urgent announcement that repeats, followed until it finishes:
result = api.announce( hub_id, "Please come to the kitchen now", IntercomTargets.for_groups("downstairs"), priority="urgent", repeat={"times": 3, "interval_seconds": 20}, wait=True, # poll until it stops sending (needs intercom:read as well))print(result.status, result.acked_by)const result = await api.announce(hubId, { text: "Please come to the kitchen now", targets: { groups: ["downstairs"] }, priority: "urgent", repeat: { times: 3, interval_seconds: 20 }, wait: true, // poll until it stops sending (needs intercom:read as well)});console.log(result.status, result.acked_by);If a normal announcement gets no answer at all (the network dropped), it may already have been spoken. Don’t send it again blindly: send it with an Idempotency-Key and, to try again, reuse the same key, so the API returns the first result instead of speaking twice.
The SDK calls are named announce, get_announcement, list_announcements, list_intercom_speakers, update_intercom_speaker, get_intercom_settings and set_intercom_settings (camel case in Node.js, such as listIntercomSpeakers). They are not called “intercom” on purpose: the intercom frame of a hub’s mesh is a different thing, a frame of the hub mesh protocol. See SDK Functions.
Use It From An Agent
Section titled “Use It From An Agent”The MCP server has two read tools, thalovant_intercom_list_speakers and thalovant_intercom_get_announcement, and an opt-in thalovant_intercom_announce, registered only when the person running the server sets THALOVANT_ENABLE_INTERCOM_ANNOUNCE=1. It needs the intercom:send scope, a text of at most 280 plain characters, explicit targets (all only with allowAll: true), and confirmUrgent: true for an urgent announcement.
Other MCP tools reach a hub as one of its clients, such as thalovant_emit_event. If the opt-in is meant to be the only way an agent speaks in a home, deny thalovant_emit_event on that server too.
When An Announcement Isn’t Heard
Section titled “When An Announcement Isn’t Heard”| What you see | What it means |
|---|---|
skipped_not_receiving |
The speaker’s Receive is off. Switch it on in the Intercom tab. |
skipped_dnd |
The speaker is in its quiet hours and the announcement was normal. Urgent ones ignore quiet hours. |
offline |
The speaker hasn’t connected recently. A speaker is remembered for six hours after it last spoke to the hub. |
403 or 422 intercom_disabled |
Intercom is off for the hub, or the hub is a kids’ or public hub. |
403 plan_limit |
The plan doesn’t include Intercom. |
429 |
Too many announcements for this hub: wait for Retry-After. |
502 hub_unreachable |
The hub didn’t answer in time. It may still have spoken, so don’t just send again: check the announcement, or retry with the same Idempotency-Key. |
Remember what Intercom is for: a short, friendly message in a home. For anything that can’t be missed, use a device built for it.
Related Pages
Section titled “Related Pages”- Hubs and Connections: what a hub and its speakers are.
- API tokens: the
intercom:readandintercom:sendscopes. - MCP server and SDK Functions.