Invia richieste all'API di Owncast

Attualmente supportiamo le seguenti azioni che puoi eseguire tramite richieste dal tuo codice.

Evento	Interfaccia	Ambito
Messaggio di chat del sistema	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
Messaggio di chat standard	/api/integrations/chat/send	CAN_SEND_MESSAGES
Azione di chat	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
Rimuovi messaggio di chat	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
Recupera la cronologia della chat	/api/integrations/chat	HAS_ADMIN_ACCESS
Recupera i client connessi	/api/integrations/clients	HAS_ADMIN_ACCESS
Imposta il titolo dello stream	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
messaggio di sistema al 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

Visita la documentazione dell'API per ciascun endpoint per saperne di più sui valori attesi o che verranno restituiti.

Il tuo server Owncast accetterà solo azioni da richieste con un Token di Accesso valido. Segui i passaggi seguenti per creare un token di accesso.

1. visita /admin/access-tokens sul tuo server Owncast.
2. Clicca su Crea token di accesso.
3. Seleziona l'ambito delle autorizzazioni che desideri attribuire a questo token.
4. Salva questo token di accesso.

Il tuo codice

Invia un POST autenticato con il tuo token di accesso nell'intestazione Authorization e un corpo JSON. Ad esempio, per inviare un messaggio di chat di sistema:

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" }

Testa l'invio di messaggi in chat

Cambia il seguente comando curl per puntare all'URL del tuo server e usa il tuo token di autenticazione con accesso "messaggio di sistema". Invierà un messaggio di sistema alla tua 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

Una richiesta riuscita restituisce 200 con un corpo JSON:

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

Ambiti

Ogni token di accesso viene concesso uno o più ambiti che controllano cosa può fare. Gli endpoint sopra elencano l'ambito che ciascuno richiede.

Ambito	Concessioni
CAN_SEND_MESSAGES	Invia messaggi in chat standard come l'utente del token.
CAN_SEND_SYSTEM_MESSAGES	Invia messaggi in chat come il sistema e invia azioni di chat.
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.

Risposte e errori

Stato	Significato
200	La richiesta è andata a buon fine. 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	Il corpo della richiesta era malformato. Il corpo JSON ha success: false e un message.
401	Il token di accesso è mancante, non valido o privo dell'ambito richiesto dall'endpoint. Il corpo è testo semplice.
500	Il server ha riscontrato un errore nel gestire la richiesta.

Owncast non restituisce un 403 separato per un ambito insufficiente. Un token senza l'ambito richiesto viene rifiutato con 401, lo stesso di un token mancante o non valido.