Telegram Account Proxy User Guide

The Telegram account proxy provides an independent, permanent MCP and REST interface for your personal Telegram account. Each instance serves only one account; the container does not contain AI, and the login session is stored in the independent persistent volume of that instance.

This is not the Telegram Bot API. Do not use it for spam messages, bulk cold sending, or bypassing Telegram restrictions. Before sending, editing, or deleting content to third parties, explicit confirmation should be obtained from your Agent.

Create a Telegram account proxy in Console → Applications and select resource specifications.
Once the instance is ready, click "Generate Login QR Code." The QR code is valid for a short time and can be regenerated after expiration.
Open Settings → Devices → Link Desktop Device in Telegram and scan the QR code.
If the status changes to password_required, enter the Telegram two-step verification password in the console. The password is only submitted to your tenant instance and will not be written to the platform configuration.
After the status changes to authenticated, the console displays the current account, MCP address, and Bearer access token.

The authorized session is stored in the persistent volume, and normal restarts and upgrades will reuse it. The console "Logout Account" will call /api/auth/logout to revoke the Telegram session; "Destroy Instance" will also delete the workload and persistent volume.

¶ Authentication and Health Check

Except for /health and /readyz, login, REST, and MCP interfaces all require:

Authorization: Bearer <access_token>

The service only accepts request header authentication and does not support appending the token to the URL. Please protect it as you would your account password.

curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz

/health only indicates that the HTTP process is alive:

{"status":"ok"}

/readyz indicates whether the MTProto connection is available. When connected, it returns HTTP 200, even if the account is still scanning or waiting for two-step verification:

{"status":"ready","gateway_connected":true,"login_state":"login_required"}

When disconnected, Kubernetes's direct probe of the Pod returns HTTP 503, and the instance will automatically reconnect in the background. At this time, the Pod will be temporarily removed from the public Service, and it is not guaranteed that the diagnostic JSON can be read through the instance domain name; please wait in the console for the Deployment to return to Ready. Common values for login_state include login_required, waiting_scan, password_required, and authenticated; the authenticated state must be reached before performing account message operations.

¶ Connecting MCP Client

¶ Claude Code

claude mcp add \
  --transport http \
  --header "Authorization: Bearer <access_token>" \
  telegram \
  https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp

¶ Clients like Cursor that Support Static Request Headers

Configure the Streamable HTTP address according to the current client documentation and add the Authorization request header. For example, clients that support the following structure can use:

{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer <access_token>"}
    }
  }
}

This is not a universal configuration format for all MCP clients. The remote connector for Claude Desktop / Claude.ai is established by the cloud and does not read any HTTP request headers from the local claude_desktop_config.json; if a static Bearer request header is needed, please use Claude Code or a client that explicitly supports this capability.

¶ MCP Tools

Tool	Function
`telegram_whoami`	View the current authorized account
`telegram_list_chats`	List recent chats, can view unread only
`telegram_contacts`	List contacts
`telegram_read_messages`	Read recent messages from a specified chat
`telegram_search_messages`	Search a chat or all chats
`telegram_send_message`	Send a message, can reply to a specified message
`telegram_edit_message`	Edit a message sent by the current account
`telegram_delete_message`	Delete messages that can be deleted
`telegram_react`	Respond to messages with Unicode emojis
`telegram_mark_read`	Mark a chat as read

target can be the chat ID, username, or exact chat name; when names are ambiguous, prefer using ID or username.

¶ REST API

All successful responses use {"data": ...}, and failed responses use {"error": "..."}.

¶ Example

# Current account
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

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

# Send a test message to 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"}'

¶ Complete Interface

Method and Path	Main Parameters	Function
`POST /api/auth/qr`	—	Generate login QR code URL
`GET /api/auth/status`	—	Query login status and account information
`POST /api/auth/password`	`{password}`	Submit two-step verification password
`POST /api/auth/logout`	—	Revoke the session saved by the instance
`GET /api/whoami`	—	View the current account
`GET /api/chats`	`?limit=&unread_only=`	List chats and unread counts
`GET /api/contacts`	—	List contacts
`GET /api/chats/{target}/messages`	`?limit=`	Read messages
`GET /api/messages/search`	`?q=&target=&limit=`	Search messages; omit target for cross-chat search
`POST /api/messages`	`{target,text,reply_to?}`	Send or reply to messages
`PATCH /api/chats/{target}/messages/{message_id}`	`{text}`	Edit messages
`DELETE /api/chats/{target}/messages/{message_id}`	—	Delete messages
`POST /api/chats/{target}/messages/{message_id}/reactions`	`{emoji}`	Add Unicode emoji response
`POST /api/chats/{target}/read`	—	Mark chat as read

¶ Frequently Asked Questions

401: Bearer token is missing or incorrect. Confirm that the token is placed in the request header, not in the URL query parameters.
503: Proxy access token is not configured, or the Telegram client is not ready yet. First, check /readyz; if the proxy access token is not configured, the protected interface will also return 503.
400: Parameters or JSON are invalid; search must provide q, and limit must be an integer greater than or equal to 1.
403 / 404: The current account does not have permission, or the target/message ID does not exist.
429: Triggered Telegram rate limit. Read retry_after and wait, do not retry concurrently.
QR code has not completed: Regenerate the QR code and confirm that you are using the Telegram "Link Desktop Device" scanning entry.
Requires re-login after restart: Check if the instance persistent volume is functioning properly; actively logging out, revoking sessions in the Telegram device list, or session expiration will require re-scanning.

¶ Verification Scope

Source code and automated tests cover login status, Bearer fail-close, REST parameter validation, error mapping, and session persistence implementation. Production use should first complete read-only and message creation/editing/deletion smoke tests in target=me (Saved Messages) before allowing the Agent to operate third-party sessions.