API Chat LD

API нужен, чтобы выводить в виджет Chat LD сообщения из своих программ: ботов, сервисов донатов, игровых событий, площадок, которых нет в приложении. И чтобы читать общий чат стрима: для озвучки, статистики, своего оверлея. Для каждого проекта ключ один, и он же стоит в ссылке на виджет.

Ключ и адрес

Ключ виден в кабинете, это тот же API-ключ, что вставлен в приложение. Все запросы идут на один адрес:

https://app.chat-ld.pro/api/v1/messages/

Ключ передаётся заголовком Authorization: Bearer КЛЮЧ. Если программа не умеет задавать заголовки, подойдёт X-Api-Key: КЛЮЧ или параметр ?key=КЛЮЧ в адресе.

С ключом можно писать в ваш виджет и читать ваш чат. Не публикуйте его на открытых страницах. Если ключ утёк, нажмите «Перевыпустить» в кабинете: старый перестанет работать сразу, а ссылку виджета в OBS и ключ в приложении нужно будет заменить.

Отправить сообщение в виджет

POST https://app.chat-ld.pro/api/v1/messages/, тело - JSON:

curl -X POST https://app.chat-ld.pro/api/v1/messages/ \
  -H "Authorization: Bearer КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"username": "DonationAlerts", "text": "Петя задонатил 500 ₽: удачи!", "id": "don-1842"}'

Ответ 201:

{"ok": true, "id": 1281995}

Если сообщение с таким id уже было, ответ 200 с тем же номером и "duplicate": true. Если ник или текст пришлось обрезать, в ответе будет "truncated": true.

Прочитать чат

GET https://app.chat-ld.pro/api/v1/messages/ отдаёт сообщения из всех источников: приложения, Telegram-групп, API.

{
  "ok": true,
  "messages": [
    {
      "id": 1281996,
      "source": "twitch",
      "username": "Зритель",
      "text": "привет Kappa",
      "html": "привет <img alt=\"Kappa\" src=\"https://...\">",
      "date": "2026-10-23T14:58:47Z",
      "reply_to": null
    }
  ],
  "last_id": 1281996
}

text - сообщение без разметки, смайлы площадок заменены их названием. html - то же, что показывает виджет, вместе с картинками смайлов. username и text - простой текст: прежде чем вставлять их в HTML, экранируйте их. Время date указано в UTC. Сообщения хранятся 30 дней.

Чтобы следить за чатом, первый раз запросите ленту без after_id, а дальше раз в 1-2 секунды запрашивайте её с after_id, равным last_id из прошлого ответа.

Примеры

JavaScript (браузер или Node.js 18+):

const KEY = 'КЛЮЧ';
const URL = 'https://app.chat-ld.pro/api/v1/messages/';

await fetch(URL, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'Бот', text: 'Раунд начался!' }),
});

let lastId = 0;
setInterval(async () => {
  const res = await fetch(`${URL}?after_id=${lastId}`, { headers: { 'Authorization': `Bearer ${KEY}` } });
  const data = await res.json();
  for (const m of data.messages) console.log(m.source, m.username, m.text);
  lastId = data.last_id;
}, 2000);

Python:

import requests, time

KEY = "КЛЮЧ"
URL = "https://app.chat-ld.pro/api/v1/messages/"
HEADERS = {"Authorization": f"Bearer {KEY}"}

requests.post(URL, json={"username": "Бот", "text": "Раунд начался!"}, headers=HEADERS)

last_id = 0
while True:
    data = requests.get(URL, params={"after_id": last_id}, headers=HEADERS).json()
    for m in data["messages"]:
        print(m["source"], m["username"], m["text"])
    last_id = data["last_id"]
    time.sleep(2)

API отвечает и запросам со страниц в браузере (CORS разрешён для любых сайтов). Но ключ в коде страницы увидит любой посетитель, поэтому так стоит делать только на страницах, которые видите вы сами: в OBS или локально.

Лимиты

• Не больше 30 сообщений за 10 секунд на один ключ. Сверх лимита - ответ 429, заголовок Retry-After говорит, через сколько секунд можно повторить.
• Тело запроса - до 64 КБ.
• Чтение лентой не ограничено, но запрашивать её чаще раза в секунду смысла нет.

Ошибки

При ошибке API отвечает так: {"ok": false, "error": "invalid_key", "message": "API-ключ не найден"}. Поле error не меняется, по нему удобно ветвить код, message - пояснение для человека.