Enviar solicitudes a la API de Owncast

Actualmente admitimos las siguientes acciones que puede realizar a través de solicitudes desde su código.

Evento	Endpoint	Alcance
Mensaje de chat del sistema	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
Mensaje de chat estándar	/api/integrations/chat/send	CAN_SEND_MESSAGES
Acción de chat	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
Eliminar mensaje de chat	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
Obtener historial de chat	/api/integrations/chat	HAS_ADMIN_ACCESS
Obtener clientes conectados	/api/integrations/clients	HAS_ADMIN_ACCESS
Establecer título del stream	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
mensaje del sistema al cliente	/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

Visite la documentación de la API para cada endpoint para obtener más información sobre qué valores se esperan o se devolverán.

Su servidor Owncast solo aceptará acciones de solicitudes con un token de acceso válido. Siga los pasos a continuación para crear un token de acceso.

1. visite /admin/access-tokens en su servidor owncast.
2. Haga clic en Crear token de acceso.
3. Seleccione el alcance de los permisos que desea otorgar a este token.
4. Guarde este token de acceso.

Su código

Envíe un POST autenticado con su token de acceso en el encabezado Authorization y un cuerpo JSON. Por ejemplo, para enviar un mensaje de chat del 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" }

Prueba enviar mensajes de chat

Cambia el siguiente comando curl para señalar la URL de su servidor y usar su token de autenticación con acceso a "mensaje del sistema". Se enviará un mensaje del sistema a su 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 solicitud exitosa devuelve 200 con un cuerpo JSON:

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

Alcances

A cada token de acceso se le concede uno o más alcances que controlan lo que puede hacer. Los endpoints anteriores enumeran el alcance que cada uno requiere.

Alcance	Concesiones
CAN_SEND_MESSAGES	Enviar mensajes de chat estándar como el propio usuario del token.
CAN_SEND_SYSTEM_MESSAGES	Enviar mensajes de chat como el sistema y enviar acciones de 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.

Respuestas y errores

Estado	Significado
200	La solicitud tuvo éxito. 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	El cuerpo de la solicitud estaba mal formado. El cuerpo JSON tiene success: false y un message.
401	El token de acceso falta, es inválido o no tiene el alcance que requiere el endpoint. El cuerpo es texto sin formato.
500	El servidor encontró un error al manejar la solicitud.

Owncast no devuelve un 403 separado por un alcance insuficiente. Un token sin el alcance requerido es rechazado con 401, lo mismo que un token faltante o inválido.