Home Assistant

Home Assistant Integration

Connect Thriva to Home Assistant so your family’s agreed plan becomes part of your home. When Quiet Time begins, lights can soften. When Focused Time starts, a scene can settle the space for work. Your home follows the plan you made together — no extra steps for anyone.

Note

This integration requires the Thriva custom component installed via HACS. You’ll also need the Home Assistant app (2024.1 or later) and an active Thriva account.

What Home Assistant Can See

Home Assistant receives plan-level mode state only for each child you include:

• The child’s current mode (Focused Mode, Free Time, Quiet Time, or a custom mode)
• When the current mode started
• When it ends (if scheduled)
• The next scheduled transition

That’s it. Home Assistant never sees app usage, screen time, website history, messages, tasks, or any activity data. This is a privacy floor built into the integration — not a setting you can change. The goal is to let your home respond to the family plan, not to create a usage scoreboard.

Step 1 — Install the Thriva Component via HACS

Caution

You need HACS installed in Home Assistant before continuing. If you haven’t set it up, follow the HACS installation guide first.

1. Open Home Assistant and go to HACS in the sidebar.
2. Click the ⋮ menu (top right) → Custom repositories.
3. Add the repository:
   • Repository URL: https://github.com/Wldc4rd/thriva
   • Type: Integration
   • Click Add.
4. Search for Thriva in HACS and click Download.
5. Restart Home Assistant when prompted.

Step 2 — Get Your Thriva Token

Thriva uses a dedicated read-only token for Home Assistant — separate from your account password, revocable at any time.

1. Open the Parent Portal → Settings → Integrations.
2. Click Home Assistant.
3. Click Create token.
4. You’ll be asked to confirm your password (this protects token creation).
5. Select which children to include — only the children you choose appear as sensors in Home Assistant. Default is none; select deliberately.
6. Optionally give the token a label (e.g., “Living room display”).
7. Click Create.
8. Copy the token now — it’s shown only once and cannot be retrieved later.

The token list shows each token’s label, which children it covers, a short prefix for identification, when it was created, and when it was last used.

Step 3 — Connect in Home Assistant

1. In Home Assistant, go to Settings → Devices & Services → Add integration.
2. Search for Thriva and click it.
3. In the config flow:
   • API URL: leave as https://api.thriva.app unless you’re self-hosting.
   • Token: paste the token you copied in Step 2.
4. Click Submit. Home Assistant validates the token and creates one sensor per child you scoped.

Your Sensors

Each child you included becomes a sensor in Home Assistant:

Entity	State	Example
sensor.thriva_emma_mode	Mode slug	focused / free_time / quiet_time

The entity ID is derived from the child’s display name in Thriva — spaces become underscores, lowercased. If you rename a child in Thriva, the entity ID stays stable (it’s tied to an internal identifier, not the name).

Sensor attributes

Attribute	Description
child_label	The child’s display name in Thriva
mode_id	Numeric mode identifier
since	When the current mode started (ISO 8601 UTC)
until	When the current mode ends, if scheduled (ISO 8601 UTC)
scheduled_next	The upcoming transition — mode and time
family_plan_ref	Which schedule or plan set this mode
last_synced	When Thriva last updated this data

Sensors update every 60 seconds by default (minimum 30 seconds — faster polling won’t improve freshness and increases API load).

Unavailable state

If the Thriva API is unreachable, your token is revoked, or the data becomes stale, sensors go unavailable rather than showing an outdated mode. This is intentional — a home automation that triggers on a confidently wrong mode is worse than one that pauses.

When a sensor goes unavailable:

• Automations that check state will stop triggering (safe default)
• Check Settings → Integrations → Home Assistant in the Parent Portal — a revoked or expired token will show there
• Re-authorize by revoking the old token, creating a new one, and re-entering it in Home Assistant’s integration config

Example Automations

These examples follow the same principle as Thriva’s Device Availability Plan: gentle, supportive, and plan-following. None of them announce a child’s mode publicly, trigger on failures, or create pressure.

Warm lights at Quiet Time

alias: "Thriva — warm lights at Quiet Time"
trigger:
  - platform: state
    entity_id: sensor.thriva_emma_mode
    to: "quiet_time"
action:
  - service: light.turn_on
    target:
      area_id: emmas_room
    data:
      color_temp_kelvin: 2700
      brightness_pct: 30

