Взаимодействия
Аутентификация
Используйте Bearer API-ключ того же паблишера, который получил первоначальное объявление.
Authorization: Bearer YOUR_API_KEY
POST /api/v1/ad/interact — запрос
| Поле | Тип | Описание |
|---|---|---|
tokenобязательно | string | Подписанный токен между первыми двумя двоеточиями в sk:<token>:<payload>. Используйте API-ключ паблишера, которому был выдан этот показ. |
payloadобязательно | string | Действие после второго двоеточия, от 1 до 32 символов. Может содержать другие двоеточия; передавайте без изменений. |
user_idобязательно | number | ID пользователя Telegram, нажавшего кнопку (callback_query.from.id). |
chat_type | string | "private", "group" или "supergroup" (callback_query.message.chat.type). По умолчанию "private". Определяет отправку последующих сцен только нажавшему пользователю в группе. |
callback_query_id | string | ID callback-запроса Telegram. Используется для новой ephemeral-отправки после нажатия в группе. Клиент также должен вызвать answerCallbackQuery. |
ephemeral_message_id | number | Числовой ID ephemeral-сообщения из callback, если он есть. Позволяет изменить сообщение на месте. |
capabilities | object | Те же возможности, что и в /ad. Без custom_emoji используется название бренда жирным шрифтом. SDK берёт последние capabilities, переданные в inject(). |
Обязательные поля.
Ответ и отправка
Успешный ответ содержит ok, interaction, send и delivery. Передайте send.method и send.params в Telegram, дополнив адресат из callback-события.
- Личный чат: delivery.mode — edit, send.method — editMessageText. Добавьте chat_id и message_id.
- Новая сцена в группе: delivery.mode — ephemeral_new. Сохраните ephemeral_message_parameters при вызове sendRichMessage и добавьте chat_id.
- Существующее ephemeral-сообщение: delivery.mode — ephemeral_edit, send.method — editEphemeralMessageText. Сохраните receiver_user_id и ephemeral_message_id.
Клиент должен подтвердить callback через answerCallbackQuery, в том числе при обработанной ошибке. При сбое ephemeral-сцену нельзя повторно отправлять публично в группу.
Ошибки
| Статус | Значение |
|---|---|
400 | Некорректный user_id, пустой payload, payload длиннее 32 символов или неподдерживаемое действие. |
401 | API-ключ отсутствует или недействителен. |
403 | Токен отсутствует или недействителен либо показ принадлежит другому паблишеру. |
404 | Показ не найден, кампания отсутствует или её rich-формат либо настройки недоступны. |
429 | Превышен лимит: 30 запросов на один показ за 24 часа. |