HA-Toniebox

Unofficial Home Assistant Integration for Toniebox / Tonie Cloud
Inoffizielle Home Assistant Integration für Toniebox / Tonie Cloud

---

Warning

Disclaimer — Please read before use / Bitte vor der Nutzung lesen

This project has no affiliation with Boxine GmbH (manufacturer of Toniebox / tonies.de) and is neither supported nor endorsed by them. It uses the official Tonie Cloud REST API, which may change at any time without notice. Use at your own risk. No warranty, no support from Boxine.

Dieses Projekt steht in keiner Verbindung zu Boxine GmbH und wird von diesen weder unterstützt noch empfohlen. Es nutzt die offizielle Tonie Cloud REST API, die sich jederzeit ohne Ankündigung ändern kann. Nutzung auf eigene Gefahr.

🤖 This integration was vibecoded — developed with AI assistance (Claude by Anthropic) and tested against a real Toniebox account.

---

🇬🇧 English

Features

• 🧸 Each Creative Tonie as its own device with media player, cover image and chapter list
• 📻 Each Toniebox as its own device — shows the currently placed figure with name and cover
• ▶️ Full playback control on the Toniebox 2 (TNG) — play/pause, next/previous chapter, jump to any chapter (browse), volume, and put to sleep — live via the Tonie Cloud's real-time channel
• 🎚️ Live "now playing" — current chapter title, progress bar and play/pause state
• ⏲️ Sleep timer — start a timer via the toniebox.sleeptimer action, with a sleeptimer_active binary sensor and the alarm that fires at the end of the timer
• ⏰ Weekday alarms — manage the recurring bedtime schedules of the tonies app, with a next_alarm sensor and an on/off switch per schedule
• 📊 Sensors for chapter count, total duration, firmware version, online status, battery level, active figure and figure ID
• 🔘 Buttons to sort (title / filename / date), shuffle, clear and refresh
• 🔀 Shuffle the chapter order on demand (sort_chapters with sort_by: random) or automatically on swap — a per-Creative-Tonie switch that reshuffles a Tonie once a different one replaces it on a box
• 🔴 Binary Sensors for transcoding, live mode, household lock, active figure and running sleep timer
• 🎛️ Switches for LED, chapter skipping, scrubbing, offline mode, household lock
• 🌐 Select entities for language, LED level, tap direction, age mode
• ⚙️ Services for automations: sleeptimer, sort, clear, rename, apply tune, redeem voucher and more
• 🌍 Translations for English, German, French, Spanish and Italian
• 🔐 Keycloak OpenID Connect authentication — same credentials as the Toniebox app
• 🛠️ Config Flow setup — no YAML required
• 📦 Available via the Home Assistant Marketplace / HACS

---

Installation via Marketplace / HACS

Home Assistant 2026.11 and newer come with the built-in Marketplace (the successor of HACS): go to Settings → Marketplace, search for Toniebox and download. If it is not listed, add https://github.com/git4sim/HA-Toniebox as a custom repository of type Integration.

Home Assistant 2026.3 to 2026.10 with HACS installed:

Note

If the button does not work: add https://github.com/git4sim/HA-Toniebox manually in HACS as a Custom Repository of type Integration, search for Toniebox and download.

Restart Home Assistant after download.

Manual Installation

Copy the custom_components/toniebox/ folder from the latest release into your HA configuration directory:

/config/custom_components/toniebox/

Restart Home Assistant.

---

Setup

Note

If the button does not work: go to Settings → Devices & Services → Add Integration and search for Toniebox.

Enter the email address and password of your Toniebox account (the same credentials as in the Toniebox app or on my.tonies.com).

---

Device Hierarchy

The integration creates a logical device hierarchy in Home Assistant:

Household (Hub)
├── Toniebox 1       →  Media Player · Switches · Sensors · Buttons · Select
├── Toniebox 2       →  ...
├── Creative Tonie A →  Media Player · Chapters · Duration · Sort/Clear Buttons · Live/Private Switch
└── Creative Tonie B →  ...

Each device appears under Settings → Devices & Services → Toniebox with its own entities.

---

Entities

Household (Hub device)

Entity	Description
sensor.<household>_account	Logged-in account (email)
sensor.<household>_creative_tonies	Number of Creative Tonies
sensor.<household>_tonieboxes	Number of Tonieboxes
sensor.<household>_children	Number of child profiles
sensor.<household>_members	Number of household members
sensor.<household>_notifications	Number of unread notifications
sensor.<household>_pending_invitations	Pending invitations
button.<household>_refresh_all	Reload all data from server

Per Toniebox

