Envoyer des requêtes à l'API Owncast

Nous supportons actuellement les actions suivantes que vous pouvez effectuer via des requêtes depuis votre code.

Événement	Point de terminaison	Portée
Message de chat système	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
Message de chat standard	/api/integrations/chat/send	CAN_SEND_MESSAGES
Action de chat	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
Supprimer le message de chat	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
Obtenir l'historique des chats	/api/integrations/chat	HAS_ADMIN_ACCESS
Obtenir les clients connectés	/api/integrations/clients	HAS_ADMIN_ACCESS
Définir le titre du flux	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
message système au 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

Visitez la documentation de l'API pour chaque point de terminaison afin d'en savoir plus sur les valeurs attendues ou qui seront retournées.

Votre serveur Owncast n'acceptera que les actions des requêtes avec un jeton d'accès valide. Suivez les étapes ci-dessous pour créer un jeton d'accès.

1. visitez /admin/access-tokens sur votre serveur Owncast.
2. Cliquez sur Créer un jeton d'accès.
3. Sélectionnez la portée des autorisations que vous souhaitez donner à ce jeton.
4. Enregistrez ce jeton d'accès.

Votre code

Envoyez un POST authentifié avec votre jeton d'accès dans l'en-tête Authorization et un corps JSON. Par exemple, pour envoyer un message de chat système :

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

Tester l'envoi de messages de chat

Changez la commande curl suivante pour pointer vers l'URL de votre serveur et utilisez votre jeton d'authentification avec accès "message système". Cela enverra un message système à votre 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

Une requête réussie retourne 200 avec un corps JSON :

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

Portées

Chaque jeton d'accès se voit attribuer une ou plusieurs portées qui contrôlent ce qu'il peut faire. Les points de terminaison ci-dessus listent la portée requise pour chacun d'eux.

Portée	Accorde
CAN_SEND_MESSAGES	Envoyez des messages de chat standard en tant qu'utilisateur du jeton.
CAN_SEND_SYSTEM_MESSAGES	Envoyez des messages de chat en tant que système et envoyez des actions 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.

Réponses et erreurs

Statut	Signification
200	La requête a réussi. 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	Le corps de la requête était mal formé. Le corps JSON a success: false et un message.
401	Le jeton d'accès est manquant, invalide, ou n'a pas la portée requise par le point de terminaison. Le corps est du texte brut.
500	Le serveur a rencontré une erreur lors du traitement de la requête.

Owncast ne retourne pas un 403 séparé pour une portée insuffisante. Un jeton sans la portée requise est rejeté avec 401, de la même manière qu'un jeton manquant ou invalide.