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é.
Intercom permet à une personne, à un script ou à un agent de dire une courte phrase à voix haute sur les haut-parleurs d’un hub : « 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.
Ce qu’il fait et ce qu’il ne fait pas
Section intitulée « 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
Section intitulée « 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 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.
- 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.
- Choisissez les haut-parleurs. Activez Recevoir pour ceux qui doivent parler, et réglez leur pièce, leurs groupes et leurs heures calmes.
- 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
Section intitulée « 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
Section intitulée « 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
Section intitulée « 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 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 :
{ "text": "Le souper est prêt", "targets": { "rooms": ["cuisine", "salon"] }, "priority": "normal", "lang": "fr-CA"}textfait de 1 à 280 caractères, sans espaces aux extrémités ni caractères de contrôle.targetsest exactement l’un de{"all": true},{"speakers": [...]}(identifiants de clients ou slugs, 50 au plus),{"rooms": [...]}ou{"groups": [...]}.priorityvautnormal(par défaut) ouurgent.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 :
{ "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.
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"]}}'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])import { ThalovantControlPlane } from "@thalovant/sdk";
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 :
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)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.
Utiliser Intercom depuis un agent
Section intitulée « Utiliser Intercom depuis un agent »Le serveur MCP 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
Section intitulée « 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
Section intitulée « Pages connexes »- Hubs et Connexions : ce que sont un hub et ses haut-parleurs.
- Jetons d’API : les portées
intercom:readetintercom:send. - Serveur MCP et Fonctions du SDK.