Entity	Description
media_player.<toniebox>	Current chapter, cover, progress and play/pause; on TNG also play/pause, next/previous, chapter browsing, volume and sleep (turn off)
sensor.<toniebox>_current_tonie	Currently placed figure (name)
sensor.<toniebox>_current_tonie_id	Currently placed figure (raw Tonie ID — useful as an automation trigger)
sensor.<toniebox>_settings_applied	Whether the latest settings have been transmitted
switch.<toniebox>_skip_chapters	Chapter skipping via tap on/off
switch.<toniebox>_scrubbing	Scrubbing by tilting on/off
switch.<toniebox>_offline_mode	Offline mode
switch.<toniebox>_tilt_and_tap	Accelerometer on/off (older boxes)
sensor.<toniebox>_firmware	Current firmware version
sensor.<toniebox>_last_seen	Timestamp of last connection
sensor.<toniebox>_online_status	API online status (connected / offline / unknown)
sensor.<toniebox>_current_battery	Live battery level — unknown when offline (TNG only)
sensor.<toniebox>_current_battery_status	Live charging status — unknown when offline (TNG only)
sensor.<toniebox>_last_battery	Last known battery level while online (TNG only)
sensor.<toniebox>_last_battery_status	Last known charging status while online (TNG only)
sensor.<toniebox>_last_online	Timestamp of last cloud connection (TNG only)
sensor.<toniebox>_generation	Model generation (classic / rosered / tng)
sensor.<toniebox>_features	Supported features
sensor.<toniebox>_timezone	Configured timezone
sensor.<toniebox>_setup_wifi	SSID of setup network
sensor.<toniebox>_added_at	Registration date
sensor.<toniebox>_bedtime_color	Night light color (tng)
binary_sensor.<toniebox>_online	Toniebox recently active (reachability)
binary_sensor.<toniebox>_led_active	LED status
binary_sensor.<toniebox>_charging	Currently charging — unknown when offline (TNG only)
binary_sensor.<toniebox>_sleeptimer_active	Whether a sleep timer is running; sleep_until attribute shows when the box will sleep, alarm the armed alarm (TNG only)
sensor.<toniebox>_next_alarm	Next wake-up of the enabled bedtime schedules; schedule attribute is the schedule it belongs to, schedules lists them all (TNG only)
switch.<toniebox>_<schedule>	One per bedtime schedule, turns it on/off (TNG only)
select.<toniebox>_led_level	LED brightness
select.<toniebox>_language	Language setting
select.<toniebox>_tap_direction	Tap direction
select.<toniebox>_age_mode	Age mode
number.<toniebox>_max_volume	Maximum volume
number.<toniebox>_lightring_brightness	Light ring brightness
button.<toniebox>_refresh	Reload device
button.<toniebox>_factory_reset	Reset settings

Per Creative Tonie

Entity	Description
media_player.<tonie>	Main entity with cover image and chapter overview
sensor.<tonie>_chapters	Number of chapters (incl. chapter list as attribute)
sensor.<tonie>_total_duration	Total playback duration in minutes
sensor.<tonie>_remaining_time	Remaining free capacity in minutes (max. 90 min)
sensor.<tonie>_transcoding	Transcoding status
switch.<tonie>_private	Hide Tonie from guest members
switch.<tonie>_live	Enable live mode
switch.<tonie>_shuffle_on_swap	Local only — when on, this Tonie's chapters are shuffled once it is replaced on a box by a different Tonie
binary_sensor.<tonie>_transcoding	Transcoding in progress
binary_sensor.<tonie>_live	Live status
binary_sensor.<tonie>_private	Private status
button.<tonie>_clear_chapters	Remove all chapters
button.<tonie>_sort_by_title	Sort chapters alphabetically
button.<tonie>_sort_by_filename	Sort chapters by filename
button.<tonie>_sort_by_date	Sort chapters by date
button.<tonie>_shuffle_chapters	Shuffle chapters into a random order
button.<tonie>_refresh	Reload Tonie data

Shuffle on swap (switch.<tonie>_shuffle_on_swap) is a local convenience toggle with no counterpart in the Tonie Cloud:

• Only a displacement counts: the shuffle fires for the Tonie that gets replaced on a box by a different Tonie. Simply lifting a Tonie off (box goes empty) never shuffles it, so you can pick it up and put it back later to keep listening where you left off.
• Only Creative Tonies with ≥ 2 chapters are shuffled.
• Each shuffle triggers a full re-transcode on the Tonie Cloud (typically 1–60 s) — expected, not an error.
• Real-time on the Toniebox 2 (TNG) via the cloud's push channel; on classic (non-TNG) boxes there is currently no placement data source to detect a swap from, so this only works on TNG.

---

Services

toniebox.sort_chapters — Sort Chapters

service: toniebox.sort_chapters
data:
  entity_id: media_player.my_tonie
  sort_by: title   # title | filename | date | random

random shuffles the chapters into a new random order. Like every reorder, it triggers a full re-transcode of the Tonie on the Tonie Cloud (typically 1–60 s). Needs at least 2 chapters.

toniebox.clear_chapters — Clear All Chapters

service: toniebox.clear_chapters
data:
  entity_id: media_player.my_tonie

toniebox.remove_chapter — Remove a Single Chapter

service: toniebox.remove_chapter
data:
  entity_id: media_player.my_tonie
  chapter_id: "abc123"

Chapter IDs are available as the chapters attribute on the media player or chapter sensor.

toniebox.move_chapter — Move Chapter

service: toniebox.move_chapter
data:
  entity_id: media_player.my_tonie
  chapter_id: "abc123"
  direction: up   # up | down

toniebox.upload_audio — Upload Audio

service: toniebox.upload_audio
data:
  entity_id: media_player.my_tonie
  file_path: /config/tonie_audio/story.mp3
  title: "My Story"   # optional

Supported formats: mp3, ogg, wav, flac, m4a, aac, opus.

