HTTP APIВыдача рекламы

Фото и анимации

POST/api/v1/ad/fetch-image

Метод только для изображений. Тело запроса совпадает с /api/v1/ad/fetch без accept_formats (сервер всегда считает его равным ["image"]). Используйте для отправки фото или анимации отдельно от текста ответа LLM. Возвращает { "has_ad": false, ... } , если для площадки или языка нет подходящей рекламы с изображением.

Авторизация

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Тот же Bearer-токен, что и для /api/v1/ad. Создайте ключи в настройках паблишера.

Тело запроса

Поле	Тип	Описание
`user_id`обязательно	number	ID пользователя Telegram (ctx.from.id): конечное число. Документация Telegram User →
`platform_id`обязательно	string	Публичный ID вашей площадки (plt_…). кабинета площадок →
`language_code`обязательно	string	Непустой языковой тег IETF, например "en" или "ru". Обязателен, даже если Telegram не передал language_code; используйте язык, выбранный в боте. Документация Telegram User →
`is_premium`	boolean	Есть ли у пользователя Telegram Premium. По умолчанию: false. Документация Telegram User →
`group_id`	number	ID чата Telegram для групп и супергрупп: ограничения частоты и суточные лимиты применяются к чату. В личных чатах не передавайте. Документация Telegram Chat →
`participants_count`	number	Неотрицательное число участников группы. Имеет смысл только вместе с group_id.
`group_name`	string	Необязательное название группы. Проверяется как строка, но после разбора сейчас не используется рекламными маршрутами.
`parse_mode`	string	"HTML", "MarkdownV2" или "Markdown". Если указан, добавляет ad_text_formatted: гиперссылку вокруг ad_text в выбранном режиме разметки.
`platform`	string	Тип площадки. По умолчанию: "telegram".

Обязательные поля.

Ответ — реклама получена

200 OK

{
  "has_ad": true,
  "impression_id": "imp_xxx",
  "ad": {
    "format": "image",
    "ad_text": "Try Sidekick",
    "ad_text_formatted": "<a href=\"https://sidekick-ads.com/api/v1/click/imp_xxx\">Try Sidekick</a>",
    "ad_url": "https://sidekick-ads.com/api/v1/click/imp_xxx",
    "button_text": "Try",
    "button_url": "https://sidekick-ads.com/api/v1/click/imp_xxx",
    "media_type": "photo",
    "image_url": "https://cdn.example.com/sidekick/ad.jpg",
    "image_mime": "image/jpeg"
  }
}

media_type принимает значение "photo" или "animation" — используйте sendPhoto или sendAnimation соответственно. ad_text — обычная подпись; ad_text_formatted оборачивает её в ссылку, чтобы подпись была кликабельной. button_url — URL перенаправления для учёта кликов.

Ответ — рекламы нет

200 OK

{ "has_ad": false, "impression_id": null, "ad": null }

Если для площадки или языка нет подходящей кампании с изображением, оба поля равны null. Можно запросить текстовую рекламу через /api/v1/ad/fetch или отправить ответ LLM без рекламы.

Ответы с ошибкой

Статус	Значение
`400`	Обязательное поле отсутствует, значение поля некорректно или platform_id не указывает на площадку этого аккаунта.
`401`	API-ключ отсутствует или недействителен.