1. Vorbereitungen (TeamMessage.de)1. Preparations (TeamMessage.eu)

2. Installation & Einrichtung2. Installation & Setup

Nach der Installation (siehe Downloads) fügst du die Integration über Einstellungen -> Geräte & Dienste hinzu. Dort gibst du ID und Token ein. After installation (see Downloads), add the integration via Settings -> Devices & Services. There you enter the ID and Token.

Smarte Fallbacks (Optionen)Smart Fallbacks (Options)

Über den Button Konfigurieren in der Integrations-Übersicht kannst du diese Fallbacks definieren. Das erspart dir ständiges Tippen in den YAML-Automatisierungen! You can define these fallbacks via the Configure button in the integration overview. This saves you from constantly typing in YAML automations!

3. Das TeamMessage Panel im Detail3. The TeamMessage Panel

Die Integration fügt deinem Home Assistant in der linken Seitenleiste ein neues Menü namens TeamMessage hinzu. Dieses hochmoderne "Glassmorphism"-Panel ist in 5 Tabs unterteilt: The integration adds a new menu called TeamMessage to the left sidebar of your Home Assistant. This modern "Glassmorphism" panel is divided into 5 tabs:

• Dashboard: Anzeige von Guthaben (Prepaid), historisch gesendeten Nachrichten und deinem Tarifmodell.Display of credits (prepaid), historically sent messages, and your tariff model.
• SendenSend: Ideal, um Nachrichten manuell zu testen, ohne erst eine Automatisierung schreiben zu müssen. Formular für Direkt- oder Gruppenversand.Ideal for testing messages manually without having to write an automation first. Form for direct or group sending.
• LogbuchLogbook: Das Herzstück der Fehleranalyse. Live-Anzeige von Zustellstatus (Haken, Sanduhr, Fehler), Filterfunktion und Auto-Refresh.The core of error analysis. Live display of delivery status (check, hourglass, error), filter function and auto-refresh.
• KontakteContacts: Verwalte die Mitglieder deiner Teamlisten direkt aus Home Assistant heraus! Du kannst Kontakte laden, erstellen, bearbeiten und löschen.Manage the members of your team lists directly from Home Assistant! You can load, create, edit and delete contacts.
• EinstellungenSettings: Hier kannst du die Smarten Fallbacks bequem über die grafische Oberfläche ändern.Here you can easily change the Smart Fallbacks via the graphical interface.

4. Nutzung in Automatisierungen4. Usage in Automations

Sende Alarme über den Dienst:Send alarms via the service: sno_teammessage.send_message.
Hier sind alle 13 verfügbaren Parameter:Here are all 13 available parameters:

Vollumfängliche YAML BeispieleComprehensive YAML Examples

alias: "Alarm: Wasserschaden SMS"
trigger:
  - platform: state
    entity_id: binary_sensor.wassersensor_keller
    to: "on"
action:
  - action: sno_teammessage.send_message
    data:
      target_type: "direct"
      to_mobile: "+4915112345678"
      channel: "sms"
      message: "🚨 ALARM: Der Wassersensor im Keller hat Wasser registriert!"
      from_mobile: "HomeAssist"
      ucs2: true

alias: "Alarm: Einbruch Voice Call"
trigger:
  - platform: state
    entity_id: binary_sensor.haustur_kontakt
    to: "on"
condition:
  - condition: time
    after: "23:00:00"
    before: "06:00:00"
action:
  - action: sno_teammessage.send_message
    data:
      target_type: "direct"
      to_mobile: "+4915187654321"
      channel: "voice"
      message: "Achtung. Kritische Systemwarnung. Die Haustür wurde soeben geöffnet."

alias: "Info: System offline an Team"
trigger:
  - platform: state
    entity_id: binary_sensor.server_status
    to: "off"
    for:
      minutes: 5
action:
  - action: sno_teammessage.send_message
    data:
      target_type: "list"
      teamlist_email: "98765"
      message: "SERVER OFFLINE: Der Hauptserver ist seit 5 Minuten nicht erreichbar."
      keyword: "Sicher123!"
      sender_email: "admin@beispiel.de"

alias: "Info: Waschmaschine (Planung)"
trigger:
  - platform: state
    entity_id: sensor.waschmaschine_status
    to: "Fertig"