toniebox.rename_tonie — Rename Tonie

service: toniebox.rename_tonie
data:
  entity_id: media_player.my_tonie
  name: "Bedtime Tonie"

toniebox.rename_toniebox — Rename Toniebox

service: toniebox.rename_toniebox
data:
  entity_id: media_player.my_toniebox
  name: "Kids Room"

toniebox.sleeptimer — Sleep Timer (Toniebox 2 / TNG only)

Start a sleep timer: the box falls asleep on its own after the given number of minutes. Pass 0 to cancel a running timer.

service: toniebox.sleeptimer
data:
  entity_id: media_player.my_toniebox
  minutes: 30   # 0 = cancel the running timer

Setting a timer has no immediate visible effect — the box keeps playing and sleeps later. Watch binary_sensor.<toniebox>_sleeptimer_active (attribute sleep_until) to confirm it is running.

The alarm that fires at the end of the timer is part of the same command and has to be requested explicitly — without it the box only falls asleep and never wakes up on its own:

service: toniebox.sleeptimer
data:
  entity_id: media_player.my_toniebox
  minutes: 480            # maximum 1092, see below
  one_time_alarm: true    # a one-time alarm has to be armed again every night
  alarm:
    tone: "alarmLoop1.opus"
    volume: 100
    morning_light: true

The duration is stored as a 16-bit value in seconds on the box, so 1092 minutes is the maximum; a larger value wraps silently (1093 min is applied as 44 s). The alarm fires when the timer ends, not at a fixed clock time — a fixed wake-up time means arming a timer that ends at that time.

toniebox.set_bedtime_schedule / toniebox.delete_bedtime_schedule — Bedtime Schedules (TNG only)

The recurring schedules from the tonies app. Without schedule_id a new one is created, with it only the given fields are changed:

service: toniebox.set_bedtime_schedule
data:
  entity_id: media_player.my_toniebox
  name: School days
  sleep_time: "19:00"
  wakeup_time: "06:40"
  days: [monday, tuesday, wednesday, thursday, friday]
  enabled: true
  alarm_enabled: true
  alarm_tone: "alarmLoop1.opus"
  alarm_volume: 50
  alarm_morning_light: false

A schedule alone does not make the box ring — the alarm still has to be armed each evening with toniebox.sleeptimer (see the weekday alarm example below).

toniebox.redeem_content_token — Redeem Content Token

service: toniebox.redeem_content_token
data:
  entity_id: media_player.my_tonie
  token: "TOKEN123"

toniebox.apply_tune — Apply Tune to Tonie

service: toniebox.apply_tune
data:
  entity_id: media_player.my_tonie
  tune_id: "tune-id-xyz"

toniebox.remove_tune — Remove Tune (Restore Original)

service: toniebox.remove_tune
data:
  entity_id: media_player.my_tonie

toniebox.redeem_voucher — Redeem Voucher Code

service: toniebox.redeem_voucher
data:
  code: "VOUCHER123"

toniebox.dismiss_all_notifications — Dismiss All Notifications

service: toniebox.dismiss_all_notifications

toniebox.accept_invitation / toniebox.decline_invitation — Accept/Decline Invitation

service: toniebox.accept_invitation
data:
  invitation_id: "invitation-id"

---

Automation Examples

Turn on light when favourite Tonie is placed

automation:
  trigger:
    - platform: state
      entity_id: binary_sensor.benjamin_bear_currently_active
      to: "on"
  action:
    - service: light.turn_on
      target:
        entity_id: light.kids_room

Automatic sleep timer for a specific figure (TNG)

Start a 60-minute sleep timer when a bedtime figure is placed, and cancel it when it is removed (uses the current_tonie_id sensor and sleeptimer action):

automation:
  alias: Toniebox - automatic sleep timer
  triggers:
    - trigger: state
      entity_id: sensor.toniebox_current_tonie_id
      to: "6B6A3428500304E0"          # bedtime figure -> start timer
      id: figure_placed
    - trigger: state
      entity_id: sensor.toniebox_current_tonie_id
      from: "6B6A3428500304E0"        # removed -> cancel timer
      id: figure_removed
  actions:
    - choose:
        - conditions: [{ condition: trigger, id: figure_placed }]
          sequence:
            - action: toniebox.sleeptimer
              data: { entity_id: media_player.toniebox, minutes: 60 }
        - conditions: [{ condition: trigger, id: figure_removed }]
          sequence:
            - action: toniebox.sleeptimer
              data: { entity_id: media_player.toniebox, minutes: 0 }

Weekday alarm from a bedtime schedule (TNG)

The box only accepts the alarm while it is online, so arm it each evening when it comes online, using the next wake-up from the next_alarm sensor:

automation:
  alias: Toniebox - arm alarm
  triggers:
    - trigger: state
      entity_id: binary_sensor.toniebox_online
      from: "off"
      to: "on"
  conditions:
    - "{{ states('sensor.toniebox_next_alarm') not in ['unknown', 'unavailable'] }}"
  actions:
    - delay: "00:00:30"   # the box ignores commands right after coming online
    - variables:
        s: "{{ state_attr('sensor.toniebox_next_alarm', 'schedule') }}"
    - action: toniebox.sleeptimer
      data:
        entity_id: media_player.toniebox
        minutes: >
          {{ ((as_datetime(states('sensor.toniebox_next_alarm')) - now())
              .total_seconds() / 60) | round(0, 'ceil') | int }}
        one_time_alarm: true
        alarm:
          tone: "{{ s.alarmTone }}"
          volume: "{{ s.alarmVolume }}"
          morning_light: "{{ s.alarmMorningLight }}"

