Методы API

Донаты

История донатов стримера, тестовые донаты и объект доната с голосовыми сообщениями и кружочками.

Список донатов

GEThttps://donatex.gg/api/v1/donations

Возвращает донаты стримера страницами — по умолчанию от новых к старым. Можно искать по нику и тексту, фильтровать по периоду или произвольному диапазону дат.

Для живых уведомлений не опрашивайте этот метод в цикле — подключитесь к realtime-хабу или вебхукам.

OAuth-токену нужен scope donations.read. External token работает без scopes.

Query-параметры

skipintegerнеобязательный

Сколько донатов пропустить (offset). По умолчанию 0

takeintegerобязательный

Размер страницы, до 100. Без него вернётся пустой массив

querystringнеобязательный

Поиск по нику или тексту сообщения, до 50 символов

hideTestbooleanнеобязательный

Скрыть тестовые донаты. По умолчанию false

periodstringнеобязательный

Период: Day, Week, Month, AllTime, CurrentStream, Last24Hours, Last7Days, Last30Days, CurrentYear, Last365Days

startDatedateнеобязательный

Начало диапазона в UTC, YYYY-MM-DD. Только вместе с endDate и без period

endDatedateнеобязательный

Конец диапазона в UTC, YYYY-MM-DD, включительно

sortOrderstringнеобязательный

NewestFirst (по умолчанию) или OldestFirst

Ответы

iduuid

ID доната

usernamestring

Никнейм донатера

messagestring

Текст сообщения. У голосового доната и кружочка — пустая строка либо расшифровка записи, если заказан ответ ИИ

withAIResponseboolean

Заказан ли ответ ИИ

aiCharacterIduuid | null

Сохранённый ID ИИ-персонажа, совпадает с id из /v1/ai/characters. null, если персонаж не был записан, в том числе у старых донатов. Не зависит от готовности ответа; удалённый персонаж может отсутствовать в списке

musicLinkstring

Ссылка на трек; пустая строка, если музыку не заказали

currencystring

Валюта, в которой донатер видел сумму: RUB, USD, EUR, KZT…

amountnumber

Сумма в валюте currency без доплат за ИИ и голос

amountInRubnumber

Сумма в рублях

timestampdatetime

Время доната в UTC, ISO 8601

aiResponsestring | null

Текст ответа ИИ; null, если ответа нет или он ещё не готов

aiResponseVoiceFilePathstring | null

URL озвучки ответа ИИ; null вместе с aiResponse

wasShownboolean

Показан ли донат на стриме

isTestboolean

Тестовый донат

isPotentiallyUnsafeboolean

Помечен ли донат модерацией как потенциально небезопасный

isFeePaidByUserboolean

Оплатил ли донатер комиссию

voiceFilePathstring | null

URL озвучки сообщения (TTS) или null, если озвучка не создана, например сумма ниже минимума стримера. Файлы хранятся 30 дней. Для голосовых донатов и кружочков используйте собственные записи

paidVoicestring

Название платного голоса; пустая строка для голоса по умолчанию

voiceMessagePathstring | null

URL голосового сообщения, которое записал зритель; null, если его нет

voiceMessageDurationMsinteger | null

Длительность голосового сообщения в миллисекундах

videoMessagePathstring | null

URL кружочка: квадратное видео MP4 (H.264 + AAC). null для других донатов и для кружочков, которые модерация скрыла до одобрения стримером

videoMessagePosterPathstring | null

URL постера кружочка — первого кадра в JPEG. Удобно показывать, пока видео грузится

videoMessageDurationMsinteger | null

Длительность кружочка в миллисекундах

You can't request more than 100 donations for page

Max query length is 50 symbols

Unknown period. Allowed: Day, Week, Month, AllTime, CurrentStream, Last24Hours, Last7Days, Last30Days, CurrentYear, Last365Days

Both startDate and endDate must be specified for a custom period

startDate must not be later than endDate

Specify either period or startDate and endDate