Focus scene at Focused Time

alias: "Thriva — focus scene at Focused Time"
trigger:
  - platform: state
    entity_id: sensor.thriva_emma_mode
    to: "focused"
action:
  - service: scene.turn_on
    target:
      entity_id: scene.focus_lights

10-minute pre-transition cue

Use the until attribute to give a gentle heads-up before a mode change:

alias: "Thriva — 10-min warning before mode change"
trigger:
  - platform: template
    value_template: >
      {% set until = state_attr('sensor.thriva_emma_mode', 'until') %}
      {% if until %}
        {% set t = as_datetime(until) %}
        {{ (t - now()).total_seconds() | int in range(580, 620) }}
      {% else %}
        false
      {% endif %}
action:
  - service: light.turn_on
    target:
      area_id: living_room
    data:
      flash: short

Whole-house wind-down when everyone reaches Quiet Time

alias: "Thriva — whole-house wind-down"
trigger:
  - platform: state
    entity_id:
      - sensor.thriva_emma_mode
      - sensor.thriva_sam_mode
    to: "quiet_time"
condition:
  - condition: template
    value_template: >
      {{ states('sensor.thriva_emma_mode') == 'quiet_time'
         and states('sensor.thriva_sam_mode') == 'quiet_time' }}
action:
  - service: scene.turn_on
    target:
      entity_id: scene.evening_wind_down

Binary sensor from mode (for dashboards)

A template binary sensor is useful for dashboard cards or simpler automations:

template:
  - binary_sensor:
      - name: "Emma — Focused Time"
        state: >
          {{ states('sensor.thriva_emma_mode') == 'focused' }}
        icon: >
          {{ 'mdi:book-open' if states('sensor.thriva_emma_mode') == 'focused'
             else 'mdi:book-outline' }}

Managing Tokens

Viewing active tokens

Settings → Integrations → Home Assistant shows all your tokens with:

• Label and scoped children
• Token prefix (for identifying which token is which)
• Created date and last used date (“Never” if unused)

The last used date lets you tell which tokens are active and which can safely be revoked.

Revoking a token

If you change your HA setup, suspect a token was exposed, or simply want to rotate credentials:

1. Go to Settings → Integrations → Home Assistant in the Parent Portal.
2. Click Revoke next to the token.
3. Confirm your password.
4. The token stops working immediately.

After revoking, sensors in Home Assistant will go unavailable until you create a new token and update the integration.

Token hygiene tips

• Create one token per Home Assistant instance (easier to track)
• Use labels (“Living room”, “Dashboard Pi”) so you know what each token is for
• Revoke tokens you’re no longer using — the last used column makes this easy to audit
• If you lose a token before copying it, just revoke it and create a fresh one

Privacy

Thriva’s Home Assistant integration is designed around what HA genuinely needs — and nothing more.

• Plan mode only. HA sees focused, free_time, or quiet_time — the same state your child sees on their device. It does not receive app names, session durations, websites visited, chat messages, or tasks.
• Per-child scoping. Each token covers only the children you deliberately selected. Adding a new child to your family does not automatically expose them to Home Assistant.
• Revocable at any time. Revoking a token is immediate and requires no changes on the HA side — sensors simply go unavailable.
• No write access. Home Assistant cannot change a child’s mode, extend Free Time, or interact with Thriva in any way. The integration is strictly read-only.

Troubleshooting

Sensors show as unavailable

• Check that your token is still active in Settings → Integrations → Home Assistant
• If the token shows a recent last used time, the API is reachable — check the HA integration logs
• If last used hasn’t updated in hours, re-enter the token in Home Assistant’s integration config

Sensors not created for some children

Only children selected when you created the token appear as sensors. To add a child:

1. Create a new token and include all children you want
2. Update the Home Assistant integration with the new token
3. Revoke the old token

You cannot add children to an existing token — create a new one.

Entity IDs don’t match your child’s name

Entity IDs are generated from the child’s display name at the time the integration was configured (spaces → underscores, lowercased). If you’ve renamed the child in Thriva, the entity ID stays the same — the child_label attribute reflects the current name.

Automations not triggering

• Verify the sensor state matches what you’re testing against — check Developer Tools → States in HA
• Mode slugs are lowercase: focused, free_time, quiet_time (custom modes use their slug from Thriva)
• Sensor data refreshes every 60 seconds — a mode change may take up to a minute to appear