Volume 100% during the day, reduced to 50% at night

automation:
  - alias: "Toniebox Volume Day"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: number.set_value
        target:
          entity_id: number.kids_room_max_volume
        data:
          value: 100

  - alias: "Toniebox Volume Night"
    trigger:
      - platform: time
        at: "20:00:00"
    action:
      - service: number.set_value
        target:
          entity_id: number.kids_room_max_volume
        data:
          value: 50

Notification when Toniebox goes offline

automation:
  trigger:
    - platform: state
      entity_id: binary_sensor.kids_room_online
      to: "off"
      for: "00:05:00"
  action:
    - service: notify.mobile_app
      data:
        message: "Toniebox Kids Room has been offline for 5 minutes."

---

Dashboard Example

type: vertical-stack
cards:
  - type: picture-entity
    entity: media_player.my_toniebox
    show_name: true
    show_state: true
  - type: entities
    title: Creative Tonie
    entities:
      - sensor.my_tonie_chapters
      - sensor.my_tonie_total_duration
      - sensor.my_tonie_remaining_time
      - select.my_tonie_sort_chapters
  - type: horizontal-stack
    cards:
      - type: button
        entity: button.my_tonie_clear_chapters
        name: "Clear"
      - type: button
        entity: button.my_tonie_sort_by_title
        name: "A–Z"
      - type: button
        entity: button.my_tonie_refresh
        name: "Refresh"

---

Debug Logging

logger:
  default: info
  logs:
    custom_components.toniebox: debug

Or via Settings → Devices & Services → Toniebox → Enable debug logging.

Tip

Debug logs are especially helpful when Creative Tonies or Tonieboxes are not displayed correctly — they show the exact API response fields and help diagnose parsing issues.

---

🤖 About Vibecoding

This integration was developed with AI pair programming (Claude by Anthropic). Architecture, authentication flow and all platforms were built iteratively with AI assistance and tested against a real Toniebox account.

That means: it works — but edge cases may occur. PRs, bug reports and improvements are very welcome!

---

Sources & Attribution

Source	License	Usage
Wilhelmsson177/tonie-api	MIT	API endpoint research, Python concepts
maximilianvoss/toniebox-api	Apache-2.0	Concrete API URLs from Constants.java
toniebox-reverse-engineering/teddycloud	GPL-3.0	Keycloak SSO flow documentation
api.tonie.cloud/v2/doc	—	Official REST API documentation

The endpoints used are part of the official Tonie Cloud API. No DRM protections or access controls are bypassed. The integration uses the same API as the official app.

---

Legal

• Published under the MIT License
• Not affiliated with Boxine GmbH
• Toniebox® and Tonies® are registered trademarks of Boxine GmbH
• Use in accordance with Boxine's Terms of Service

---

🇩🇪 Deutsch

Features

• 🧸 Jede Creative Tonie als eigenes Gerät mit Media Player, Cover-Bild und Kapitelliste
• 📻 Jede Toniebox als eigenes Gerät — zeigt die aktuell aufgelegte Figur mit Name und Cover
• ▶️ Volle Wiedergabesteuerung bei der Toniebox 2 (TNG) — Play/Pause, Kapitel vor/zurück, zu beliebigem Kapitel springen (Browse), Lautstärke und Schlafenlegen — live über den Echtzeit-Kanal der Tonie Cloud
• 🎚️ Live „Now Playing" — aktueller Kapiteltitel, Fortschrittsbalken und Play/Pause-Status
• ⏲️ Schlaftimer — per Action toniebox.sleeptimer starten, mit Binary-Sensor sleeptimer_active und dem Wecker, der am Ende des Timers losgeht
• ⏰ Wecker an Wochentagen — die wiederkehrenden Schlafenszeiten der tonies-App verwalten, mit Sensor nachster_wecker und einem Schalter pro Zeitplan
• 📊 Sensoren für Kapitelanzahl, Gesamtdauer, Firmware-Version, Online-Status, Batteriestand, aktive Figur und Figur-ID
• 🔘 Buttons zum Sortieren (Titel / Dateiname / Datum), Mischen, Leeren und Aktualisieren
• 🔀 Mischen der Kapitelreihenfolge auf Wunsch (sort_chapters mit sort_by: random) oder automatisch beim Wechsel — ein Schalter pro Creative Tonie, der einen Tonie neu mischt, sobald er auf einer Box durch einen anderen ersetzt wird
• 🔴 Binary Sensors für Transcoding, Live-Modus, Haushalt-Lock, aktive Figur und laufenden Schlaftimer
• 🎛️ Switches für LED, Kapitel-Überspringen, Scrubbing, Offline-Modus, Haushalt-Sperren
• 🌐 Select-Entities für Sprache, LED-Level, Tap-Richtung, Alters-Modus
• ⚙️ Services für Automationen: Schlaftimer, sortieren, löschen, umbenennen, Tune aufspielen, Gutschein einlösen u.v.m.
• 🌍 Übersetzungen für Deutsch, Englisch, Französisch, Spanisch und Italienisch
• 🔐 Keycloak OpenID Connect Authentifizierung — selbe Zugangsdaten wie die Toniebox App
• 🛠️ Config Flow Setup — kein YAML erforderlich
• 📦 Installierbar über den Home Assistant Marketplace / HACS

