Bot API

Bot API Docs

Публичный справочник по owner-side управлению и bot-token runtime endpoint-ам.

Все endpoint-ыOwnerBot runtimeWebhooksLong pollingTS SDKOpenAPI JSONRedocSwagger UI
Список ботов
OwnerGET/v1/bot-api/bots

Возвращает всех ботов текущего owner-аккаунта.

Авторизация: Bearer owner token

Статусы
200Возвращает всех ботов текущего owner-аккаунта.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots
JSON response
{
  "items": [
    {
      "bot_user_id": "b63c...",
      "created_at": "2026-04-21T10:00:00Z",
      "description": "Publishes Russia news",
      "display_name": "News Bot Russia",
      "id": "7f9d...",
      "owner_user_id": "25c0...",
      "updated_at": "2026-04-21T10:30:00Z",
      "username": "newsbot_russia_v1",
      "webhook_url": "https://bot.example.test/webhook"
    }
  ]
}
Создать бота
OwnerPOST/v1/bot-api/bots

Создаёт нового бота и один раз возвращает стартовый токен.

Авторизация: Bearer owner token

Статусы
201Создаёт нового бота и один раз возвращает стартовый токен.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/bots \
  -H "Authorization: Bearer <owner_token>" \
  -H "Content-Type: application/json" \
  -d '{"username":"news_tatarstan_bot","display_name":"News Bot","description":"Publishes verified news"}'
JSON request
{
  "description": "Publishes verified news",
  "display_name": "News Bot",
  "username": "news_tatarstan_bot"
}
JSON response
{
  "bot": {
    "bot_user_id": "b63c...",
    "created_at": "2026-04-21T10:00:00Z",
    "description": "Publishes verified news",
    "display_name": "News Bot",
    "id": "7f9d...",
    "owner_user_id": "25c0...",
    "updated_at": "2026-04-21T10:00:00Z",
    "username": "news_tatarstan_bot"
  },
  "token": {
    "created_at": "2026-04-21T10:00:00Z",
    "token": "bot_..."
  }
}
Получить бота
OwnerGET/v1/bot-api/bots/{id}

Возвращает одного бота текущего owner-аккаунта.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Возвращает одного бота текущего owner-аккаунта.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>
JSON response
{
  "bot_user_id": "b63c...",
  "created_at": "2026-04-21T10:00:00Z",
  "description": "Publishes Russia news",
  "display_name": "News Bot Russia",
  "id": "7f9d...",
  "owner_user_id": "25c0...",
  "updated_at": "2026-04-21T10:30:00Z",
  "username": "newsbot_russia_v1",
  "webhook_url": "https://bot.example.test/webhook"
}
Список привязанных каналов
OwnerGET/v1/bot-api/bots/{id}/channels

Возвращает каналы, привязанные к одному боту.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Возвращает каналы, привязанные к одному боту.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/channels
JSON response
{
  "items": [
    {
      "bot_role": "moderator",
      "created_at": "2026-04-21T10:00:00Z",
      "description": "Owned channel for bot publishing",
      "id": "22d6...",
      "slug": "news-russia",
      "title": "News Russia"
    }
  ]
}
Привязать бота к каналу
OwnerPOST/v1/bot-api/bots/{id}/channels/{channelId}

Привязывает бота к одному owned channel с ролью moderator.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
channelIdpath · requiredChannel identifier.
Статусы
200Привязывает бота к одному owned channel с ролью moderator.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/bots/<bot_id>/channels/<channel_id> \
  -H "Authorization: Bearer <owner_token>"
JSON response
{
  "attached_by": "25c0...",
  "bot_id": "7f9d...",
  "channel_id": "22d6...",
  "role": "moderator"
}
Статистика бота
OwnerGET/v1/bot-api/bots/{id}/stats

Возвращает счётчики очереди и delivery по одному боту.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Возвращает счётчики очереди и delivery по одному боту.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/stats
JSON response
{
  "attached_channel_count": 2,
  "bot_id": "7f9d...",
  "delivered_updates": 16,
  "last_attempted_at": "2026-04-21T10:42:02Z",
  "last_delivered_at": "2026-04-21T10:42:02Z",
  "last_update_at": "2026-04-21T10:42:00Z",
  "pending_updates": 1,
  "scheduled_retries": 1,
  "terminal_failed_updates": 1,
  "total_updates": 18
}
Повернуть bot token
OwnerPOST/v1/bot-api/bots/{id}/token

Выпускает новый bot token и инвалидирует предыдущий.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Выпускает новый bot token и инвалидирует предыдущий.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/bots/<bot_id>/token -H "Authorization: Bearer <owner_token>"
JSON response
{
  "created_at": "2026-04-21T10:30:00Z",
  "token": "bot_..."
}
Последние update
OwnerGET/v1/bot-api/bots/{id}/updates

Возвращает последние bot_api_updates rows с payload и delivery state.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
limitquery · optionalMaximum number of items to return.
Статусы
200Возвращает последние bot_api_updates rows с payload и delivery state.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/updates?limit=20
JSON response
{
  "items": [
    {
      "created_at": "2026-04-21T10:42:00Z",
      "delivered_webhook_at": "2026-04-21T10:42:02Z",
      "event_type": "channel.post_created",
      "last_attempted_at": "2026-04-21T10:42:02Z",
      "last_delivery_error": "",
      "payload": {
        "body": "Owner update for history",
        "channel_id": "22d6...",
        "post_id": "90ab..."
      },
      "update_id": 41,
      "webhook_attempt_count": 1
    }
  ]
}
Получить webhook config
OwnerGET/v1/bot-api/bots/{id}/webhook

