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

Реклама в ответе

POST/api/v1/ad

Передайте текст ответа LLM. Sidekick подберёт подходящее объявление, добавит его к сообщению и вернёт всё одним ответом. Если рекламы нет, сообщение вернётся без изменений.

Авторизация

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Создайте ключи в настройках паблишера.

Тело запроса

Поле	Тип	Описание
`user_id`обязательно	number	ID пользователя Telegram (ctx.from.id): конечное число. Документация Telegram User →
`message`обязательно	string	Непустой текст ответа LLM, в который можно добавить рекламу.
`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 (ctx.chat.id) для групп и супергрупп. Частота «1 реклама на N сообщений» и суточный лимит применяются к чату, а не к пользователю. При ephemeral-отправке (группа + bot_is_admin + rich accept_formats) они действуют для пользователя. В личных чатах не передавайте. Документация Telegram Chat →
`participants_count`	number	Неотрицательное число участников группы; кешируйте getChatMemberCount. Вместе с group_id используется для фильтров по размеру группы и расчёта веса показа. Метод Telegram getChatMemberCount →
`group_name`	string	Необязательное название группы. Проверяется как строка, но после разбора сейчас не используется рекламными маршрутами.
`first_name`	string	Имя пользователя Telegram (ctx.from.first_name). Необязательный сигнал для профилирования аудитории; API сохраняет до 128 символов. Документация Telegram User →
`user_message`	string	Сообщение пользователя, на которое отвечает бот. Может влиять на контекстный подбор, проверку чувствительных тем и профилирование аудитории. API сохраняет до 4096 символов.
`parse_mode`	string	"HTML", "MarkdownV2" или "Markdown". Если указан, рекламный текст экранируется и оформляется гиперссылкой для выбранного режима.
`platform`	string	Тип площадки. По умолчанию: "telegram".
`accept_formats`	string[]	Допустимые форматы: "text", "response", "card", "consent", "quiz". По умолчанию ["text"]. Неизвестные форматы и форматы без нужных возможностей отбрасываются; при пустом результате используется ["text"]. Включите "text", чтобы получать обычные объявления вместе с rich-рекламой.
`capabilities`	object	{ "rich_messages": bool, "callbacks": bool, "custom_emoji": bool } — что умеет отправлять бот. Rich-реклама выдаётся только при наличии нужной возможности. См. раздел «Rich-форматы» ниже.
`bot_is_admin`	boolean	Является ли бот администратором группы (кешированный результат getChatMember). Позволяет показывать первую сцену в группе только целевому пользователю.
`test_rich`	boolean	Для проверки интеграции: по очереди выдаёт образцы rich-кампаний сети, обходя таргетинг и ограничения частоты. Учёт показов, callback и переходы работают по настоящей цепочке. Не включайте в production.

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

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

200 OK

{
  "message": "Python — это высокоуровневый язык программирования...\n\n<a href=\"https://t.me/heysidekick\">Реклама от Sidekick 👇</a>\n\n<a href=\"https://sidekick-ads.com/api/v1/click/imp_a8f3d2c1e9b7\">💡 Попробуй Cursor — AI-редактор для разработчиков</a>",
  "has_ad": true,
  "impression_id": "imp_a8f3d2c1e9b7",
  "ad": {
    "text": "💡 Попробуй Cursor — AI-редактор для разработчиков",
    "formatted_text": "💡 Попробуй <b>Cursor</b> — <a href=\"https://sidekick-ads.com/api/v1/click/imp_a8f3d2c1e9b7\">AI-редактор</a>",
    "button_text": "Попробовать Cursor →",
    "button_url": "https://sidekick-ads.com/api/v1/click/imp_a8f3d2c1e9b7"
  }
}

ad.formatted_text — версия с разметкой для ad.text, уже преобразованная в parse_mode из запроса. Она может содержать ссылки и выделение текста. Используйте её, если собираете рекламное сообщение сами, вместо отправки готового поля message. Она специально не обёрнута ссылкой отслеживания, поскольку вложенные ссылки недопустимы в Telegram. Поэтому клики по тексту не учитываются, а по кнопке — учитываются. Если у кампании нет авторской разметки, поле совпадает с ad.text.

Поле message содержит исходный текст с добавленной рекламой. Объект ad содержит текст кнопки и URL отслеживания кликов — используйте их для inline-кнопки в Telegram.

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

200 OK

{
  "message": "Python — это высокоуровневый язык программирования...",
  "has_ad": false,
  "impression_id": null,
  "ad": null
}

Если подходящей кампании нет, сообщение возвращается без изменений. В обоих случаях используйте поле message .

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

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