メインコンテンツまでスキップ

ギフト履歴を取得

現在の配信で受け取ったギフトステッカーの履歴を取得します。イベントストリームの donation はリアルタイムに一度だけ届くので、 ボットが止まっていた間のギフトを復旧するとき にこの API を使います。

メソッド・パスGET /v1/live/donations
必要な権限donations.read
成功レスポンス200
配信中でないとき404(OAPI_MNGR_0301)

ギフトが多い配信は一度にすべては返さず カーソルで続きを受け取ります。

export SPOON_BASE_URL="https://jp-openapi.spooncast.net"
export SPOON_ACCESS_TOKEN="{発行された access token}"

韓国リージョンなら https://kr-openapi.spooncast.net です — リージョン別アドレス。

リクエスト​

GET /v1/live/donations?cursor={cursor}

ヘッダー​

名前必須説明
Authorization✔Bearer {access_token} 形式です。

クエリパラメータ​

名前型必須説明
cursorstring前のレスポンスの nextCursor をそのまま入れます。最初のページでは省略します。

リクエスト例​

# 最初のページ
curl -H "Authorization: Bearer $SPOON_ACCESS_TOKEN" "$SPOON_BASE_URL/v1/live/donations"

# 次のページ — 前のレスポンスの nextCursor をそのまま入れます
curl -H "Authorization: Bearer $SPOON_ACCESS_TOKEN" \
  "$SPOON_BASE_URL/v1/live/donations?cursor=1024307"

レスポンス​

{
  "donations": [
    {
      "user": {
        "id": "Ab1Cd2Ef3Gh4Ij5Kl6Mn7O",
        "nickname": "スプーンリスナー"
      },
      "stickerName": "ハート",
      "amount": 300,
      "time": "2026-10-19T05:47:50.512Z"
    }
  ],
  "nextCursor": "1024307"
}
フィールド型null説明
donationsobject[]いいえ現在の配信で受け取ったギフトです。
donations[].userobjectいいえギフトを送った人です。
donations[].user.idstringいいえギフトを送った人を指す値です。暗号化した値です。
donations[].user.nicknamestringいいえニックネームです。
donations[].stickerNamestringいいえステッカーの表示名です。アプリの画面に見える名前そのままです。
donations[].amountnumberいいえこのギフトの 合計スプーン です。イベントストリーム donation の amount と同じ値です。
donations[].timestringいいえギフトの時刻です。ISO-8601 UTC(Z)です。
nextCursorstringはい次のページのカーソルです。null なら最後のページ です。
user.id で人を識別します

user.id はその人の一意な識別子です。同じ人なら常に同じ値なので、出席・累計・ランキングのキーとして 使います。user.nickname は変わり、重複するので識別に使わないでください。

値の範囲は自分のボットとその DJ の組み合わせです。DJ が連携を解除して再度同意しても維持されます。

この user は イベントストリームの user と同じ形・同じ id です。リアルタイムに受け取った ギフトとこの履歴を同じキーで突き合わせられます。

コード​

// donations.ts — node --experimental-strip-types donations.ts

interface Donation {
  user: { id: string; nickname: string };
  stickerName: string;
  amount: number;
  time: string;
}

interface DonationsPage {
  donations: Donation[];
  nextCursor: string | null;
}

const BASE = process.env.SPOON_BASE_URL;
const TOKEN = process.env.SPOON_ACCESS_TOKEN;

const all = [];
let cursor;

do {
  const url = new URL(`${BASE}/v1/live/donations`);
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });
  if (!res.ok) throw new Error(`ギフト履歴の取得に失敗しました: ${res.status}`);

  const page = (await res.json()) as DonationsPage;
  all.push(...page.donations);
  cursor = page.nextCursor;   // null なら繰り返しが終わります
} while (cursor);

const total = all.reduce((sum, d) => sum + d.amount, 0);
console.log(`この配信のギフトは ${all.length}件、合計 ${total} スプーンです。`);

// 再起動後の復旧 — 保存しておいた最後の処理時刻より後だけ処理し直します
const lastProcessedTime = '2026-10-19T05:00:00.000Z';
const missed = all.filter((d) => d.time > lastProcessedTime);
console.log(`取りこぼした ${missed.length}件のギフトを処理し直します。`);
node --experimental-strip-types donations.ts

注意​

現在の配信の範囲です。 配信が終わるとその配信の履歴は取得できず、次の配信では次の配信の分 だけが返ります。配信をまたいで積み上げるならボット側で保存します。

メッセージはありません。 ギフトに添えられた一言(message)は イベントストリーム donation にだけ載ります。 一言が必要な機能はリアルタイムで受け取って保存します。

普段はイベントストリームで受け取ります。 この API は復旧用です — 再接続したときにその間の 履歴を取り込んで埋め、同じギフトが両方から来たら user.id と time の組み合わせで重複を除きます。

nextCursor が null になるまで繰り返します。 最初のページだけで終えると、ギフトが多い 配信では一部しか見えません。逆に null をそのまま ?cursor= に入れてはいけません — 繰り返しを止める合図です。

エラー​

HTTPdetailCode何が起きたかどうするか
400OAPI_MNGR_0103cursor が正しくありません。前のレスポンスの nextCursor ではありません。cursor なしで最初のページからやり直します。
401なしトークンがないか無効です。DJ に再連携を案内します。
403なしdonations.read の権限がありません。権限を追加して再同意を得ます。
404OAPI_MNGR_0301配信中ではありません。エラーではなく状態です。しばらくして呼び直します。
502OAPI_MNGR_2302配信サーバーのエラーです。バックオフしてから再試行します。

この表にない状態も返ることがあります。 誤ったメソッド・Content-Type(400・405・415、 OAPI_MNGR_0103)・呼び出し上限(429、ボディなし)・サーバーエラー(500、OAPI_MNGR_1002)は すべてのエンドポイントに共通 です — エラーコード にあります。

関連ドキュメント​