---

Installation über Marketplace / HACS

Ab Home Assistant 2026.11 ist der Marketplace (Nachfolger von HACS) eingebaut: Einstellungen → Marketplace öffnen, nach Toniebox suchen und herunterladen. Falls die Integration nicht gelistet ist, https://github.com/git4sim/HA-Toniebox als benutzerdefiniertes Repository vom Typ Integration hinzufügen.

Home Assistant 2026.3 bis 2026.10 mit installiertem HACS:

Note

Falls der Button nicht funktioniert: https://github.com/git4sim/HA-Toniebox in HACS manuell als Custom Repository vom Typ Integration hinzufügen, nach Toniebox suchen und herunterladen.

Nach dem Download Home Assistant neu starten.

Manuelle Installation

Den Ordner custom_components/toniebox/ aus dem neuesten Release in das HA-Konfigurationsverzeichnis kopieren:

/config/custom_components/toniebox/

Home Assistant neu starten.

---

Einrichtung

Note

Falls der Button nicht funktioniert: Einstellungen → Geräte & Dienste → Integration hinzufügen und nach Toniebox suchen.

E-Mail-Adresse und Passwort des Toniebox-Kontos eingeben (dieselben Zugangsdaten wie in der Toniebox App oder auf my.tonies.com).

---

Gerätehierarchie

Die Integration erstellt eine logische Gerätehierarchie in Home Assistant:

Haushalt (Hub)
├── Toniebox 1       →  Media Player · Switches · Sensoren · Buttons · Select
├── Toniebox 2       →  ...
├── Creative Tonie A →  Media Player · Kapitel · Dauer · Sort/Clear Buttons · Live/Privat Switch
└── Creative Tonie B →  ...

Jedes Gerät erscheint unter Einstellungen → Geräte & Dienste → Toniebox mit seinen eigenen Entities.

---

Entities

Haushalt (Hub-Gerät)

Entity	Beschreibung
sensor.<haushalt>_account	Angemeldetes Konto (E-Mail)
sensor.<haushalt>_creative_tonies	Anzahl Creative Tonies
sensor.<haushalt>_tonieboxen	Anzahl Tonieboxen
sensor.<haushalt>_kinder	Anzahl Kinder-Profile
sensor.<haushalt>_mitglieder	Anzahl Haushaltsmitglieder
sensor.<haushalt>_benachrichtigungen	Anzahl ungelesener Benachrichtigungen
sensor.<haushalt>_offene_einladungen	Ausstehende Einladungen
button.<haushalt>_alle_aktualisieren	Alle Daten vom Server neu laden

Pro Toniebox

Entity	Beschreibung
media_player.<toniebox>	Aktuelles Kapitel, Cover, Fortschritt und Play/Pause; bei TNG zusätzlich Play/Pause, Kapitel vor/zurück, Kapitel-Browse, Lautstärke und Schlafenlegen
sensor.<toniebox>_aktuelle_figur	Aktuell aufgelegte Figur (Name)
sensor.<toniebox>_aktuelle_figur_id	Aktuell aufgelegte Figur (rohe Tonie-ID — praktisch als Automations-Trigger)
sensor.<toniebox>_einstellungen_uebertragen	Ob die aktuellen Einstellungen übertragen wurden
switch.<toniebox>_kapitel_ueberspringen	Kapitel-Überspringen per Tippen ein/aus
switch.<toniebox>_vorspulen_zurueckspulen	Scrubbing durch Kippen ein/aus
switch.<toniebox>_offline_modus	Offline-Modus
switch.<toniebox>_kippen_und_klopfen	Beschleunigungssensor ein/aus (ältere Boxen)
sensor.<toniebox>_firmware	Aktuelle Firmware-Version
sensor.<toniebox>_zuletzt_gesehen	Zeitstempel der letzten Verbindung
sensor.<toniebox>_online_status	API Online-Status (connected / offline / unknown)
sensor.<toniebox>_aktuelle_batterie	Live-Ladestand — Unbekannt wenn offline (nur TNG)
sensor.<toniebox>_aktueller_batteriestatus	Live-Ladestatus — Unbekannt wenn offline (nur TNG)
sensor.<toniebox>_letzte_batterie	Letzter bekannter Ladestand im Online-Zustand (nur TNG)
sensor.<toniebox>_letzter_batteriestatus	Letzter bekannter Ladestatus im Online-Zustand (nur TNG)
sensor.<toniebox>_zuletzt_online	Zeitstempel der letzten Cloud-Verbindung (nur TNG)
sensor.<toniebox>_generation	Modell-Generation (classic / rosered / tng)
sensor.<toniebox>_features	Unterstützte Funktionen
sensor.<toniebox>_zeitzone	Konfigurierte Zeitzone
sensor.<toniebox>_setup_wlan	WLAN-SSID des Setup-Netzwerks
sensor.<toniebox>_hinzugefuegt_am	Registrierungsdatum
sensor.<toniebox>_schlafenszeit_farbe	Nachtlicht-Farbe (tng)
binary_sensor.<toniebox>_online	Toniebox zuletzt aktiv (Erreichbarkeit)
binary_sensor.<toniebox>_led_aktiv	LED-Status
binary_sensor.<toniebox>_wird_geladen	Wird gerade geladen — Unbekannt wenn offline (nur TNG)
binary_sensor.<toniebox>_schlaftimer_aktiv	Ob ein Schlaftimer läuft; Attribut sleep_until zeigt die Einschlaf-Uhrzeit, alarm den gestellten Wecker (nur TNG)
sensor.<toniebox>_nachster_wecker	Nächste Weckzeit der aktiven Schlafenszeiten; Attribut schedule ist der zugehörige Zeitplan, schedules listet alle (nur TNG)
switch.<toniebox>_<zeitplan>	Einer pro Schlafenszeit, schaltet sie ein/aus (nur TNG)
select.<toniebox>_led_level	LED-Helligkeit
select.<toniebox>_sprache	Spracheinstellung
select.<toniebox>_tap_richtung	Tipp-Richtung
select.<toniebox>_alters_modus	Alters-Modus
number.<toniebox>_max_lautstaerke	Maximale Lautstärke
number.<toniebox>_lightring_helligkeit	Lichtring-Helligkeit
button.<toniebox>_aktualisieren	Gerät neu laden
button.<toniebox>_werkseinstellungen	Einstellungen zurücksetzen

