Envie requisições para a API Owncast

Atualmente, apoiamos as seguintes ações que você pode realizar por meio de requisições do seu código.

Evento	Ponto final	Escopo
Mensagem de chat do sistema	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
Mensagem de chat padrão	/api/integrations/chat/send	CAN_SEND_MESSAGES
Ação de chat	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
Remover mensagem de chat	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
Obter o histórico do chat	/api/integrations/chat	HAS_ADMIN_ACCESS
Obter clientes conectados	/api/integrations/clients	HAS_ADMIN_ACCESS
Definir o título do stream	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
mensagem do sistema para o 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 a documentação da API para cada endpoint para saber mais sobre quais valores são esperados ou serão retornados.

Seu servidor Owncast aceitará apenas ações de requisições com um Token de Acesso válido. Siga os passos abaixo para criar um token de acesso.

1. visite /admin/access-tokens em seu servidor Owncast.
2. Clique em Criar Token de Acesso.
3. Selecione o escopo de permissões que você deseja conceder a este token.
4. Salve este token de acesso.

Seu código

Envie um POST autenticado com seu token de acesso no cabeçalho Authorization e um corpo JSON. Por exemplo, para enviar uma mensagem de chat do 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" }

Teste o envio de mensagens de chat

Altere o seguinte comando curl para apontar para a URL do seu servidor e usar seu token de autenticação com acesso a "mensagem do sistema". Ele enviará uma mensagem do sistema para o seu 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

Uma requisição bem sucedida retorna 200 com um corpo JSON:

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

Escopos

Cada token de acesso é concedido um ou mais escopos que controlam o que ele pode fazer. Os endpoints acima listam o escopo que cada um requer.

Escopo	Concessões
CAN_SEND_MESSAGES	Enviar mensagens de chat padrão como o próprio usuário do token.
CAN_SEND_SYSTEM_MESSAGES	Enviar mensagens de chat como o sistema e enviar ações 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.

Respostas e erros

Status	Significado
200	A requisição foi bem-sucedida. 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	O corpo da requisição estava malformado. O corpo JSON tem success: false e uma message.
401	O token de acesso está faltando, é inválido ou não possui o escopo que o endpoint requer. O corpo é texto puro.
500	O servidor encontrou um erro ao processar a requisição.

Owncast não retorna um 403 separado para um escopo insuficiente. Um token sem o escopo requerido é rejeitado com 401, o mesmo que um token ausente ou inválido.