Unknown sort order. Allowed: NewestFirst, OldestFirst

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "skip": [
      "The value 'abc' is not valid."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Общие для всех методов: 401 — нет токена или он недействителен, 403 — у OAuth-токена нет нужного scope, 429 — превышен лимит запросов. Подробнее об ошибках

GET/v1/donations

curl "https://donatex.gg/api/v1/donations?skip=0&take=20&period=Last7Days" \
  -H "Authorization: Bearer $DONATEX_TOKEN"

[
  {
    "id": "4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b",
    "username": "NeDrugLegenda1377",
    "message": "",
    "withAIResponse": false,
    "musicLink": "",
    "currency": "RUB",
    "amount": 500.00,
    "amountInRub": 500.00,
    "timestamp": "2026-10-12T18:42:07Z",
    "aiResponse": null,
    "aiResponseVoiceFilePath": null,
    "wasShown": true,
    "isTest": false,
    "isPotentiallyUnsafe": false,
    "isFeePaidByUser": true,
    "voiceFilePath": "https://cdn.donatex.gg/default-donation-voices/4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b.mp3",
    "paidVoice": "",
    "voiceMessagePath": null,
    "voiceMessageDurationMs": null,
    "videoMessagePath": "https://cdn.donatex.gg/donation-video-messages/4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b.mp4",
    "videoMessagePosterPath": "https://cdn.donatex.gg/donation-video-messages/4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b.jpg",
    "videoMessageDurationMs": 14250,
    "aiCharacterId": null
  }
]

Тестовый донат

POSThttps://donatex.gg/api/v1/test-donation

Отправляет тестовый донат на канал владельца токена. Он проходит весь путь настоящего: алерт в виджете, событие DonationCreated в realtime-хабе и вебхуки.

Необязательные поля не передавайте вовсе: null вместо числа, boolean или uuid вернёт 400.

OAuth-токену нужен scope donations.write. External token работает без scopes.

Тело запроса

usernamestringобязательный

Имя донатера, 1–30 символов

amountnumberобязательный

Сумма, не меньше 0

currencystringобязательный

RUB, USD, KZT или EUR

messagestringнеобязательный

Текст, до 300 символов и не длиннее лимита из настроек стримера

withAIResponsebooleanнеобязательный

Сгенерировать ответ ИИ. Нужен верифицированный аккаунт; не больше 5 тестовых донатов с ИИ в день

aiPresetIduuidнеобязательный

ID активного ИИ-персонажа, который ответит. Без него отвечает основной

musicLinkstringнеобязательный

Ссылка на YouTube-трек. Музыкальный виджет должен быть включён

Ответы

Тело ответа пустое — проверяйте только статус.

Виджет музыки выключен

Ваш лимит 5 тестовых донатов с ИИ в день!

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "username": [
      "'username' must not be empty."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

POST/v1/test-donation

curl -X POST "https://donatex.gg/api/v1/test-donation" \
  -H "Authorization: Bearer $DONATEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "Mopsik",
    "message": "Это я — твой единственный зритель.",
    "amount": 100,
    "currency": "RUB"
  }'

// Пустое тело ответа

Объект доната

Один формат для истории донатов, событий DonationCreated и DonationRerun и вебхуков. Новые поля всегда добавляются в конец — существующие не меняются.

iduuid

ID доната

usernamestring

Никнейм донатера

messagestring

withAIResponseboolean

Заказан ли ответ ИИ

aiCharacterIduuid | null

musicLinkstring

Ссылка на трек; пустая строка, если музыку не заказали

currencystring

Валюта, в которой донатер видел сумму: RUB, USD, EUR, KZT…

amountnumber

Сумма в валюте currency без доплат за ИИ и голос

amountInRubnumber

Сумма в рублях

timestampdatetime

Время доната в UTC, ISO 8601

aiResponsestring | null

Текст ответа ИИ; null, если ответа нет или он ещё не готов

aiResponseVoiceFilePathstring | null

URL озвучки ответа ИИ; null вместе с aiResponse

wasShownboolean

Показан ли донат на стриме

isTestboolean

Тестовый донат

isPotentiallyUnsafeboolean

Помечен ли донат модерацией как потенциально небезопасный

isFeePaidByUserboolean

Оплатил ли донатер комиссию

voiceFilePathstring | null

paidVoicestring

Название платного голоса; пустая строка для голоса по умолчанию

voiceMessagePathstring | null

URL голосового сообщения, которое записал зритель; null, если его нет

voiceMessageDurationMsinteger | null

Длительность голосового сообщения в миллисекундах

videoMessagePathstring | null

videoMessagePosterPathstring | null

URL постера кружочка — первого кадра в JPEG. Удобно показывать, пока видео грузится

videoMessageDurationMsinteger | null

Длительность кружочка в миллисекундах

Донат с кружочком

{
  "id": "4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b",
  "username": "NeDrugLegenda1377",
  "message": "",
  "withAIResponse": false,
  "musicLink": "",
  "currency": "RUB",
  "amount": 500.00,
  "amountInRub": 500.00,
  "timestamp": "2026-10-12T18:42:07Z",
  "aiResponse": null,
  "aiResponseVoiceFilePath": null,
  "wasShown": true,
  "isTest": false,
  "isPotentiallyUnsafe": false,
  "isFeePaidByUser": true,
  "voiceFilePath": "https://cdn.donatex.gg/default-donation-voices/4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b.mp3",
  "paidVoice": "",
  "voiceMessagePath": null,
  "voiceMessageDurationMs": null,
  "videoMessagePath": "https://cdn.donatex.gg/donation-video-messages/4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b.mp4",
  "videoMessagePosterPath": "https://cdn.donatex.gg/donation-video-messages/4fd9677b-8b17-4c9d-9a9f-c2a7a3f9960b.jpg",
  "videoMessageDurationMs": 14250,
  "aiCharacterId": null
}

Кружочки и голосовые

Зритель может приложить к донату голосовое сообщение или кружочек — короткое видео с камеры. Ссылки на файлы готовы к воспроизведению как есть.

Кружочек — видео в videoMessagePath, постер в videoMessagePosterPath, длительность в videoMessageDurationMs.
Голосовое — запись зрителя в voiceMessagePath, длительность в voiceMessageDurationMs.
Если оба поля пустые — обычный текстовый донат, URL его озвучки лежит в voiceFilePath или равен null, если озвучка не создана.

Модерация кружочков

Если модерация пометила кружочек как потенциально небезопасный (isPotentiallyUnsafe: true), ссылки на видео и постер приходят как null. Когда стример одобрит донат, придёт событие DonationRerun уже со ссылками.

Оверлей: выбираем, что проиграть

connection.on('DonationCreated', (donation) => {
  if (donation.videoMessagePath) {
    // Кружочек: квадратное MP4, постер — первый кадр
    showCircle({
      src: donation.videoMessagePath,
      poster: donation.videoMessagePosterPath,
      durationMs: donation.videoMessageDurationMs,
    });
  } else if (donation.voiceMessagePath) {
    playAudio(donation.voiceMessagePath);
  } else if (donation.voiceFilePath) {
    speak(donation.voiceFilePath);
  }
});

Лимиты

Дальше

Алерты