Tater Assistant Docs
Portal profile

HomeKit

Siri and Apple Shortcuts portal for a full Siri-to-Tater round-trip, with per-device sessions, Shortcut-friendly JSON, and optional auth protection.

Voice endpoint v1.1.3 5 settings 48 Verbas
Portal role

What this portal is for

Voice endpoint

Highlights

Behavior in the current codebase

  • Provides lightweight Siri and Apple Shortcuts routes mounted inside the main Tater app.
  • Designed for Shortcut-driven voice loops where Siri captures speech, posts JSON to Tater, then speaks the reply back aloud.
  • Maintains per-device conversation sessions instead of treating every request as stateless.
  • Supports optional API key protection so Shortcuts must send X-Tater-Token when enabled.
  • Uses the default Tater port, so no separate HomeKit service port is needed.
  • Good fit for Apple-first households that want voice access without a full chat client.
Settings

Configuration schema

  • Require API Key select

    Require X-Tater-Token on HomeKit API requests.

    Key: API_AUTH_ENABLED Default: false Options: true, false
  • API Key password

    Shared API key expected in the X-Tater-Token header when auth is enabled.

    Key: API_AUTH_KEY
  • Legacy Auth Token (optional) password

    Backward-compatible fallback token if API Key is empty.

    Key: AUTH_TOKEN
  • Session TTL (seconds) number

    How long to keep a Siri session alive.

    Key: SESSION_TTL_SECONDS Default: 3600
  • Legacy Bind Port number

    Deprecated. Siri / Shortcuts now uses Tater's main API path: /api/portals/homekit_portal/api/tater-homekit/v1

    Key: bind_port Default: 8789
Shortcut guide

How to connect Siri and Apple Shortcuts to this portal.

These notes focus on the Shortcut flow, session handling, optional auth, and the Siri voice round-trip.

ShortcutSiriQuick start

Premade shortcut

A ready-made Apple Shortcut already exists for the HomeKit portal.

  • You can start from the premade Ask Tater shortcut instead of building the flow by hand.
  • It is a good baseline even if you later customize the session_id, endpoint IP, or auth header.
Premade Shortcut
Dictate TextPOST JSONSpeak Text

Build the shortcut

The common Shortcut flow is Dictate Text -> Get Contents of URL -> Get Dictionary Value -> Speak Text.

  • Create a shortcut such as Ask Tater, then add Dictate Text with stop listening set to After Pause.
  • Use Get Contents of URL to POST JSON to http://YOUR-TATER-IP:8501/tater-homekit/v1/message with text and session_id fields.
  • Extract the reply key from the JSON response, then feed it into Speak Text so Siri or a HomePod reads it back.
session_idX-Tater-TokenPer-device memory

Session IDs and auth

Each device should use its own session_id, and protected routes can require the X-Tater-Token header.

  • Use a stable session_id such as iphone, ipad, or bedroom_homepod so conversations do not mix between devices.
  • If API auth is enabled in Tater HomeKit settings, add an X-Tater-Token header inside the shortcut request.
  • The portal keeps short Siri-friendly session history in Redis using the configured session TTL and history limits.
HomePodHandoffSiri phrase

HomePod behavior

HomePods can use the same shortcut flow by handing off through the iPhone that owns the shortcut.

  • After adding the shortcut to Siri, phrases like Ask Tater or Talk to Tater can trigger the round-trip hands-free.
  • If the shortcut lives on the iPhone, a HomePod can hand off the shortcut execution and still speak Tater's reply.
  • This gives Apple households a practical voice surface without needing a separate Apple-native Tater app.
Built-in APIs

HTTP endpoints exposed by this portal.

API auth

When API auth is enabled, requests must include X-Tater-Token with the configured portal API key.

POST /tater-homekit/v1/message

Main Siri / Shortcuts message endpoint.

Accepts JSON with text plus an optional session_id, enforces X-Tater-Token when API auth is enabled, and returns a plain reply field sized for Siri speech.

Back to portals Verbas Portals ESPHome Cores Home