Skip to content
Console
Try one

    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.

    • 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.

    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.

    1. 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.
    2. Choose the speakers. Switch Receive on for the ones that should speak, and set their room, groups and quiet hours.
    3. 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.

    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.

    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.

    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"
    }
    • text is 1 to 280 characters, trimmed, with no control characters.
    • targets is exactly one of {"all": true}, {"speakers": [...]} (client ids or slugs, at most 50), {"rooms": [...]} or {"groups": [...]}.
    • priority is normal (default) or urgent. 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.

    Terminal window
    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"]}}'

    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)

    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.

    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.

    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.