Pro Creative Tonie

Entity	Beschreibung
media_player.<tonie>	Hauptentität mit Cover-Bild und Kapitelübersicht
sensor.<tonie>_kapitel	Anzahl Kapitel (inkl. Kapitelliste als Attribut)
sensor.<tonie>_gesamtdauer	Gesamtspieldauer in Minuten
sensor.<tonie>_freie_zeit	Verbleibende freie Kapazität in Minuten (max. 90 min)
sensor.<tonie>_transkodierung	Transkodierungs-Status
switch.<tonie>_privat	Tonie für Gastmitglieder ausblenden
switch.<tonie>_live	Live-Modus aktivieren
switch.<tonie>_shuffle_on_swap	Nur lokal — wenn aktiv, werden die Kapitel dieses Tonies gemischt, sobald er auf einer Box durch einen anderen Tonie ersetzt wird
binary_sensor.<tonie>_wird_verarbeitet	Transkodierung läuft
binary_sensor.<tonie>_live	Live-Status
binary_sensor.<tonie>_privat	Privat-Status
button.<tonie>_alle_kapitel_loeschen	Alle Kapitel entfernen
button.<tonie>_nach_titel_sortieren	Kapitel alphabetisch sortieren
button.<tonie>_nach_dateiname_sortieren	Kapitel nach Dateiname sortieren
button.<tonie>_nach_datum_sortieren	Kapitel nach Datum sortieren
button.<tonie>_kapitel_mischen	Kapitel in eine zufällige Reihenfolge mischen
button.<tonie>_aktualisieren	Tonie-Daten neu laden

Beim Wechsel mischen (switch.<tonie>_shuffle_on_swap) ist ein rein lokaler Schalter ohne Entsprechung in der Tonie Cloud:

• Nur die Verdrängung zählt: Gemischt wird der Tonie, der auf einer Box durch einen anderen Tonie ersetzt wird. Das bloße Abnehmen (Box wird leer) löst kein Mischen aus — so kannst du ihn abnehmen und später wieder auflegen, um weiterzuhören.
• Nur Kreativ-Tonies mit ≥ 2 Kapiteln werden gemischt.
• Jedes Mischen löst ein vollständiges Neu-Transkodieren in der Tonie Cloud aus (typisch 1–60 s) — das ist normal, kein Fehler.
• In Echtzeit auf der Toniebox 2 (TNG) über den Push-Kanal der Cloud; auf klassischen (Nicht-TNG) Boxen gibt es aktuell keine Placement-Datenquelle, um einen Wechsel zu erkennen — funktioniert daher nur auf TNG.

---

Services

toniebox.sort_chapters — Kapitel sortieren

service: toniebox.sort_chapters
data:
  entity_id: media_player.mein_tonie
  sort_by: title   # title | filename | date | random

random mischt die Kapitel in eine neue zufällige Reihenfolge. Wie jede Umsortierung löst das ein vollständiges Neu-Transkodieren des Tonies in der Tonie Cloud aus (typisch 1–60 s). Es werden mindestens 2 Kapitel benötigt.

toniebox.clear_chapters — Alle Kapitel löschen

service: toniebox.clear_chapters
data:
  entity_id: media_player.mein_tonie

toniebox.remove_chapter — Einzelnes Kapitel löschen

service: toniebox.remove_chapter
data:
  entity_id: media_player.mein_tonie
  chapter_id: "abc123"

Die Kapitel-IDs stehen als Attribut chapters am Media Player oder Kapitel-Sensor.

toniebox.move_chapter — Kapitel verschieben

service: toniebox.move_chapter
data:
  entity_id: media_player.mein_tonie
  chapter_id: "abc123"
  direction: up   # up | down

toniebox.upload_audio — Audio hochladen

