> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Посібник із використання проксі акаунта Telegram

> Telegram Account Proxy API guide - Ace Data Cloud

Проксі акаунта Telegram надає незалежні, постійні MCP і REST інтерфейси для вашого особистого акаунта Telegram. Кожен екземпляр обслуговує лише один акаунт; контейнер не містить AI, а сеанс входу зберігається в окремому постійному томі цього екземпляра.

> Це не бот Telegram Bot API. Будь ласка, не використовуйте його для спаму, масових холодних розсилок або обходу обмежень Telegram. Перед надсиланням, редагуванням або видаленням вмісту третім особам ваш Agent повинен отримати явне підтвердження.

## Розгортання та вхід

1. У [консолі → застосунки](https://platform.acedata.cloud/console/applications) створіть проксі акаунта Telegram, після оформлення підписки натисніть розгорнути. Ресурси екземпляра автоматично налаштовуються платформою.
2. Після готовності екземпляра натисніть «Згенерувати QR-код для входу». QR-код дійсний протягом короткого часу, після завершення строку дії його можна згенерувати повторно.
3. У Telegram відкрийте **Налаштування → Пристрої → Підключити пристрій для комп’ютера** та відскануйте QR-код.
4. Якщо статус зміниться на `password_required`, введіть у консолі пароль двоетапної перевірки Telegram. Пароль надсилається лише до екземпляра вашого тенанта й не записується в конфігурацію платформи.
5. Після зміни статусу на `authenticated` консоль відобразить поточний акаунт, MCP-адресу та Bearer токен доступу.

Авторизований сеанс зберігається в постійному томі та повторно використовується під час звичайних перезапусків і оновлень. Опція консолі «Вийти з акаунта» викликає `/api/auth/logout` для відкликання сеансу Telegram; «Знищити екземпляр» також видаляє робоче навантаження та постійний том.

## Автентифікація та перевірка стану

Окрім `/health` і `/readyz`, інтерфейси входу, REST і MCP усі вимагають:

```text theme={null}
Authorization: Bearer <访问令牌>
```

Сервіс приймає автентифікацію лише через заголовок запиту та не підтримує додавання токена до URL. Захищайте його так само, як пароль від акаунта.

```bash theme={null}
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz
```

`/health` лише означає, що HTTP-процес працює:

```json theme={null}
{"status":"ok"}
```

`/readyz` означає, чи доступне MTProto-з’єднання. Під час підключення повертається HTTP 200, навіть якщо акаунт усе ще сканує QR-код або очікує двоетапної перевірки:

```json theme={null}
{"status":"ready","gateway_connected":true,"login_state":"login_required"}
```

У разі розриву з’єднання пряме зондування Kubernetes до Pod повертає HTTP 503, а екземпляр автоматично перепідключається у фоновому режимі. У цей час Pod буде тимчасово вилучено з публічного Service, тому не гарантується можливість прочитати діагностичний JSON через домен екземпляра; будь ласка, зачекайте в консолі, доки Deployment знову стане Ready. Поширені значення `login_state` включають `login_required`, `waiting_scan`, `password_required`, `authenticated`; перед виконанням операцій із повідомленнями акаунта все одно потрібно досягти `authenticated`.

## Підключення MCP-клієнта

### Claude Code

```bash theme={null}
claude mcp add \
  --transport http \
  --header "Authorization: Bearer <访问令牌>" \
  telegram \
  https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp
```

### Cursor та інші клієнти, що підтримують статичні заголовки запитів

Налаштуйте адресу Streamable HTTP відповідно до поточної документації клієнта та додайте заголовок запиту `Authorization`. Наприклад, клієнти, що підтримують наведену нижче структуру, можуть використати:

```json theme={null}
{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer <访问令牌>"}
    }
  }
}
```

Це не універсальний формат конфігурації для всіх MCP-клієнтів. Віддалений конектор Claude Desktop / Claude.ai встановлюється з хмари та не зчитує жодних HTTP-заголовків запитів із локального `claude_desktop_config.json`; якщо наразі потрібен статичний Bearer заголовок запиту, використовуйте Claude Code або клієнт, що явно підтримує цю можливість.

## Інструменти MCP

| Інструмент | Призначення |
| - | - |
| `telegram_whoami` | Переглянути поточний авторизований акаунт |
| `telegram_list_chats` | Вивести список останніх чатів, можна переглянути лише непрочитані |
| `telegram_contacts` | Вивести список контактів |
| `telegram_read_messages` | Прочитати останні повідомлення вказаного чату |
| `telegram_search_messages` | Шукати в одному чаті або в усіх чатах |
| `telegram_send_message` | Надіслати повідомлення, можна відповісти на вказане повідомлення |
| `telegram_edit_message` | Редагувати повідомлення, надіслані поточним акаунтом |
| `telegram_delete_message` | Видалити повідомлення, які дозволено видаляти |
| `telegram_react` | Реагувати на повідомлення Unicode-емодзі |
| `telegram_mark_read` | Позначити чат як прочитаний |

`target` може бути ID чату, іменем користувача або **точною** назвою чату; якщо назва неоднозначна, переважно використовуйте ID або ім’я користувача.

## REST API

Усі успішні відповіді використовують `{"data": ...}`, а відповіді з помилками використовують `{"error": "..."}`.

### Приклади

```bash theme={null}
# 当前账号
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

# 最近会话
curl "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/chats?limit=20&unread_only=false" \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

# 给 Saved Messages 发一条测试消息
curl -X POST https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"me","text":"Hello from my Telegram proxy"}'
```

### Повний список інтерфейсів

| Метод і шлях | Основні параметри | Призначення |
| - | - | - |
| `POST /api/auth/qr` | — | Згенерувати URL QR-коду для входу |
| `GET /api/auth/status` | — | Перевірити статус входу та інформацію про акаунт |
| `POST /api/auth/password` | `{password}` | Надіслати пароль двоетапної перевірки |
| `POST /api/auth/logout` | — | Відкликати збережений екземпляром сеанс |
| `GET /api/whoami` | — | Переглянути поточний акаунт |
| `GET /api/chats` | `?limit=&unread_only=` | Вивести список чатів і кількість непрочитаних |
| `GET /api/contacts` | — | Вивести список контактів |
| `GET /api/chats/{target}/messages` | `?limit=` | Прочитати повідомлення |
| `GET /api/messages/search` | `?q=&target=&limit=` | Шукати повідомлення; якщо не вказано target, пошук виконується між чатами |
| `POST /api/messages` | `{target,text,reply_to?}` | Надіслати повідомлення або відповідь |
| `PATCH /api/chats/{target}/messages/{message_id}` | `{text}` | Редагувати повідомлення |
| `DELETE /api/chats/{target}/messages/{message_id}` | — | Видалити повідомлення |
| `POST /api/chats/{target}/messages/{message_id}/reactions` | `{emoji}` | Додати реакцію Unicode-емодзі |
| `POST /api/chats/{target}/read` | — | Позначити чат як прочитаний |

## Поширені запитання

* **401**: Bearer токен відсутній або неправильний. Переконайтеся, що токен розміщено в заголовку запиту, а не в параметрах URL-запиту.
* **503**: Токен доступу проксі не налаштовано, або клієнт Telegram ще не готовий. Спочатку перевірте `/readyz`; якщо токен доступу проксі не налаштовано, захищені інтерфейси також повертатимуть 503.
* **400**: Параметри або JSON недійсні; для пошуку обов’язково потрібно надати `q`, `limit` має бути цілим числом, більшим або рівним 1.
* **403 / 404**: Поточний акаунт не має дозволу, або target / message ID не існує.
* **429**: Спрацьовує обмеження частоти Telegram. Прочитайте `retry_after` і зачекайте, не виконуйте повторних спроб паралельно.
* **QR-код постійно не завершено**: Згенеруйте QR-код повторно та переконайтеся, що використовується точка входу сканування Telegram «Підключити пристрій для комп’ютера».
* **Після перезапуску потрібно знову увійти**: Перевірте, чи нормально працює постійний том інстансу; після активного виходу, відкликання сеансу в списку пристроїв Telegram або втрати чинності сеансу потрібно повторно сканувати код.

## Обсяг перевірки

Вихідний код і автоматизовані тести охоплюють стан входу, fail-close Bearer, перевірку REST-параметрів, зіставлення помилок і реалізацію постійного зберігання сеансу. У виробничому використанні все одно слід спочатку завершити smoke-перевірки лише для читання та створення/редагування/видалення повідомлень у `target=me` (Saved Messages), перш ніж дозволяти Agent керувати сеансами третіх сторін.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.