# Intercom, les annonces à voix haute

> Dites une courte annonce à voix haute sur les haut-parleurs d'un hub, tout restant désactivé jusqu'à ce que le foyer l'active. Pas un système de sécurité.

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

---
**Intercom** permet à une personne, à un script ou à un agent de dire une courte phrase à voix haute sur les haut-parleurs d'un [hub](/concepts/hubs/) : « Le souper est prêt », « Le livreur est à la porte », « C'est l'heure de partir pour l'école ». Chaque haut-parleur dit le texte avec sa propre synthèse vocale. Intercom ne fait qu'annoncer : personne ne peut écouter à travers un haut-parleur, et il n'y a pas d'audio bidirectionnel.

  Intercom n'est pas un système de sécurité certifié. Il ne remplace ni les
  détecteurs de fumée ou de CO, ni les dispositifs d'alerte médicale, ni les
  services d'urgence, et une annonce peut ne pas être entendue : un
  haut-parleur peut être hors ligne, en mode ne pas déranger, ou dans une pièce
  vide. Ne comptez jamais dessus en cas d'urgence.

  Intercom est déployé progressivement et reste désactivé pour tous les
  comptes tant que Thalovant ne l'active pas pour la plateforme. D'ici là,
  l'onglet **Intercom** indique que ce n'est pas encore disponible, et l'API
  répond `intercom_disabled_platform`.

## Ce qu'il fait et ce qu'il ne fait pas

- Il dit un texte d'au plus 280 caractères sur les haut-parleurs que vous choisissez, une fois ou, s'il est urgent, jusqu'à ce que quelqu'un réponde.
- Il n'enregistre ni ne conserve la parole, et la plateforme ne garde jamais le texte dit. Pendant une annonce urgente, le hub vérifie seulement si une réponse est un accusé de réception.
- Il commence désactivé, et chaque étape qui l'active appartient au foyer.

## Désactivé jusqu'à ce que vous l'activiez

Rien n'est dit dans une maison tant que le foyer n'a pas activé chaque étape :

| Étape | Par défaut | Qui la change |
| --- | --- | --- |
| Intercom du hub | Désactivé. Jamais disponible sur un hub pour enfants ni sur un hub public, et seulement avec les forfaits qui l'incluent. | Le propriétaire du hub ou un gestionnaire, dans l'onglet **Intercom** du hub. |
| **Recevoir** de chaque haut-parleur | Désactivé. Un haut-parleur qui ne reçoit pas n'est jamais sollicité, pas même par une annonce urgente. | Les mêmes personnes, haut-parleur par haut-parleur. |
| **Ne pas déranger** | Désactivé. Les heures calmes, dans le fuseau horaire du haut-parleur (UTC à défaut), font sauter les annonces normales. Les annonces urgentes les ignorent. | Les mêmes personnes, haut-parleur par haut-parleur. |

Tout [client](/concepts/clients/) du hub peut être un haut-parleur : un satellite vocal, une tablette, un onglet de navigateur. Donnez à chacun une **pièce** (texte libre, comme « cuisine ») et jusqu'à huit **groupes** (comme « rez-de-chaussée » ou « enfants »), et vous pourrez annoncer à une pièce ou à un groupe plutôt que de lister les haut-parleurs.

1. **Ouvrez l'onglet Intercom du hub** et lisez l'avis ci-dessus. Activez Intercom. Thalovant s'assure que le hub exécute la compétence Intercom, ce qui peut prendre un moment la première fois.
2. **Choisissez les haut-parleurs.** Activez **Recevoir** pour ceux qui doivent parler, et réglez leur pièce, leurs groupes et leurs heures calmes.
3. **Faites un essai.** Écrivez une courte phrase, choisissez un haut-parleur et envoyez. Le résultat liste chaque haut-parleur : livré, hors ligne, ignoré pour cause de ne pas déranger, ou ne reçoit pas.

Désactiver Intercom refuse toute nouvelle annonce. Pour arrêter une annonce urgente déjà en cours de répétition, annulez-la (le bouton **Arrêter**, ou `POST /announcements/{id}/cancel`) ou répondez à voix haute (« I'm okay », « stop »). La compétence peut rester installée sur le hub; elle répond « désactivé » à toute demande.

## Ce qui arrive au texte

Le texte est dit à voix haute et **n'est pas conservé**. Thalovant garde la longueur du texte et son empreinte, qui l'a envoyé, à quels haut-parleurs il est allé et ce qui s'est passé sur chacun, et rien d'autre : ni dans la base de données, ni dans les journaux, ni dans la piste d'audit. Le texte passe de l'API au hub et y est dit. Le résultat d'une annonce ne montre donc jamais ce qui a été dit.

## Normale et urgente

Une annonce **normale** est dite une fois sur chaque haut-parleur admissible. L'API attend jusqu'à dix secondes la réponse du hub et répond avec le résultat.

Une annonce **urgente** exige la portée supplémentaire `intercom:urgent` et peut se répéter : jusqu'à 10 fois, toutes les 5 à 120 secondes, jusqu'à ce que quelqu'un, sur n'importe quel haut-parleur, dise qu'il a entendu (« I'm okay », « got it », « I heard », « stop »). Elle ignore ne pas déranger, mais jamais **Recevoir**. L'API répond tout de suite avec le statut `sending`; relisez l'annonce pour la suivre. Le haut-parleur qui a entendu l'accusé de réception est indiqué dans `acked_by`.

