Aller au contenu
Console
Try one

    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.

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

    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.

    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.

    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.

    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.

    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"
    }
    • 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 :

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

    Fenêtre de terminal
    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"]}}'

    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)

    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.

    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.

    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.