EVIR API

API для выдачи спонсорских карточек в Telegram-боте

Сначала проверьте ключ через ping, затем запросите assignments через next, отправьте карточку в Telegram и следуйте флагам ответа.

Полная инструкция Webhooks

Base URL: https://evir.me/api/v1/integrations
JSON over HTTPS
Повтор delivery без двойного расчёта

Авторизация

Откройте карточку бота → «Подключение», создайте EVIR API key и сохраните его только на backend вашего бота.

Authorization: Bearer EVIR_API_KEY
Content-Type: application/json

Все пути ниже — HTTP endpoints, а не Telegram-команды. Чаты подключаются отдельно через @EvirBot и не используют этот ключ.

Проверка ключа за 60 секунд

Первым запросом вызовите POST /api/v1/integrations/ping с пустым JSON-телом.

curl -X POST https://evir.me/api/v1/integrations/ping \
  -H "Authorization: Bearer EVIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Успешный ответ: { "data": { "connected": true }, "meta": { "requestId": "..." } }.

Минимальный запрос карточки

recipientId — точно Telegram from.id строкой: String(message.from.id) в Node.js или str(message.from_user.id) в Python. chat.id не подходит.

curl -X POST https://evir.me/api/v1/integrations/next \
  -H "Authorization: Bearer EVIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipientId":"123456789"}'

limit можно не передавать: по умолчанию он равен 1. Допустимы только целые значения 1–10.

Пример полного ответа next

{
  "data": {
    "assignments": [{
      "deliveryId": "AbCdEfGhIjKlMnOpQrStUvWxYz012345",
      "title": "Заголовок",
      "description": "Текст карточки",
      "ctaLabel": "Открыть",
      "actionUrl": "https://evir.me/api/v1/r/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
      "allowSkip": false,
      "topicCode": "technology",
      "targetType": "channel",
      "targetUsername": "example_channel",
      "expiresAt": "2026-09-04T12:05:00.000Z",
      "productType": "impression",
      "requiresServedAck": true,
      "requiresQualification": false
    }]
  },
  "meta": { "requestId": "http-request-id" }
}

productType: recommendation | impression | transition | op; ctaKind: subscribe | start | open. Эти поля и requiresServedAck / requiresQualification могут отсутствовать у legacy-рекомендаций. assignments: [] — нормальный успешный ответ: продолжите обычный сценарий бота.

Что делать после ответа next

Отправьте карточку

Используйте title, description и Telegram-кнопку ctaLabel → actionUrl.

POST /api/v1/integrations/deliveries/{deliveryId}/served

Подтвердите отправку

Вызывайте с телом {} только при requiresServedAck: true и только после успешной отправки Telegram.

POST /api/v1/integrations/deliveries/{deliveryId}/qualify

Подтвердите действие

Вызывайте при requiresQualification: true после действия получателя; в теле передайте тот же recipientId.

Доверяйте флагам

requiresServedAck и requiresQualification определяют следующий шаг. Не выводите его только из productType.

Ошибки и повторы

401

Ключ отсутствует, неверный или был заменён.

404

deliveryId не найден или срок подтверждения закончился.

409

Прочитайте error.code и message: для DELIVERY_NOT_READY повторите HTTP-запрос next позже; для OP_* покажите сообщение и оставьте кнопку «Проверить».

429 / 5xx

Учтите Retry-After и повторите запрос для того же recipient или delivery. Не создавайте новую отправку при неизвестном результате Telegram.

Помощь

Частые вопросы

Все вопросы

Можно вызывать API из frontend?

Нет. EVIR API key должен оставаться на сервере вашего бота.

Какие форматы доступны через API?

ОП, переходы и показы можно включить сразу после подключения в «Способах заработка». HTTP endpoint next возвращает готовые текст и кнопку; дальше следуйте requiresServedAck и requiresQualification.

Можно подключить чат через API?

Нет. Чат подключается в разделе «Заработок» через @EvirBot; API key используется только сервером подключённого бота.

API-бот получает Premium-таргетинг?

Нет. Сервер издателя не может доказать Premium пользователя. Такой фильтр работает только там, где статус приходит в EVIR напрямую от Telegram.

Что делать, если assignments пустой?

Сначала проверьте, что в «Способах заработка» включён хотя бы один формат. Затем покажите обычный сценарий бота или настроенный empty state: пустой результат также возможен, когда подходящих предложений сейчас нет.

Можно повторить served?

Да. Повторите POST для того же delivery id. Уже рассчитанный результат не создаёт второе списание или начисление.

Следующий шаг

Готовы подключить EVIR?

Начните с готового примера или откройте полный API.

Полная инструкция