API Telegram Delivery Gateway

Публичная документация для интеграции отправки кодов через Telegram и отслеживания статусов доставки.

Base URL: https://telegram-code.ru/api Авторизация: HTTP Basic Auth

Авторизация

Все API-запросы выполняются c HTTP Basic Auth:

Authorization: Basic base64(login:password)

Пара логин/пароль выдаётся отдельно для каждого проекта.

POST /send

Отправка OTP-кода в Telegram. Можно передать код вручную или попросить API сгенерировать его автоматически.

Request JSON

{
  "phone": "+79991234567",
  "code": "493812",
  "ttl": 300
}

Поле	Тип	Обязательно	Описание
`phone`	string	Да	Телефон в международном формате, например `+79991234567`.
`code`	string	Нет	Код 4–8 цифр. Если не передан, API сгенерирует его.
`ttl`	integer	Нет	Время жизни кода в секундах (по умолчанию 300).

Response JSON

{
  "success": true,
  "request_id": "abc123",
  "ttl": 300,
  "cost": "0.01"
}

Если код генерируется API, в ответ добавляется поле code.

GET /status

Возвращает текущий статус доставки для ранее отправленного сообщения.

Request

GET /status?request_id=abc123

Response JSON

{
  "success": true,
  "request_id": "abc123",
  "delivery_status": {
    "status": "delivered",
    "updated_at": 1710000200
  }
}

Статус	Описание
`sent`	Сообщение отправлено на устройство.
`delivered`	Сообщение доставлено.
`read`	Сообщение прочитано.
`expired`	Истёк срок доставки.
`revoked`	Сообщение отозвано.

Ошибки API

HTTP	error	Описание
400	`INVALID_PHONE`	Неверный формат номера телефона.
400	`INVALID_CODE_FORMAT`	Код должен содержать 4–8 цифр.
429	`Too frequent`	Превышен лимит отправки.
400	`TG_ERROR`	Ошибка Telegram Gateway.
401	`Auth required`	Не передана авторизация.
403	`Invalid credentials`	Неверный логин или пароль.

Пример интеграции

1. POST /send
2. Сохранить request_id
3. Показать пользователю форму ввода кода
4. Периодически вызывать GET /status
5. Самостоятельно принять решение по статусу

Поддержка: support@telegram-code.ru