Guia de uso do proxy de conta do Telegram

Isto não é um bot da API do Telegram Bot. Não o utilize para mensagens de spam, envio em massa a frio ou para contornar restrições do Telegram. Antes de enviar, editar ou excluir conteúdo para terceiros, o seu Agent deve obter confirmação explícita.

​

Implantação e login

1. Crie um proxy de conta do Telegram em Console → Aplicações, ative uma assinatura e clique em implantar. Os recursos da instância são configurados automaticamente pela plataforma.
2. Após a instância estar pronta, clique em «Gerar código QR de login». O código QR é válido por pouco tempo e pode ser gerado novamente após expirar.
3. No Telegram, abra Configurações → Dispositivos → Vincular dispositivo de desktop e escaneie o código QR.
4. Se o status mudar para password_required, insira a senha de verificação em duas etapas do Telegram no console. A senha é enviada apenas à instância do seu locatário e não será gravada na configuração da plataforma.
5. Após o status mudar para authenticated, o console exibirá a conta atual, o endereço MCP e o token de acesso Bearer.

​

Autenticação e verificação de integridade

Authorization: Bearer <访问令牌>

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

{"status":"ok"}

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

​

Conectar um cliente MCP

​

Claude Code

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

​

Clientes como Cursor que oferecem suporte a cabeçalhos estáticos de requisição

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

​

Ferramentas MCP

​

API REST

​

Exemplos

# 当前账号
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"}'

​

Interfaces completas

​

Perguntas frequentes

• 401: Token Bearer ausente ou incorreto. Confirme que o token está no cabeçalho da solicitação, não nos parâmetros de consulta da URL.
• 503: O token de acesso do proxy não está configurado, ou o cliente Telegram ainda não está pronto. Primeiro verifique /readyz; se o token de acesso do proxy não estiver configurado, as interfaces protegidas também retornarão 503.
• 400: Parâmetros ou JSON inválidos; a busca deve fornecer q, e limit deve ser um inteiro maior ou igual a 1.
• 403 / 404: A conta atual não tem permissão, ou o ID de target / message não existe.
• 429: O limite de frequência do Telegram foi acionado. Leia retry_after e aguarde, não tente novamente em paralelo.
• Código QR nunca concluído: Gere novamente o código QR e confirme que está usando a entrada de escaneamento do Telegram «Vincular dispositivo desktop».
• É necessário fazer login novamente após reiniciar: Verifique se o volume persistente da instância está normal; é necessário escanear novamente após sair ativamente, revogar a sessão na lista de dispositivos do Telegram ou a sessão expirar.

​

Escopo de verificação