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ドキュメンテーションを参照して、期待される値や返される値を学んでください。

Your Owncastサーバーは、有効なアクセストークンを持つリクエストからのアクションのみを受け入れます。 アクセストークンを作成するには、以下の手順に従ってください。

1. Owncastサーバーで/admin/access-tokensにアクセスします。
2. Access Tokenを作成するをクリックします。
3. このトークンに付与する許可のスコープを選択してください。
4. このアクセストークンを保存してください。

あなたのコード

アクセストークンをAuthorizationヘッダーに入れ、JSONボディで認証されたPOSTを送信します。 例えば、システムチャットメッセージを送信するには：

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

スコープ

各アクセストークンには、それが何を行うことができるかを制御する1つ以上のスコープが付与されます。 上記のエンドポイントは、それぞれが必要とするスコープをリストしています。

スコープ	付与される権限
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で拒否されます。