Un hub accepte 20 annonces normales par minute et 10 annonces urgentes par heure. Au-delà, l'API répond `429` avec `Retry-After`.

## Utiliser l'API

Tout se trouve sous `/v1/hubs/{hub_id}/intercom`, avec un jeton d'utilisateur ou d'API qui peut atteindre le hub :

| Appel | Ce qu'il fait | Portée |
| --- | --- | --- |
| `GET /settings` | Si Intercom est activé, et si le forfait et le hub le permettent (`unavailable_reason` : `plan`, `kid_hub`, `public_hub`). | `intercom:read` |
| `PUT /settings` | L'activer ou le désactiver : `{"enabled": true}`. Refusé pour un forfait qui ne l'inclut pas (`403 plan_limit`) et pour les hubs pour enfants ou publics (`422`). | `hubs:write` |
| `GET /speakers` | Chaque client du hub avec `online`, `last_seen_at` et ses réglages : `receive`, `room`, `groups`, `dnd`. | `intercom:read` |
| `PATCH /speakers/{client_id}` | Modifier n'importe lequel des réglages d'un haut-parleur. | `hubs:write` |
| `POST /announce` | Dire un texte. Accepte un en-tête `Idempotency-Key` facultatif. | `intercom:send` |
| `GET /announcements/{id}` | Une annonce et le résultat pour chaque haut-parleur. | `intercom:read` |
| `GET /announcements?limit&cursor` | Les annonces du hub, de la plus récente à la plus ancienne. | `intercom:read` |

