向 Owncast API 发送请求

我们目前支持您可以通过代码发出的以下请求。

事件	端点	范围
系统聊天消息	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
标准聊天消息	/api/integrations/chat/send	CAN_SEND_MESSAGES
聊天操作	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
移除聊天消息	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
获取聊天历史	/api/integrations/chat	HAS_ADMIN_ACCESS
获取连接的客户端	/api/integrations/clients	HAS_ADMIN_ACCESS
设置流标题	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
发送给客户端的系统消息	/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

访问每个端点的 API 文档，以了解期望或将返回的值。

您的 Owncast 服务器仅接受带有有效访问令牌的请求中的操作。 按照以下步骤创建访问令牌。

1. 访问您的 Owncast 服务器上的 /admin/access-tokens。
2. 单击 创建访问令牌。
3. 选择您希望授予此令牌的权限范围。
4. 保存此访问令牌。

您的代码

发送一个经过身份验证的 POST 请求，使用您的访问令牌在 Authorization 标头中并使用 JSON 主体。 例如，要发送系统聊天消息：

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

测试发送聊天消息

更改以下 curl 命令以指向您的服务器 URL，并使用具有 "系统消息" 访问权限的身份验证令牌。 它将向您的聊天发送系统消息。

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

成功的请求返回 200 并带有 JSON 主体：

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

权限范围

每个访问令牌被授予一个或多个权限范围，以控制它可以执行什么。 上面列出的端点显示每个端点所需的范围。

范围	授予
CAN_SEND_MESSAGES	作为令牌自己的用户发送标准聊天消息。
CAN_SEND_SYSTEM_MESSAGES	以系统身份发送聊天消息，并发送聊天操作。
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.

响应和错误

状态	含义
200	请求成功。 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	请求主体格式不正确。 JSON 主体具有 success: false 和 message。
401	缺少访问令牌、无效或缺少端点所需的范围。 主体是纯文本。
500	服务器在处理请求时发生错误。

Owncast 不会为权限不足返回单独的 403。 缺少所需范围的令牌与丢失或无效的令牌一起被拒绝，都是 401。