service: toniebox.upload_audio
data:
  entity_id: media_player.mein_tonie
  file_path: /config/tonie_audio/geschichte.mp3
  title: "Meine Geschichte"   # optional

Unterstützte Formate: mp3, ogg, wav, flac, m4a, aac, opus.

toniebox.rename_tonie — Tonie umbenennen

service: toniebox.rename_tonie
data:
  entity_id: media_player.mein_tonie
  name: "Schlaf Tonie"

toniebox.rename_toniebox — Toniebox umbenennen

service: toniebox.rename_toniebox
data:
  entity_id: media_player.meine_toniebox
  name: "Kinderzimmer"

toniebox.sleeptimer — Schlaftimer (nur Toniebox 2 / TNG)

Startet einen Schlaftimer: Die Box schläft nach der angegebenen Minutenzahl von selbst ein. Mit 0 wird ein laufender Timer abgebrochen.

service: toniebox.sleeptimer
data:
  entity_id: media_player.meine_toniebox
  minutes: 30   # 0 = laufenden Timer abbrechen

Das Setzen eines Timers hat keinen sofort sichtbaren Effekt — die Box spielt weiter und schläft erst später ein. Zur Kontrolle binary_sensor.<toniebox>_schlaftimer_aktiv (Attribut sleep_until) beobachten.

Der Wecker, der am Ende des Timers losgeht, ist Teil desselben Befehls und muss explizit gesetzt werden — ohne ihn schläft die Box ein und wacht nie von selbst auf:

service: toniebox.sleeptimer
data:
  entity_id: media_player.meine_toniebox
  minutes: 480            # maximal 1092, siehe unten
  one_time_alarm: true    # ein Einmal-Wecker muss jeden Tag neu gesetzt werden
  alarm:
    tone: "alarmLoop1.opus"
    volume: 100
    morning_light: true

Die Dauer wird auf der Box als 16-Bit-Wert in Sekunden gespeichert, daher ist 1092 Minuten das Maximum; größere Werte laufen still um (1093 min werden als 44 s angewandt). Der Wecker fällt am Ende des Timers, nicht zu einer festen Uhrzeit — eine feste Aufstehzeit heißt, den Timer so zu setzen, dass er zu dieser Zeit endet.

toniebox.set_bedtime_schedule / toniebox.delete_bedtime_schedule — Schlafenszeiten (nur TNG)

Die wiederkehrenden Zeitpläne aus der tonies-App. Ohne schedule_id wird ein neuer angelegt, mit schedule_id werden nur die angegebenen Felder geändert:

service: toniebox.set_bedtime_schedule
data:
  entity_id: media_player.meine_toniebox
  name: Schultage
  sleep_time: "19:00"
  wakeup_time: "06:40"
  days: [monday, tuesday, wednesday, thursday, friday]
  enabled: true
  alarm_enabled: true
  alarm_tone: "alarmLoop1.opus"
  alarm_volume: 50
  alarm_morning_light: false

Ein Zeitplan allein lässt die Box nicht klingeln — der Wecker muss trotzdem jeden Abend mit toniebox.sleeptimer gestellt werden (siehe Wecker-Beispiel unten).

toniebox.redeem_content_token — Content Token einlösen

service: toniebox.redeem_content_token
data:
  entity_id: media_player.mein_tonie
  token: "TOKEN123"

toniebox.apply_tune — Tune auf Tonie aufspielen

service: toniebox.apply_tune
data:
  entity_id: media_player.mein_tonie
  tune_id: "tune-id-xyz"

toniebox.remove_tune — Tune entfernen (Original wiederherstellen)

service: toniebox.remove_tune
data:
  entity_id: media_player.mein_tonie

toniebox.redeem_voucher — Gutscheincode einlösen

service: toniebox.redeem_voucher
data:
  code: "GUTSCHEIN123"

toniebox.dismiss_all_notifications — Alle Benachrichtigungen löschen

service: toniebox.dismiss_all_notifications

toniebox.accept_invitation / toniebox.decline_invitation — Einladung annehmen/ablehnen

service: toniebox.accept_invitation
data:
  invitation_id: "einladungs-id"

---

Automations-Beispiele

Licht einschalten wenn Lieblings-Tonie aufgelegt wird

automation:
  trigger:
    - platform: state
      entity_id: binary_sensor.benjamin_bluemchen_gerade_aktiv
      to: "on"
  action:
    - service: light.turn_on
      target:
        entity_id: light.kinderzimmer

Automatischer Schlaftimer für eine bestimmte Figur (TNG)

Startet beim Auflegen einer Einschlaf-Figur einen 60-Minuten-Timer und bricht ihn beim Hochnehmen ab (nutzt den aktuelle_figur_id-Sensor und die sleeptimer-Action):

automation:
  alias: Toniebox - Automatischer Schlaftimer
  triggers:
    - trigger: state
      entity_id: sensor.toniebox_aktuelle_figur_id
      to: "6B6A3428500304E0"          # Einschlaf-Figur -> Timer starten
      id: figur_aufgelegt
    - trigger: state
      entity_id: sensor.toniebox_aktuelle_figur_id
      from: "6B6A3428500304E0"        # entfernt -> Timer abbrechen
      id: figur_entfernt
  actions:
    - choose:
        - conditions: [{ condition: trigger, id: figur_aufgelegt }]
          sequence:
            - action: toniebox.sleeptimer
              data: { entity_id: media_player.toniebox, minutes: 60 }
        - conditions: [{ condition: trigger, id: figur_entfernt }]
          sequence:
            - action: toniebox.sleeptimer
              data: { entity_id: media_player.toniebox, minutes: 0 }

