Send Anfragen an die Owncast-API

Wir unterstützen derzeit die folgenden Aktionen, die Sie über Anfragen aus Ihrem Code durchführen können.

Ereignis	Endpunkt	Bereich
System-Chat-Nachricht	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
Standard-Chat-Nachricht	/api/integrations/chat/send	CAN_SEND_MESSAGES
Chat-Aktion	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
Chat-Nachricht entfernen	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
Chatverlauf abrufen	/api/integrations/chat	HAS_ADMIN_ACCESS
Getrennte Clients abrufen	/api/integrations/clients	HAS_ADMIN_ACCESS
Stream-Titel festlegen	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
Systemnachricht an den Client	/api/integrations/chat/system/client/{clientId}	CAN_SEND_SYSTEM_MESSAGES
Get server status	/api/integrations/status	HAS_ADMIN_ACCESS
Get a chat user's details	/api/integrations/moderation/chat/user/{userId}	HAS_ADMIN_ACCESS

Besuchen Sie die API-Dokumentation für jeden Endpunkt, um mehr über die erwarteten oder zurückgegebenen Werte zu erfahren.

Ihr Owncast-Server akzeptiert nur Aktionen von Anfragen mit einem gültigen Zugriffstoken. Befolgen Sie die folgenden Schritte, um ein Zugriffstoken zu erstellen.

1. Besuchen Sie /admin/access-tokens auf Ihrem Owncast-Server.
2. Klicken Sie auf Zugriffstoken erstellen.
3. Wählen Sie den Umfang der Berechtigungen aus, die Sie diesem Token geben möchten.
4. Speichern Sie dieses Zugriffstoken.

Ihr Code

Senden Sie einen authentifizierten POST mit Ihrem Zugriffstoken im Header Authorization und einem JSON-Body. Zum Beispiel, um eine System-Chat-Nachricht zu senden:

const res = await fetch("https://your.owncast.server/api/integrations/chat/system", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + YOUR_ACCESS_TOKEN,
  },
  body: JSON.stringify({ body: "this is a system chat message" }),
});

const result = await res.json();
// { "success": true, "message": "sent" }

Testen Sie das Senden von Chatnachrichten

Ändern Sie den folgenden curl-Befehl, um auf Ihre Server-URL zu verweisen, und verwenden Sie Ihr Authentifizierungstoken mit "Systemnachricht"-Zugriff. Es sendet eine Systemnachricht in Ihren Chat.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOURAUTHTOKEN" \
  -d '{"body": "I am a system message!"}' \
  https://your.owncast.server/api/integrations/chat/system

Eine erfolgreiche Anfrage gibt 200 mit einem JSON-Body zurück:

{ "success": true, "message": "sent" }

Umfänge

Jedes Zugriffstoken erhält einen oder mehrere Bereiche, die kontrollieren, was es tun kann. Die oben genannten Endpunkte listen den Bereich auf, den jeder benötigt.

Umfang	Gewährt
CAN_SEND_MESSAGES	Senden Sie Standard-Chatnachrichten als Benutzer des Tokens.
CAN_SEND_SYSTEM_MESSAGES	Senden Sie Chatnachrichten als System und senden Sie Chataktionen.
HAS_ADMIN_ACCESS	Administrative actions: read chat history, list connected clients, set the stream title, change message visibility, get the server status, and look up a chat user.

Antworten und Fehler

Status	Bedeutung
200	Die Anfrage war erfolgreich. For the mutation (POST) endpoints the JSON body is the success: true envelope with a short message. The GET endpoints return the domain object instead: the server status, an array of chat messages, an array of connected clients, or a user's details.
400	Der Anfragetext war fehlerhaft. Der JSON-Body hat success: false und eine message.
401	Das Zugriffstoken fehlt, ist ungültig oder hat nicht den erforderlichen Umfang für den Endpunkt. Der Text ist einfacher Text.
500	Der Server hat beim Verarbeiten der Anfrage einen Fehler aufgetreten.

Owncast gibt keinen separaten 403 für einen unzureichenden Umfang zurück. Ein Token ohne den erforderlichen Umfang wird mit 401 abgelehnt, genau wie ein fehlendes oder ungültiges Token.