Gateway API · Боты

Партнёрская документация — управляемые Telegram-аккаунты

Base URL
api/v1/gateway
v1.1 · Bearer

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

Каждый запрос — с заголовком Authorization: Bearer <token>. Для POST — Content-Type: application/json.

Base URL

https://telegramilti.com/api/v1/gateway

Внимание: путь именно с префиксом /api/v1/gateway (короткий /gateway/… → 404). Не путать с /api/v1/accounts — там другая авторизация (по owner_user_id, без Bearer); gateway-токен туда слать нельзя (Session is invalid).

Эндпоинты

GET/bots

Список всех управляемых аккаунтов.

Запрос

curl -sS "https://telegramilti.com/api/v1/gateway/bots" \
  -H "Authorization: Bearer $TOKEN"

Ответ

{ "bots": [ Bot, … ] }

POST/bots/get

Один аккаунт по bot_tg_id.

Запрос

curl -sS "https://telegramilti.com/api/v1/gateway/bots/get" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_tg_id":"8160200298"}'

Ответ — объект Bot (404, если не найден)

POST/bots/sleep/bots/wake

Ротация: усыпить аккаунт (AUTO-выбор его пропустит; явный вызов по bot_tg_id всё равно сработает) / разбудить.

Усыпить

curl -sS "…/api/v1/gateway/bots/sleep" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"bot_tg_id":"816…","seconds":300}'

# разбудить: POST /bots/wake  {"bot_tg_id":"816…"}

Ответ

{ "bot_tg_id":"…", "sleeping":true|false, "sleep_until":<ts>|null }

Объект Bot

{
  "bot_tg_id": "8160200298",
  "username": "solo_lux_man",
  "display_name": "Snowy",
  "is_premium": false,
  "status": "available",
  "status_reason": null,
  "flood_wait_until": null,
  "sleep_until": null,
  "meta": { "internal_account_id": "…", "phone": "+8190…" },
  "last_seen_at": 1783071435
}

Поле	Тип	Описание
bot_tg_id	string	Telegram user id (числом). Если не резолвнулся — придёт внутренний UUID + `status=unknown`: не использовать.
username	string · null	@username без «@».
display_name	string · null	Имя профиля.
is_premiumNEW	bool	Есть ли у аккаунта Telegram Premium.
status	enum	`available` · `unavailable` · `unknown`
status_reason	string · null	Причина, когда не available (см. ниже).
flood_wait_until	int · null	Unix ts (сек) — до конца флуд-ожидания.
sleep_until	int · null	Unix ts (сек) — окно «сна»/ротации.
meta	object	`internal_account_id`, `phone`.
last_seen_at	int · null	Unix ts (сек) последней проверки.

Статусы

available — можно таргетить.

unavailable — временно нельзя; смотри status_reason:

flood_waitlimitedfrozenbanneddeadauth_requiredsleeping

unknown — состояние неизвестно (unresolved — не резолвнулся tg id, либо error). Не таргетить.

Коды ошибок

401 нет / невалидный / отозванный токен 404 бот не найден 422 ошибка валидации тела 429 rate-limit (заголовок Retry-After, сек)

Ретрай упавшей операции = НОВЫЙ operation_id. Операции идемпотентны по id: повтор со старым id вернёт тот же (в т.ч. failed) результат, а не новую попытку. На транзиентных кодах (см. ниже) генерируй свежий UUID.

Коды операции — operation.error.code