Wecker an Wochentagen aus einer Schlafenszeit (TNG)

Die Box nimmt den Wecker nur an, solange sie online ist — also jeden Abend beim Online-Gehen stellen, mit der nächsten Weckzeit aus dem Sensor nachster_wecker:

automation:
  alias: Toniebox - Wecker stellen
  triggers:
    - trigger: state
      entity_id: binary_sensor.toniebox_online
      from: "off"
      to: "on"
  conditions:
    - "{{ states('sensor.toniebox_nachster_wecker') not in ['unknown', 'unavailable'] }}"
  actions:
    - delay: "00:00:30"   # direkt nach dem Online-Gehen ignoriert die Box Befehle
    - variables:
        s: "{{ state_attr('sensor.toniebox_nachster_wecker', 'schedule') }}"
    - action: toniebox.sleeptimer
      data:
        entity_id: media_player.toniebox
        minutes: >
          {{ ((as_datetime(states('sensor.toniebox_nachster_wecker')) - now())
              .total_seconds() / 60) | round(0, 'ceil') | int }}
        one_time_alarm: true
        alarm:
          tone: "{{ s.alarmTone }}"
          volume: "{{ s.alarmVolume }}"
          morning_light: "{{ s.alarmMorningLight }}"

Lautstärke tagsüber 100 %, nachts auf 50 % reduzieren

automation:
  - alias: "Toniebox Lautstärke Tag"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: number.set_value
        target:
          entity_id: number.kinderzimmer_max_lautstaerke
        data:
          value: 100

  - alias: "Toniebox Lautstärke Nacht"
    trigger:
      - platform: time
        at: "20:00:00"
    action:
      - service: number.set_value
        target:
          entity_id: number.kinderzimmer_max_lautstaerke
        data:
          value: 50

Benachrichtigung wenn Toniebox offline geht

automation:
  trigger:
    - platform: state
      entity_id: binary_sensor.kinderzimmer_online
      to: "off"
      for: "00:05:00"
  action:
    - service: notify.mobile_app
      data:
        message: "Toniebox Kinderzimmer ist seit 5 Minuten offline."

---

Dashboard-Beispiel

type: vertical-stack
cards:
  - type: picture-entity
    entity: media_player.meine_toniebox
    show_name: true
    show_state: true
  - type: entities
    title: Creative Tonie
    entities:
      - sensor.mein_tonie_kapitel
      - sensor.mein_tonie_gesamtdauer
      - sensor.mein_tonie_freie_zeit
      - select.mein_tonie_kapitel_sortieren
  - type: horizontal-stack
    cards:
      - type: button
        entity: button.mein_tonie_alle_kapitel_loeschen
        name: "Leeren"
      - type: button
        entity: button.mein_tonie_nach_titel_sortieren
        name: "A–Z"
      - type: button
        entity: button.mein_tonie_aktualisieren
        name: "Aktualisieren"

---

Debug Logging

logger:
  default: info
  logs:
    custom_components.toniebox: debug

Oder über Einstellungen → Geräte & Dienste → Toniebox → Debug-Protokollierung aktivieren.

Tip

Debug-Logs sind besonders hilfreich wenn Creative Tonies oder Tonieboxen nicht korrekt angezeigt werden — sie zeigen die exakten API-Antwortfelder und helfen beim Diagnosieren von Parsing-Problemen.

---

🤖 Über Vibecoding

Diese Integration wurde mit KI-Pair-Programming (Claude by Anthropic) entwickelt. Architektur, Authentifizierungsflow und alle Plattformen wurden iterativ mit KI-Unterstützung erstellt und gegen ein echtes Toniebox-Konto getestet.

Das bedeutet: Es funktioniert — aber Randfälle können vorkommen. PRs, Bug Reports und Verbesserungen sind herzlich willkommen!

---

Quellen & Attribution

Quelle	Lizenz	Verwendung
Wilhelmsson177/tonie-api	MIT	API-Endpoint-Recherche, Python-Konzept
maximilianvoss/toniebox-api	Apache-2.0	Konkrete API-URLs aus Constants.java
toniebox-reverse-engineering/teddycloud	GPL-3.0	Keycloak SSO Flow Dokumentation
api.tonie.cloud/v2/doc	—	Offizielle REST API Dokumentation

Die verwendeten Endpunkte sind Teil der offiziellen Tonie Cloud API. Es werden keine DRM-Schutzmaßnahmen oder Zugriffskontrollen umgangen. Die Integration nutzt dieselbe API wie die offizielle App.

---

Legal

• Veröffentlicht unter der MIT-Lizenz
• Nicht verbunden mit Boxine GmbH
• Toniebox® und Tonies® sind eingetragene Marken der Boxine GmbH
• Nutzung gemäß den Nutzungsbedingungen von Boxine

---

Made with 🧸 + 🤖 + ☕  |  Report a bug / Bug melden