API

Spider API — для разработчиков

Получайте сырые данные из Telegram-чатов на свой сервер через вебхуки

Полноценное API и MCP находятся в разработке. Ниже описан формат получения уведомлений через вебхуки.

Как подключиться

Уже сейчас вы можете получать сырые данные (сообщения из чатов) на свой сервер. Для этого отправьте нашему менеджеру:

Список ключевых слов
Список слов-исключений
URL вашего вебхука (HTTPS-эндпоинт, принимающий POST-запросы)

После настройки сервис начнёт отправлять на ваш вебхук все совпавшие сообщения в реальном времени. Средняя задержка от момента захвата сообщения - около 4.2 секунды.

В режиме API вся ответственность за обработку и категоризацию сообщений лежит на вашей стороне. Мы отдаём сырые данные — вы решаете, что с ними делать.

Лимиты

Для защиты от слишком широких ключевых слов (и от случайных ошибок в настройках) действуют ограничения:

Лимит	Значение
Сообщений в сутки	100
Сообщений в месяц	3 000

При превышении любого из лимитов доставка приостанавливается, и на вебхук приходит событие limit_reached. Сброс суточного лимита — в 00:00 UTC.

Вебхук

При каждом совпавшем сообщении на ваш URL приходит POST-запрос с телом в формате JSON.

Пример запроса

HTTP

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Spider-Token: your_secret_token_here

JSON Тело запроса

{
  "event": "new_message",
  "data": {
    "text": "Подскажите, где можно арендовать байк на месяц?",
    "chat_id": 1847205913,
    "user_id": 590123847,
    "country": "ID",
    "city": "Bali",
    "date": 1752498127
  }
}

Описание полей

Поле	Тип	Описание
`event`	string	`new_message` — новое сообщение, `limit_reached` — лимит исчерпан
`data.text`	string	Текст сообщения из чата
`data.chat_id`	integer	ID чата в Telegram
`data.user_id`	integer	ID автора сообщения в Telegram
`data.country`	string	Код страны (ISO 3166-1 alpha-2)
`data.city`	string	Город / остров / район
`data.date`	integer	Время сообщения в Telegram (Unix time, секунды)

В текущей реализации имена чатов и имена пользователей не передаются — данные обезличены.

Ответ вашего сервера

Ожидаем HTTP 200 в ответ. Повторные попытки доставки мы не делаем — убедитесь, что ваш эндпоинт стабильно доступен.

Событие `limit_reached`

При исчерпании лимита отправка сообщений приостанавливается. Вместо очередного сообщения вы получите одно статусное уведомление:

JSON limit_reached

{
  "event": "limit_reached",
  "data": {
    "reason": "daily_limit",
    "messages_today": 100,
    "messages_this_month": 2870,
    "resets_at": "2025-07-15T00:00:00Z"
  }
}

Значение `reason`	Описание
`daily_limit`	Достигнут суточный лимит (100 сообщений)
`monthly_limit`	Достигнут месячный лимит (3 000 сообщений)

После сброса лимита отправка возобновляется автоматически.

Стоимость

API-доступ оплачивается отдельно от стандартной подписки Spider. Уточняйте тариф у менеджера.

Аутентификация

Каждый запрос к вашему вебхуку содержит заголовок с секретным токеном:

HTTP Header

X-Spider-Token: your_secret_token_here

Токен выдаётся при подключении. Рекомендуем проверять его на вашей стороне и отклонять запросы с невалидным или отсутствующим токеном (HTTP 401).

Вопросы и подключение

Напишите менеджеру — поможем настроить интеграцию.

Написать менеджеру