Перейти к основному содержимому

Данные из API в ответах команд

Переменная $(api ...) подставляет в ответ команды данные внешнего сервиса. Например, бот может показать курс валюты или игровую статистику. Для этого нужна ссылка на API, которое возвращает JSON, и путь к нужному полю в его ответе.

Пример: курс доллара​

Создадим команду !курс, которая показывает курс доллара к рублю из API Frankfurter.

  1. Откройте раздел команд в панели управления, создайте команду и укажите !курс.

  2. Вставьте в текст ответа:

    Курс доллара: $(api https://api.frankfurter.dev/v2/rate/USD/RUB $.rate) ₽

  3. Нажмите «Тест», чтобы проверить результат.

  4. Сохраните команду и вызовите !курс в чате.

Редактор команды !курс: переменная с API Frankfurter и результат теста Курс доллара: 86.3 ₽

На скриншоте бот отвечает: Курс доллара: 86.3 ₽.

Вызов команды !курс в чате и ответ бота Курс доллара: 86.3 ₽

Как устроена переменная​

Общий формат:

$(api URL $.path)

Замените URL ссылкой на API, а $.path — путём к полю, которое хотите вывести. Между ссылкой и путём нужен пробел.

В нашем примере API возвращает:

{
  "date": "2026-09-08",
  "base": "USD",
  "quote": "RUB",
  "rate": 86.3
}

Символ $ обозначает весь ответ. Путь $.rate выбирает поле rate, поэтому вместо переменной бот подставляет число 86.3, сохраняя текст вокруг неё.

Названия полей зависят от конкретного API. Откройте ссылку в браузере или посмотрите документацию сервиса, чтобы найти нужное поле.

Вложенные поля и списки​

Допустим, другой сервис возвращает такой JSON:

{
  "player": {
    "nickname": "Streamer",
    "elo": 1850
  },
  "matches": [
    {"map": "Mirage"},
    {"map": "Inferno"}
  ]
}
Что вывестиПутьРезультат
Никнейм игрока$.player.nicknameStreamer
Elo игрока$.player.elo1850
Карту первого матча$.matches[0].mapMirage

Точка переходит к вложенному полю. Число в квадратных скобках выбирает элемент списка: нумерация начинается с нуля. Если путь находит несколько значений, бот выводит первое.

Переменную API можно сочетать с обычным текстом и другими переменными команды.

Если вместо значения появилась ошибка​

Сообщение «API временно недоступно» означает, что бот не смог получить нужное значение. Такое бывает, если сервис недоступен, возвращает ошибку или не JSON, либо указанного поля нет в ответе.

Проверьте ссылку и фактический ответ сервиса. Сверьте названия полей, их вложенность и индекс элемента списка. Затем снова нажмите «Тест». Успешное сохранение команды проверяет её запись, но не гарантирует доступность внешнего сервиса.

После нескольких ошибок обращения к одному адресу бот может временно приостановить запросы к нему. Если тест уже работает, а чат ещё показывает ошибку, повторите вызов позже: такая пауза длится до 15 минут.

Ограничения​

  • Используйте прямую публичную ссылку по HTTPS, без перенаправлений.
  • Ссылка должна быть фиксированной: подставить в неё ник зрителя или другую переменную нельзя.
  • Бот выполняет GET-запрос. Собственные заголовки авторизации и тело запроса задать нельзя.
  • В одном ответе допускается до 2 переменных API. Если у команды несколько вариантов ответа, суммарно в них допускается до 10 таких переменных.
  • На бесплатном тарифе можно создать до 3 команд с API, с платной подпиской — до 10 на канал.
  • Результат кешируется на 15 секунд. Повторный вызов в это время может показать прежнее значение.
  • Общая задержка между вызовами одной команды с API — минимум 5 секунд, независимо от того, какой зритель её вызвал.