> ## 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 계정 프록시는 본인이 소유한 개인 Telegram 계정에 독립적이고 상주하는 MCP 및 REST 인터페이스를 제공합니다. 각 인스턴스는 하나의 계정만 서비스하며, 컨테이너에는 AI가 포함되어 있지 않고 로그인 세션은 해당 인스턴스의 독립적인 영구 볼륨에 저장됩니다.

> 이것은 Telegram Bot API 봇이 아닙니다. 스팸 메시지, 대량 콜드 메시지 발송 또는 Telegram 제한 우회에 사용하지 마세요. 제3자에게 콘텐츠를 전송, 편집 또는 삭제하기 전에 Agent가 명확한 확인을 받아야 합니다.

## 배포 및 로그인

1. [콘솔 → 애플리케이션](https://platform.acedata.cloud/console/applications)에서 Telegram 계정 프록시를 생성하고, 구독을 활성화한 후 배포를 클릭합니다. 인스턴스 리소스는 플랫폼에서 자동으로 구성합니다.
2. 인스턴스가 준비되면 「로그인 QR 코드 생성」을 클릭합니다. QR 코드는 단기간 유효하며, 만료 후 다시 생성할 수 있습니다.
3. Telegram에서 **설정 → 기기 → 데스크톱 기기 연결**을 열고 QR 코드를 스캔합니다.
4. 상태가 `password_required`로 변경되면 콘솔에서 Telegram 2단계 인증 비밀번호를 입력합니다. 비밀번호는 테넌트 인스턴스에만 제출되며, 플랫폼 구성에 기록되지 않습니다.
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 연결 사용 가능 여부를 나타냅니다. 연결된 경우 계정이 아직 QR 코드 스캔 중이거나 2단계 인증을 기다리는 상태여도 HTTP 200을 반환합니다:

```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의 원격 커넥터는 클라우드에서 연결되며, 로컬 `claude_desktop_config.json`에 있는 어떠한 HTTP 요청 헤더도 읽지 않습니다. 현재 정적 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` | — | 로그인 QR 코드 URL 생성 |
| `GET /api/auth/status` | — | 로그인 상태 및 계정 정보 조회 |
| `POST /api/auth/password` | `{password}` | 2단계 인증 비밀번호 제출 |
| `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 기기 목록에서 세션을 취소했거나 세션이 만료된 후에는 다시 스캔해야 합니다.

## 검증 범위

소스 코드와 자동화 테스트는 로그인 상태, Bearer fail-close, REST 매개변수 검증, 오류 매핑 및 세션 영속화 구현을 포괄합니다. 프로덕션 사용 시에는 여전히 먼저 `target=me`（Saved Messages）에서 읽기 전용 및 메시지 생성/편집/삭제 smoke를 완료한 후, Agent가 제3자 세션을 조작하도록 허용해야 합니다.


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