Возвращает webhook URL, наличие секрета и delivery health.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Возвращает webhook URL, наличие секрета и delivery health.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook
JSON response
{
  "has_secret_token": true,
  "last_attempted_at": "2026-04-21T10:42:02Z",
  "last_delivered_at": "2026-04-21T10:42:02Z",
  "last_delivery_error": "",
  "next_retry_at": null,
  "pending_update_count": 0,
  "url": "https://bot.example.test/webhook"
}
Обновить webhook config
OwnerPUT/v1/bot-api/bots/{id}/webhook

Устанавливает webhook URL и необязательный secret token.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Устанавливает webhook URL и необязательный secret token.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X PUT https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook \
  -H "Authorization: Bearer <owner_token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.test/webhook","secret_token":"secret-123"}'
JSON request
{
  "secret_token": "secret-123",
  "url": "https://bot.example.test/webhook"
}
JSON response
{
  "has_secret_token": true,
  "last_attempted_at": "2026-04-21T10:42:02Z",
  "last_delivered_at": "2026-04-21T10:42:02Z",
  "last_delivery_error": "",
  "next_retry_at": null,
  "pending_update_count": 0,
  "url": "https://bot.example.test/webhook"
}
Удалить webhook config
OwnerDELETE/v1/bot-api/bots/{id}/webhook

Отключает webhook delivery для одного бота.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
Статусы
200Отключает webhook delivery для одного бота.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X DELETE https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook -H "Authorization: Bearer <owner_token>"
JSON response
{
  "status": "ok"
}
Лог ошибок webhook
OwnerGET/v1/bot-api/bots/{id}/webhook/errors

Возвращает конкретные ошибки webhook delivery.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
limitquery · optionalMaximum number of items to return.
Статусы
200Возвращает конкретные ошибки webhook delivery.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <owner_token>" https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook/errors?limit=20
JSON response
{
  "items": [
    {
      "created_at": "2026-04-21T10:52:00Z",
      "event_type": "channel.post_created",
      "last_attempted_at": "2026-04-21T10:52:02Z",
      "last_delivery_error": "500 Internal Server Error",
      "next_retry_at": "2026-04-21T10:52:04Z",
      "update_id": 44,
      "webhook_attempt_count": 1
    }
  ]
}
Перекинуть failed deliveries в replay
OwnerPOST/v1/bot-api/bots/{id}/webhook/replay

Возвращает failed rows обратно в delivery queue.

Авторизация: Bearer owner token

Параметры
idpath · requiredBot identifier.
limitquery · optionalMaximum number of failed updates to requeue.
Статусы
200Возвращает failed rows обратно в delivery queue.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
404Referenced resource was not found.
429Rate limit exceeded.
curl
curl -X POST "https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook/replay?limit=100" \
  -H "Authorization: Bearer <owner_token>"
JSON response
{
  "bot_id": "7f9d...",
  "max_window": 6,
  "requeued": 3
}
Каналы бота
Bot tokenGET/v1/bot-api/channels

Список каналов, доступных текущему bot token.

Авторизация: Bearer bot token

Статусы
200Список каналов, доступных текущему bot token.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <bot_token>" https://api.yullama.ru/v1/bot-api/channels
JSON response
{
  "items": [
    {
      "bot_role": "moderator",
      "created_at": "2026-04-21T10:00:00Z",
      "description": "Owned channel for bot publishing",
      "id": "22d6...",
      "slug": "news-russia",
      "title": "News Russia"
    }
  ]
}
Создать пост в канале
Bot tokenPOST/v1/bot-api/channels/{id}/posts

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

Авторизация: Bearer bot token

Параметры
idpath · requiredAttached channel identifier.
Статусы
201Публикует пост от имени бота в привязанный канал.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
403Authenticated but not allowed to perform this action.
429Rate limit exceeded.
curl
curl -X POST https://api.yullama.ru/v1/bot-api/channels/<channel_id>/posts \
  -H "Authorization: Bearer <bot_token>" \
  -H "Content-Type: application/json" \
  -d '{"body":"Bot API production news update"}'
JSON request
{
  "body": "Bot API production news update"
}
JSON response
{
  "author_username": "newsbot_russia_v1",
  "body": "Bot API production news update",
  "channel_id": "22d6...",
  "created_at": "2026-04-21T10:55:00Z",
  "id": "90ab..."
}
Текущий бот
Bot tokenGET/v1/bot-api/me

Возвращает identity текущего бота по bot token.

Авторизация: Bearer bot token

Статусы
200Возвращает identity текущего бота по bot token.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <bot_token>" https://api.yullama.ru/v1/bot-api/me
JSON response
{
  "bot_user_id": "b63c...",
  "display_name": "News Bot Russia",
  "id": "7f9d...",
  "username": "newsbot_russia_v1"
}
Получить updates polling-ом
Bot tokenGET/v1/bot-api/updates

Забирает bot events через offset/limit/timeout polling.

Авторизация: Bearer bot token

Параметры
offsetquery · optionalReturn updates with `update_id > offset`.
limitquery · optionalMaximum number of items to return.
timeoutquery · optionalLong polling timeout in seconds. Current maximum is 30 seconds.
Статусы
200Забирает bot events через offset/limit/timeout polling.
400Malformed input or invalid parameter value.
401Missing or invalid bearer token.
429Rate limit exceeded.
curl
curl -H "Authorization: Bearer <bot_token>" "https://api.yullama.ru/v1/bot-api/updates?offset=0&limit=50&timeout=30"
JSON response
{
  "items": [
    {
      "created_at": "2026-04-21T10:42:00Z",
      "event_type": "channel.post_created",
      "payload": {
        "body": "Owner published to channel",
        "channel_id": "22d6...",
        "post_id": "90ab..."
      },
      "update_id": 41
    }
  ]
}