Realtime: Ereignisse über WebSocket

Verbindungsparameter

Die Werte stammen aus der AsyncAPI, nicht aus Fließtext. Host, Port und Schema müssen manuell gesetzt werden: Es gibt keinen Pusher-Cloud-Cluster, der Server ist selbst betrieben.

Wie ein Abo autorisiert wird

Einen privaten Kanal kann man nicht einfach mithören. Die Client-Bibliothek durchläuft vier Schritte — und nur wer sie kennt, weiß, an welchem der 403 entstanden ist.

1. 1

   Der Socket wird geöffnet

   Der Client verbindet sich per App-Key mit dem Host. Ihr API-Schlüssel spielt hier noch keine Rolle — der Socket öffnet sich auch mit einem ungültigen Schlüssel.

2. 2

   socket_id trifft ein

   Der Server antwortet mit pusher:connection_established samt socket_id, die genau diese Verbindung identifiziert.

3. 3

   Das Abo wird signiert

   Der Client sendet socket_id und Kanalnamen per POST /broadcasting/auth mit dem Header X-API-KEY. Der Server prüft Schlüssel, Recht und Kanalzugehörigkeit und liefert eine Signatur. Genau hier entstehen 401, 403 und 429.

4. 4

   Abo bestätigt, Ereignisse fließen

   Der Client übergibt die Signatur, der Kanal bestätigt mit pusher:subscription_succeeded — erst danach treffen die Ereignisse des Kanals ein.

orders.readvoices.readreseller.read— die in Schritt drei geprüften Rechte: Jeder Kanal hat sein eigenes, siehe Kanaltabelle unten.

Verbindungs-Snippets

Drei Clients, dieselbe Abfolge. Der Schlüssel im Code ist ein Platzhalter: Setzen Sie Ihren ein, aber committen Sie ihn nicht.

import Pusher from 'pusher-js';

const pusher = new Pusher('7c4dd881d8116ac76fe89aff71d8c2ff', {
  wsHost: 'ws.lumean.app',
  wsPort: 443, wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
  cluster: '',
  channelAuthorization: {
    endpoint: 'https://api.lumean.app/api/public/broadcasting/auth',
    headers: { 'X-API-KEY': 'YOUR_API_KEY' },
  },
});

const channel = pusher.subscribe('private-orders.{userId}');
channel.bind('policy_cooldown.applied', (data) => {
  console.log(data);
});

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';
window.Pusher = Pusher;

const echo = new Echo({
  broadcaster: 'pusher',
  key: '7c4dd881d8116ac76fe89aff71d8c2ff',
  wsHost: 'ws.lumean.app',
  wsPort: 443, wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
  cluster: '',
  authEndpoint: 'https://api.lumean.app/api/public/broadcasting/auth',
  auth: { headers: { 'X-API-KEY': 'YOUR_API_KEY' } },
});

echo.private('orders.{userId}')
  // der führende Punkt gilt für Laravel Echo; pusher-js kennt ihn nicht
  .listen('.policy_cooldown.applied', (e) => {
    console.log(e);
  });

# pip install websocket-client requests
import json, requests, websocket

APP_KEY = "7c4dd881d8116ac76fe89aff71d8c2ff"
WS_URL  = "wss://ws.lumean.app:443/app/" + APP_KEY + "?protocol=7&client=python&version=1.0"
CHANNEL = "private-orders.{userId}"

ws = websocket.create_connection(WS_URL)
# 1. socket_id aus dem Ereignis pusher:connection_established holen
hello = json.loads(ws.recv())
socket_id = json.loads(hello["data"])["socket_id"]

# 2. privates Abo mit dem eigenen API-Schlüssel autorisieren
auth = requests.post("https://api.lumean.app/api/public/broadcasting/auth",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    data={"socket_id": socket_id, "channel_name": CHANNEL},
).json()["auth"]

# 3. abonnieren und Ereignisse empfangen
ws.send(json.dumps({"event": "pusher:subscribe",
    "data": {"auth": auth, "channel": CHANNEL}}))
while True:
    print(ws.recv())

Kanäle

Die Kanäle sind privat: Die Namen beginnen mit private-, den Parameter in geschweiften Klammern setzen Sie selbst ein. Jeder Kanal erfordert sein eigenes Recht — es steht in der Tabelle.

• WSprivate-orders.{userId}Events for every order of the account at once.14 Ereignisseorders.readKanal öffnen
• WSprivate-order.task.{orderId}Events for a single order. Someone else's order is out of reach: subscription auth returns `403`.8 Ereignisseorders.readKanal öffnen
• WSprivate-chunks.preview.{userId}The result of a background chunk-preview split calculation. Arrives for large texts submitted to `POST /orders/chunks/preview`.1 Ereignisseorders.readKanal öffnen
• WSprivate-cartesia-voice-clones.{userId}Progress of your Cartesia voice clones: one event per status change of a clone created via `POST /voices/cartesia/clones` (or in the web dashboard). Key permission: `voices.read`.1 Ereignissevoices.readKanal öffnen
• WSprivate-fishaudio-voice-clones.{userId}Progress of your Fish Audio voice clones: one event per status change of a clone created via `POST /voices/fishaudio/clones` (or in the web dashboard). Key permission: `voices.read`.1 Ereignissevoices.readKanal öffnen
• WSprivate-giftcodes.{userId}Gift codes and reseller status of the key owner: a batch issued, a code changing status, the reseller status and the reseller application changing. Events never carry code values, only masks; the full code comes from `GET /reseller/codes` and `GET /reseller/codes/{uuid}`. Key permission: `reseller.read`.4 Ereignissereseller.readKanal öffnen

Zwei Fallen

// private-orders.{userId} → .progress
{ "order_id": "…", "completed": 3, "total": 7, "percent": 43 }

// private-order.task.{orderId} → .progress
{ "task_id": "…", "progress": 43, "chunks_done": 3, "chunks_total": 7, "eta_seconds": 12 }

echo.private(channel).listen('.status.changed', handler)

channel.bind('status.changed', handler)

Autorisierungsfehler

Alle drei kommen als HTTP-Antwort auf POST /broadcasting/auth, nicht über den Socket. Der Socket ist zu diesem Zeitpunkt bereits offen — „verbunden“ sagt daher nichts über Ihre Rechte aus.

POST /broadcasting/auth

Dieser Endpunkt fehlt bewusst in der Referenz: Niemand ruft ihn von Hand auf, das erledigt die Client-Bibliothek. Wenn ein Abo aber 403 liefert, debuggen Sie genau diese Anfrage — deshalb steht sie hier.

Anfrage-Body

{
  "auth": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}

Authentifizierung und Rechte·Leitfaden: Realtime statt Polling