код	что значит	что делать
`flood_wait`	слишком часто	ждать `retry_after` сек → повтор (новый id)
`slowmode_wait`	slow mode в чате	ждать `retry_after` сек → повтор
`peer_flood`	анти-спам ограничил бот-аккаунт	НЕ ретраить — дать боту отдохнуть (~сутки) / слать с другого бота
`premium_required`	получатель принимает ЛС только от Premium	слать с Premium-бота, иначе пропустить
`privacy_restricted`	получатель закрыл ЛС от незнакомых	достучаться нельзя — пропустить
`user_blocked`	получатель заблокировал бота	пропустить (терминально)
`chat_write_forbidden`	нет прав писать / нужен админ	выдать права боту / сменить чат
`chat_restricted`	чат приватный / недоступен боту	вступить или слать из бота-участника
`peer_not_resolved`	не резолвится получатель / username / id	проверить username/id; для чата — вступить ботом
`source_context_unavailable`	бот не знает исходный чат	`/bots/join-chat` или слать из бота-участника
`source_message_unavailable`	бот не участник — не читает исходное сообщение	`allow_join=true` или бот-участник
`account_banned`	сам бот забанен Telegram	заменить бот-аккаунт (терминально)
`reauth_required`	сессия бота недействительна	перелогинить бот-аккаунт
`invite_invalid`	инвайт-ссылка недействительна	проверить ссылку
`chatlist_limit`	лимит Telegram (папки / ссылки / чаты)	снять Premium-ботом / уменьшить
`filter_invalid`	неверный chat-folder	проверить параметры папки
`reaction_invalid`	неверная реакция	проверить эмодзи
`validation_failed`	неверные данные запроса	проверить тело запроса
`operation_conflict`	уже участник / конфликт состояния	не ошибка — прочитать статус
`mtproto_error`	временный сбой Telegram	повтор позже (новый id)
`unexpected_error`	ошибка на нашей стороне	повтор; если повторяется — в поддержку с `operation_id`

Вступление в чат · subscribe

Когда отправка вернула source_context_unavailable, в error приходит подсказка suggested_action: "join_source_chat" + join_chat_peer_id. Аккаунт вступает в этот чат и повторяет отправку.

POST/bots/join-chat

Запрос — по @username или инвайт-ссылке. Идемпотентна по operation_id (повтор с тем же id вернёт тот же оп).

{
  "operation_id": "<uuid>",
  "bot_tg_id": "8160200298",
  "chat": { "type": "username", "username": "source_channel" }
  // либо: "chat": { "type": "invite_link", "invite_link": "https://t.me/+abc…" }
}

Ответ

{
  "operation": { "type":"join_chat", "status":"succeeded", // pending|running|succeeded|failed
                 "error":null, "result":{…}, "created_at":…, "updated_at":… },
  "membership": { "chat_peer_id":"…", "status":"joined", … } // null, если ещё нет
}

@combot и чаты с аппрувом: вступление уходит заявкой → membership.status = "join_request_sent", ждём ручного одобрения. Обойти нельзя — это гейт на стороне Telegram. Как одобрят — статус станет joined, тогда повторяй отправку.

Статусы membership: joinedjoiningjoin_request_sentbannedrestrictedunknown

Приватные диалоги · Bot API

Чтение входящих ЛС аккаунтов через Bot API (в обход MTProto) — для быстрых ответов бота.

POST/private-dialogs/list

Список диалогов (собеседников).

// body: { "bot_tg_id":"…"?, "limit":50, "offset":0 }
// resp: { "dialogs": [ { bot_tg_id, user_tg_id, username, source, related_chat_peer_id, last_message_at } ] }

POST/private-dialogs/messages

Сообщения одного диалога.

// body: { "bot_tg_id":"…", "user_tg_id":"…", "from_tg_message_id":null?, "to_tg_message_id":null? }
// resp: { "dialog_info":{…}, "messages":[ { sender:{type:"bot|user",tg_id}, tg_message_id, text, entities:[], sent_at, received_at } ] }

POST/private-dialogs/messages/feed

Лента новых сообщений по окну времени сохранения (для поллинга входящих).

// body: { "stored_after":<ts>, "stored_before":<ts>, "bot_tg_ids":["…"]?, "limit":1000, "offset":0 }
// resp: { "messages":[ { bot_tg_id, user_tg_id, stored_at, sender, tg_message_id, text, entities, sent_at, received_at } ] }

TG Manager Gateway API · Bearer-token · telegramilti.com