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

Source: https://docs.thalovant.com/concepts/intercom/

---
**Intercom** lets a person, a script or an agent say a short sentence aloud on the speakers of a [hub](/concepts/hubs/): "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.

  Intercom is not a certified safety system. It does not replace smoke or CO
  alarms, medical alert devices or the emergency services, and an announcement
  can fail to be heard: a speaker may be offline, on do-not-disturb, or in an
  empty room. Never rely on it for an emergency.

  Intercom is rolling out gradually and is off for every account until
  Thalovant switches it on for the platform. Until then the **Intercom** tab
  says it isn't available yet, and the API answers `intercom_disabled_platform`.

## 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

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](/concepts/clients/) 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.

## 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

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

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](/account/api-tokens/) 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:

```json
{
  "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:

```json
{
  "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`.

  
```bash
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"]}}'
```
  
  
```python
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])
```
  
  
```ts

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:

  
```python
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)
```
  
  
```ts
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](/developers/sdk-functions/#intercom).

## Use It From An Agent

The [MCP server](/developers/mcp/#intercom) 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

| 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

- [Hubs](/concepts/hubs/) and [Connections](/concepts/clients/): what a hub and its speakers are.
- [API tokens](/account/api-tokens/): the `intercom:read` and `intercom:send` scopes.
- [MCP server](/developers/mcp/#intercom) and [SDK Functions](/developers/sdk-functions/#intercom).