`intercom:read` et `intercom:send` peuvent être ajoutées à un [jeton d'API](/account/api-tokens/) avec un forfait qui inclut Intercom. Une annonce qui attend son résultat (`wait`) interroge aussi l'API : ce jeton doit alors avoir les deux portées. Elles sont séparées exprès : un jeton qui peut annoncer, on le confie à un agent en connaissance de cause, et la gestion des haut-parleurs et de l'interrupteur reste sous `hubs:write`.

Le corps d'une annonce :

```json
{
  "text": "Le souper est prêt",
  "targets": { "rooms": ["cuisine", "salon"] },
  "priority": "normal",
  "lang": "fr-CA"
}
```

- `text` fait de 1 à 280 caractères, sans espaces aux extrémités ni caractères de contrôle.
- `targets` est exactement l'un de `{"all": true}`, `{"speakers": [...]}` (identifiants de clients ou slugs, 50 au plus), `{"rooms": [...]}` ou `{"groups": [...]}`.
- `priority` vaut `normal` (par défaut) ou `urgent`. `repeat` (`{"times": 1-10, "interval_seconds": 5-120}`) ne vaut que pour l'urgent.

La réponse est `200` pour une annonce normale et `202` pour une annonce urgente qui se répète :

```json
{
  "id": "5b7d...",
  "status": "completed",
  "priority": "normal",
  "created_at": "2026-11-11T18:30:00Z",
  "deliveries": [
    { "client_id": "c1", "slug": "tablette-cuisine", "name": "Cuisine", "status": "delivered", "at": "2026-11-11T18:30:01Z" },
    { "client_id": "c2", "slug": "chambre", "name": "Chambre", "status": "skipped_dnd", "at": "2026-11-11T18:30:01Z" }
  ],
  "acked_by": null
}
```

`status` vaut `completed`, `partial`, `failed` ou `sending`. Chaque livraison vaut `delivered`, `acked`, `offline`, `skipped_dnd`, `skipped_not_receiving` ou `failed`. Quand personne n'est admissible, la réponse est `200` avec le statut `failed` et chaque livraison dit pourquoi. Si le hub lui-même ne répond pas, l'API renvoie `502` (`hub_unreachable`); si Intercom est désactivé pour le hub, `403` ou `422` avec `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":"Le souper est prêt","targets":{"rooms":["cuisine"]}}'
```
  
  
```python
from thalovant import IntercomTargets, ThalovantControlPlane

api = ThalovantControlPlane(access_token=token)
result = api.announce(
    hub_id,
    "Le souper est prêt",
    IntercomTargets.for_rooms("cuisine"),
    idempotency_key="souper-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: "Le souper est prêt",
  targets: { rooms: ["cuisine"] },
  idempotencyKey: "souper-2026-11-11",
});
console.log(result.status, result.deliveries.map((d) => [d.slug, d.status]));
```
  

Une annonce urgente qui se répète, suivie jusqu'à la fin :

  
```python
result = api.announce(
    hub_id,
    "Venez à la cuisine tout de suite",
    IntercomTargets.for_groups("rez-de-chaussee"),
    priority="urgent",
    repeat={"times": 3, "interval_seconds": 20},
    wait=True,          # interroge jusqu'à la fin de l'envoi (exige aussi intercom:read)
)
print(result.status, result.acked_by)
```
  
  
```ts
const result = await api.announce(hubId, {
  text: "Venez à la cuisine tout de suite",
  targets: { groups: ["rez-de-chaussee"] },
  priority: "urgent",
  repeat: { times: 3, interval_seconds: 20 },
  wait: true, // interroge jusqu'à la fin de l'envoi (exige aussi intercom:read)
});
console.log(result.status, result.acked_by);
```
  

Si une annonce normale ne reçoit aucune réponse (le réseau a coupé), elle a peut-être déjà été dite. Ne la renvoyez pas à l'aveugle : envoyez-la avec un `Idempotency-Key` et, pour réessayer, réutilisez la même clé, de sorte que l'API renvoie le premier résultat au lieu de parler deux fois.

Les appels du SDK s'appellent `announce`, `get_announcement`, `list_announcements`, `list_intercom_speakers`, `update_intercom_speaker`, `get_intercom_settings` et `set_intercom_settings` (en camelCase dans Node.js, comme `listIntercomSpeakers`). Ils ne s'appellent pas « intercom » exprès : la trame `intercom` du maillage d'un hub est autre chose, une trame du protocole de maillage du hub. Voir [Fonctions du SDK](/developers/sdk-functions/#intercom).

## Utiliser Intercom depuis un agent

Le [serveur MCP](/developers/mcp/#intercom) a deux outils de lecture, `thalovant_intercom_list_speakers` et `thalovant_intercom_get_announcement`, et un outil **sur activation volontaire**, `thalovant_intercom_announce`, enregistré seulement quand la personne qui exécute le serveur définit `THALOVANT_ENABLE_INTERCOM_ANNOUNCE=1`. Il exige la portée `intercom:send`, un texte de 280 caractères simples au plus, des cibles explicites (`all` seulement avec `allowAll: true`) et `confirmUrgent: true` pour une annonce urgente.

D'autres outils MCP atteignent un hub comme l'un de ses clients, comme `thalovant_emit_event`. Si l'activation volontaire doit être la seule façon pour un agent de parler dans une maison, refusez aussi `thalovant_emit_event` sur ce serveur.

## Quand une annonce n'est pas entendue

| Ce que vous voyez | Ce que cela veut dire |
| --- | --- |
| `skipped_not_receiving` | **Recevoir** est désactivé pour ce haut-parleur. Activez-le dans l'onglet Intercom. |
| `skipped_dnd` | Le haut-parleur est dans ses heures calmes et l'annonce était normale. Les annonces urgentes les ignorent. |
| `offline` | Le haut-parleur ne s'est pas connecté récemment. Un haut-parleur est retenu six heures après sa dernière interaction avec le hub. |
| `403` ou `422` `intercom_disabled` | Intercom est désactivé pour le hub, ou c'est un hub pour enfants ou public. |
| `403 plan_limit` | Le forfait n'inclut pas Intercom. |
| `429` | Trop d'annonces pour ce hub : attendez `Retry-After`. |
| `502` `hub_unreachable` | Le hub n'a pas répondu à temps. Il a pu parler quand même : ne renvoyez pas tel quel, vérifiez l'annonce ou réessayez avec la même `Idempotency-Key`. |

Rappelez-vous à quoi sert Intercom : un court message amical dans une maison. Pour tout ce qui ne peut pas être manqué, utilisez un appareil conçu pour cela.

## Pages connexes

- [Hubs](/concepts/hubs/) et [Connexions](/concepts/clients/) : ce que sont un hub et ses haut-parleurs.
- [Jetons d'API](/account/api-tokens/) : les portées `intercom:read` et `intercom:send`.
- [Serveur MCP](/developers/mcp/#intercom) et [Fonctions du SDK](/developers/sdk-functions/#intercom).