action:
  - action: sno_teammessage.send_message
    data:
      target_type: "direct"
      to_mobile: "+4915112345678"
      message: "Die Waschmaschine ist fertig und kann ausgeräumt werden."
      flash: true
      time: "16:00"

1. Systemarchitektur & Kernkomponenten1. System Architecture & Core Components

• api.py (API Client): Asynchroner HTTP-Wrapper (aiohttp). Verwaltet Token & Auto-Heal-Mechanismus für unvollständige PUT-Anfragen.Asynchronous HTTP wrapper (aiohttp). Manages token & auto-heal mechanism for incomplete PUT requests.
• services.py (Service Layer): Beinhaltet die Geschäftslogik für den send_message-Dienst und den Smart Group Resolver.Contains the business logic for the send_message service and the Smart Group Resolver.
• views.py (Security Proxy): Ein HomeAssistantView. Fängt HTTP-Requests ab und leitet sie sicher an api.py weiter.A HomeAssistantView. Intercepts HTTP requests and securely forwards them to api.py.
• coordinator.py: Pollt zyklisch (alle 5 Min) Guthaben, Tarife und Logs für die Sensoren.Cyclically polls (every 5 min) credits, tariffs and logs for the sensors.
• webhook.py: Nimmt asynchrone POST-Requests entgegen und feuert Events.Receives asynchronous POST requests and fires events.

2. Der Smart Group ResolverThe Smart Group Resolver (services.py)

Die TeamMessage REST-API erlaubt nativ keinen Blind-Broadcast an Listen-IDs auf dem SMS-Endpunkt. Sie verlangt immer physische Handynummern in to_mobile. Der Resolver mappt dies: The TeamMessage REST API natively does not allow blind broadcasts to list IDs on the SMS endpoint. It always requires physical mobile numbers in to_mobile. The resolver maps this:

1. Der Nutzer übergibt in HA eine teamlist_email.The user passes a teamlist_email in HA.
2. Der Service ruft await client.get_teamlist_members() asynchron ab.The service retrieves await client.get_teamlist_members() asynchronously.
3. Die Liste wird iteriert. Nur Kontakte mit mb_contacttype == sms/voice werden akzeptiert.The list is iterated. Only contacts with mb_contacttype == sms/voice are accepted.
4. Fehlende Ländervorwahlen werden durch format_phone_number() korrigiert (+49).Missing country codes are corrected by format_phone_number() (+49).
5. Die Liste wird als String verknüpft (",".join(mobile_numbers)) und als to_mobile an die API gesendet.The list is concatenated as a string (",".join(mobile_numbers)) and sent as to_mobile to the API.

3. Auto-Heal & Pydantic Validierung (api.py)

Die TeamMessage API verwendet Pydantic. Fehlt beim Aktualisieren von Kontakten (PUT) das Feld mb, wirft die API einen 422 Error. The TeamMessage API uses Pydantic. If the mb field is missing when updating contacts (PUT), the API throws a 422 error.

# Auto-Heal in api.py
if method.upper() == "PUT" and "/contacts/" in url:
    if "data" not in payload: payload["data"] = {}
    try:
        contact_id = payload["data"].get("id", url.split("/")[-1])
        existing = await self._request("GET", f"/contacts/{contact_id}")
        if existing and "data" in existing:
            # Fülle fehlende Felder auf, um 422 zu vermeiden / Fill missing fields to avoid 422
            for key in ["mb", "name", "channel"]:
                if key not in payload["data"] or not payload["data"][key]:
                    if key in existing["data"]:
                        payload["data"][key] = existing["data"][key]
    except Exception as e:
        _LOGGER.warning(f"Auto-heal failed: {e}")

4. Dynamisches URL-RoutingDynamic URL Routing

Um hardcodierte URLs zu vermeiden, leitet die API-Klasse Endpunkte aus der const.py ab. Beim Auflösen von Gruppen wird der SMS-Endpunkt dynamisch umgeschrieben: To avoid hardcoded URLs, the API class derives endpoints from const.py. When resolving groups, the SMS endpoint is rewritten dynamically:

async def get_teamlist_members(self, list_target: Any) -> Dict[str, Any]:
    # Transformation: /sms/send/ -> /teamlist/members/
    url = ENDPOINT_SMS_SEND.replace("sms/send/", "teamlist/members/")
    # ... Request ausführen / execute request

5. Event-Bus & Webhooks (Inbound)Event Bus & Webhooks (Inbound)

Schlägt ein Request auf dem Webhook (/api/webhook/sno_teammessage_12345) auf, feuert Home Assistant das Event sno_teammessage_incoming auf dem internen Event-Bus. If a request hits the webhook (/api/webhook/sno_teammessage_12345), Home Assistant fires the event sno_teammessage_incoming on the internal event bus.

trigger:
  - platform: event
    event_type: sno_teammessage_incoming
action:
  - action: notify.mobile_app
    data:
      message: "Webhook empfangen! / Webhook received! Daten: {{ trigger.event.data.payload }}"

6. Error Handling (API Map)

Die API liefert negative Integer-Codes. Die const.py mappt diese auf standardisierte String-Schlüssel für lokalisierte Exceptions in HA. The API returns negative integer codes. The const.py maps these to standardized string keys for localized exceptions in HA.

• -1 -> invalid_team_id
• -2 -> invalid_teamlist_email
• -5 -> invalid_message
• -6 -> invalid_to_mobile
• -10 -> account_not_found
• -13 -> rate_limit_exceeded (Drosselt Polling)(Throttles polling)
• -14 -> closed_group_auth

1. Karten im Dashboard platzieren1. Placing Cards in the Dashboard

Nachdem du die Datei teammessage-cards.js als Ressource hinzugefügt hast (siehe Downloads), kannst du die Karten nutzen. After adding the teammessage-cards.js file as a resource (see Downloads), you can use the cards.

1. Navigiere zu deinem gewünschten Dashboard.Navigate to your desired dashboard.
2. Klicke oben rechts auf den Stift (Dashboard bearbeiten).Click on the Pencil (Edit Dashboard) in the top right corner.
3. Klicke auf Karte hinzufügen und suche nach TeamMessage.Click on Add Card and search for TeamMessage.
4. Wähle die Karte. Im visuellen Editor trägst du zwingend deine Team-ID (tm) ein!Select the card. In the visual editor, you must enter your Team-ID (tm)!

2. Die 4 Custom Cards im Detail2. The 4 Custom Cards in Detail

3. Hybrides Einstellungs-System (Theming)3. Hybrid Setting System (Theming)

Die Karten unterstützen 5 Modi: Classic, Minimal, Glass, Dark und Neon. The cards support 5 modes: Classic, Minimal, Glass, Dark and Neon.

1. Architektur & Sicherheitskonzept1. Architecture & Security Concept

Um höchste Sicherheitsstandards einzuhalten und CORS-Probleme zu vermeiden, dürfen Dashboard-Karten niemals direkt mit der externen API kommunizieren. In order to maintain the highest security standards and avoid CORS issues, dashboard cards must never communicate directly with the external API.

• Schreiben / Aktionen:Writing / Actions: Erfolgen ausschließlich über das Home Assistant Dienst-System (sno_teammessage.send_message).Are executed exclusively via the Home Assistant service system (sno_teammessage.send_message).
• Lesen / Datenabruf:Reading / Data Retrieval: Erfolgen über den in der Integration implementierten Reverse-Proxy, der serverseitig die Authentifizierung sicher abwickelt.Are executed via the reverse proxy implemented in the integration, which securely handles authentication on the server side.

2. Daten abrufen via Reverse-Proxy2. Fetching Data via Reverse Proxy

Der Proxy (views.py) nimmt Requests an. Kapsele diesen Aufruf in deiner Custom Card mit hass.callApi: The proxy (views.py) accepts requests. Encapsulate this call in your custom card with hass.callApi:

async function fetchTMApi(hass, endpoint) {
    try {
        const data = await hass.callApi(
            'GET', 
            `sno_teammessage/proxy?endpoint=${encodeURIComponent(endpoint)}`
        );
        return { data };
    } catch (e) {
        return { error: `Proxy HTTP ${e.status_code || 'Unbekannt/Unknown'} (${e.message})` };
    }
}

