# RoomCall

> RoomCall is a Home Assistant custom integration (Marketplace, or HACS before HA 2026.11) that turns the speakers Home Assistant
> already controls (Sonos, Google Cast/Nest, AirPlay, HEOS receivers, Android TV boxes) into an
> intercom and announcement system, organised by Home Assistant areas.

Domain: `roomcall`. One config entry. Everything is managed through standard Home Assistant
APIs; no extra credentials.

## Do things

- Start with `roomcall__catalog`: API version, operation schemas, response envelope and bootstrap recipe.
- Setup before an entry exists: after Marketplace or HACS installation (restart if HA asks), start HA's RoomCall user config flow.
  Opening the flow registers tools/card resources; no entry or optional service is created yet.
- `roomcall__setup` actions discover/plan/apply/test/confirm/verify/list/get/undo share the card's
  guided setup backend. Authenticated HA administrator required. Discovery includes settings_schema.
  Plans persist 24 hours, are owner-scoped and revision checked; interrupted apply/undo can resume.
  Undo requires confirm:true and current revision; new entries with added announcements are protected.
- Choose a speech provider if ambiguous, or explicitly plan media_only:true. Never fabricate heard:true.
- `roomcall__announcements`: schema/list/create/update/enable/disable/delete. Native HA subentries;
  revisions for changes, confirm:true for delete, bounded persistent create idempotency.
- `roomcall__doctor`: diagnose setup failures, or action:plan_route for an identified physical
  alternate endpoint. Returns a draft; never silently changes policy/network/cloud/retention.
- Speak or play audio now: action `roomcall.broadcast` with `areas`, `floors`, `labels`, `speakers`, `people`,
  `message` or `media_url`, `priority` (`normal`|`urgent`), `volume`. Returns
  `{ok, id, results[], skipped}`.
- Assist / LLM agents: intent `RoomCallAnnounce` (slots `message`, `area`, `urgent`).
- Current HA: explicit `roomcall__*` LLM tools. Older HA: select the RoomCall LLM API.
- Discover first: `roomcall__discover`; preview explicit recipients with `roomcall__preview`.
- Send: `roomcall__send` with targets + message/media_url; returns a job id. Retry the
  same payload with the same idempotency_key; check `roomcall__status` afterward.
- Questions: `roomcall__ask` on compatible discovered satellites; actual transcribed responses.
- Diagnose: `roomcall__diagnose`. Stable errors include dnd_blocked, quiet_hours_blocked,
  presence_unknown, forbidden, expired and idempotency_conflict. Never silently use urgent.
- HTTP: authenticated POST `/api/roomcall/command` with `{operation,request}`.
- HA action: `roomcall.communicate` with `{operation,request}` and return_response.
- Success means playback request acceptance, not audible playback. Inspect separate
  audio_fetched_ms/playback_reported_ms evidence; human acknowledgment is explicit.
- New send operations require areas/floors/labels/speakers/people or everywhere:true, directly or through a household profile.
  HA permissions and assistant exposure apply. Ordinary jobs/keys are bounded and in memory.
- Durable text jobs: durable:true requires an explicit idempotency_key. Queued/unexpired work
  resumes with current policy after HA startup. Potentially dispatched work becomes interrupted;
  never automatically resend it. Retained owner/key/results: at most 128 jobs, up to 24 hours.
- discover.profiles lists permitted household presets; preview/send accept profile:<id>.
  Explicit targets replace all preset destinations. Voice/chime changes are per message.
- discover.speech_profiles lists configured fast/balanced/quality voice labels. Send speech_profile:<label>.
  Explicit speech profiles override household engine/voice. Labels do not promise model speed.
- roomcall__speech action:prepare takes message/targets to prepare without playback. Owner-scoped
  memory cache: ten minutes, 32 entries, 16 MiB total, 4 MiB/item. action:clear requires an administrator.
  Reload or clear after changing provider defaults or replacing a custom chime file in place.
- roomcall__policy reports additional RoomCall account restrictions: destinations, operations,
  local hours, urgency, requested volume and runtime message rate. Use dedicated non-admin accounts;
  these restrictions do not scope unrelated HA APIs. Accounts without a policy retain existing rules.
- status.progress is a bounded measured delivery timeline, not evidence of hearing.
  Authenticated WS roomcall/job_events with job_id subscribes to one owned job. Ownership
  and permissions are rechecked for every update; unsubscribe with HA unsubscribe_events.
- Speak in one room: `notify.send_message` on `notify.roomcall_<room>`.
- Do Not Disturb: `switch.roomcall_do_not_disturb`.

## Announcements (config subentries)

- Types: `scheduled` (`time`, `days`) and `triggered` (`entity`, `to_state`, `for`, `cooldown`).
- Shared fields: `name`, `message` (template), `rooms`, `target_speakers`, `people`, `priority`.
- Create: POST `/api/config/config_entries/subentries/flow` with
  `{"handler": [entry_id, "scheduled"]}`, then POST the fields to `.../flow/<flow_id>`.
- List/delete: WebSocket `config_entries/subentries/list` / `config_entries/subentries/delete`.
- Each announcement has `button.*_play_now` and `switch.*_enabled` (attributes describe it).
- Optional `task` (text someone confirms, e.g. "Took out the dry clothes") and `remind_every`
  (minutes, 0 = once): the announcement stays open and repeats until confirmed. Task
  announcements add `sensor.*_task` (idle/open/done, opened, done, done_by) and
  `button.*_mark_done`; completion fires `roomcall_task_completed`.
- `roomcall__tasks`: action list (default) / complete / snooze (`id`, optional `minutes`).
  Complete only when a person says they did it; hearing or dismissing an alert is not doing it.
  HA permissions and assistant exposure apply.

## Read

- `sensor.roomcall_last_call` attribute `history`: last 10 calls.
- Diagnostics download; Repairs for unavailable speakers and bad internal URLs.

## Docs

- [Home Assistant guide](https://daredoole.github.io/RoomCall/home-assistant/)
- [Announcements](https://daredoole.github.io/RoomCall/announcements/)
- [Managing RoomCall with AI](https://daredoole.github.io/RoomCall/ai/)
- [Guided setup and administration contract](https://daredoole.github.io/RoomCall/agent-setup/)
- [Messages, jobs, room stations and adapters](https://daredoole.github.io/RoomCall/communication/)
- [Apple Home intercom](https://daredoole.github.io/RoomCall/apple-home/)

- [Native iOS app, signing and platform limits](https://daredoole.github.io/RoomCall/native-ios/)