// Beispiel: Logbuch abrufen (Status 0=Zugestellt, 1=Wird gesendet, 2=Fehler)
// Example: Fetch logbook (Status 0=Delivered, 1=Sending, 2=Error)
// const res = await fetchTMApi(this._hass, '/logging/sms/?start=0&quantity=5&tm=12345');

3. Aktionen ausführen (Service Call)3. Executing Actions (Service Call)

Das Versenden von Nachrichten erfolgt über hass.callService. Sending messages is done via hass.callService.

async sendAlert() {
    const payload = {
        message: "Achtung: Wassersensor hat ausgelöst! / Warning: Water sensor triggered!",
        teamlist_email: "admin@beispiel.de" 
    };

    try {
        await this._hass.callService('sno_teammessage', 'send_message', payload);
        console.log("Nachricht erfolgreich an Backend übergeben / Message successfully passed to backend");
    } catch (error) {
        console.error("Fehler beim Senden / Error while sending:", error.message);
    }
}

4. Das Hybride State-Management (localStorage)4. Hybrid State Management (localStorage)

Als Entwickler musst du sicherstellen, dass deine Karte Konfigurationen aus zwei Quellen korrekt zusammenführt (State Merging): Globale Config (HA Editor) und lokaler Override (Browser). As a developer, you must ensure that your card correctly merges configurations from two sources (State Merging): Global Config (HA Editor) and Local Override (Browser).

setConfig(config) {
    if (!config.tm) throw new Error("Team-ID (tm) ist erforderlich! / is required!");
    this.config = config;
    
    // 1. Eindeutiger Key / Unique Key
    const safeTitle = (config.title || 'default').replace(/[^a-zA-Z0-9]/g, '_');
    this.cardKey = `sno_tm_v2_${config.type}_${safeTitle}`;
    
    // 2. Lade lokale Daten / Load local data
    let local = {};
    try { local = JSON.parse(localStorage.getItem(this.cardKey)) || {}; } catch(e){}

    // 3. State Merging (Local hat Vorrang / Local takes precedence)
    this.state = {
        theme: local.theme ?? this.config.theme ?? 'classic',
        interval: local.interval ?? this.config.interval ?? 30000,
    };
}

5. Blueprint für Custom Cards (Vanilla JS)5. Blueprint for Custom Cards (Vanilla JS)

Nutze folgendes Boilerplate ohne externe Lit-Abhängigkeiten für maximale HA-Kompatibilität: Use the following boilerplate without external Lit dependencies for maximum HA compatibility:

class SNOTeamMessageCustomCard extends HTMLElement {
    static getConfigElement() { 
        return document.createElement("sno-teammessage-data-editor"); 
    }
    
    static getStubConfig() { 
        return { type: "custom:sno-teammessage-custom-card", title: "Meine Karte / My Card", tm: "" }; 
    }

    setConfig(config) {
        if (!config.tm) throw new Error("Team-ID fehlt! / missing!");
        this.config = config;
    }

    set hass(hass) {
        this._hass = hass;
        if (!this.querySelector('ha-card')) {
            this.innerHTML = `
                
                
                    
${this.config.title}
                    Aktion / Action
                
            `;
            this.querySelector('#btn').addEventListener('click', () => { /* callService */ });
        }
    }

    getCardSize() { return 3; }
}
customElements.define('sno-teammessage-custom-card', SNOTeamMessageCustomCard);

6. Guidelines & Best Practices6. Guidelines & Best Practices

• Design-Konstanten nutzen:Use Design Constants: Verwende zwingend HA-Variablen wie var(--primary-color), damit sich deine Karte ins Nutzer-Theme einfügt.It is mandatory to use HA variables like var(--primary-color) so that your card blends into the user theme.
• Caching:Caching: Nutze hass.callApi nur bei expliziter Nutzerinteraktion oder in angemessen kurzen Intervallen (z.B. alle 60 Sek für Log-Updates).Use hass.callApi only on explicit user interaction or in reasonably short intervals (e.g. every 60 sec for log updates).
• Lebenszyklus:Lifecycle: Beende Timer in der disconnectedCallback() Methode (z. B. clearInterval(this.timer)), um Memory Leaks zu vermeiden.Terminate timers in the disconnectedCallback() method (e.g. clearInterval(this.timer)) to avoid memory leaks.