> ## 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. # WhatsApp 계정 에이전트 사용 가이드 > Platform API guide - Ace Data Cloud WhatsApp 계정 에이전트는 **본인이 승인한 WhatsApp 계정**에 연결하여, 기존 대화, 연락처 및 메시지를 Agent에 제공합니다. 각 배포 인스턴스에는 독립적인 연결, 액세스 토큰 및 영구 저장소가 있습니다. 서비스 자체에는 AI가 포함되어 있지 않으며, 자동으로 답장, 대량 발송 또는 누구에게도 먼저 연락하지 않습니다. > 본 서비스는 WhatsApp 연결된 기기 기능을 사용하며, WhatsApp 공식 Business API가 아닙니다. 계정 연결 방식은 WhatsApp의 공식 지원을 받지 않습니다. 프로토콜 변경, 기기 해제 또는 계정 제한으로 인해 중단될 수 있습니다. 본인이 소유한 계정만 연결하고, WhatsApp 약관을 준수하며, 스팸 메시지 또는 동의 없는 대량 발송에 사용하지 마십시오. ## 배포 및 본인 승인 1. 콘솔에서 「WhatsApp 계정 에이전트」 애플리케이션을 생성하고, 구독을 활성화한 후 배포를 클릭합니다. 인스턴스 리소스는 플랫폼에서 자동으로 구성됩니다. 2. 인스턴스가 준비된 후 관리 페이지에서 QR 코드를 확인합니다. 본인 휴대폰에서 WhatsApp **설정 → 연결된 기기 → 기기 연결**을 열고 스캔합니다. 또는 본인 전화번호를 입력하여 페어링 코드를 요청한 후, 휴대폰에서 확인할 수도 있습니다. 3. 관리 페이지 상태가 「연결됨」으로 변경된 후, 전용 MCP 주소와 Bearer 액세스 토큰을 복사합니다. 4. 계정에서 로그아웃하면 연결된 기기를 해제하고 로컬 세션 및 기록을 지우려고 시도합니다. 로그아웃 결과가 확실하지 않은 경우, 먼저 휴대폰의 「연결된 기기」에서 해당 기기를 해제하십시오. 인스턴스를 삭제하면 해당 영구 볼륨이 제거됩니다. QR 코드와 페어링 코드는 계정 본인에게만 제공할 수 있습니다. 정상적인 재시작은 해당 인스턴스의 세션을 재사용합니다. 휴대폰에서 기기를 해제한 후에는 인스턴스가 다시 승인을 요구합니다. ## 인증 및 기능 `/health` 및 `/readyz`를 제외하고 REST, MCP, QR 스캔 및 페어링 인터페이스는 모두 `Authorization: Bearer <액세스 토큰>`을 요구합니다. 토큰은 요청 헤더에만 넣고 URL이나 로그에는 넣지 마십시오. `GET /api/capabilities`는 현재 인스턴스가 실제로 지원하는 작업 및 보존 한도를 제공합니다. 현재 지원: 계정 및 연결 상태, 연결된 기기에 동기화된 대화 및 연락처, 실시간 메시지 이벤트, 로컬에 보존된 메시지 읽기, 텍스트 및 10 MiB 이하 미디어 송수신, 인용 답장, 이모지 반응, 읽음 표시, 그리고 계정 권한 및 WhatsApp의 현재 규칙이 허용하는 본인 메시지 편집/회수, 그룹 정보 및 단일 구성원 작업. 그룹 변경은 여전히 WhatsApp에서 구성원 및 관리자 권한을 검증합니다. **기록 범위**: 휴대폰에서 연결된 기기로 실제 동기화된 메시지와 에이전트가 온라인 상태인 동안 수신한 메시지만 읽을 수 있습니다. 모든 이전 메시지를 가져올 수 있다고 보장하지 않으며, 로컬에는 최근 메시지 최대 5,000개와 이벤트 2,000개만 보존됩니다. 미디어 메타데이터가 존재하더라도 원본 미디어는 이미 다운로드할 수 없을 수 있습니다. ## MCP 배포 관리 페이지는 `https://whatsapp-bot-<인스턴스 ID>.app.acedata.cloud/mcp`를 제공합니다. Streamable HTTP 및 사용자 지정 요청 헤더를 지원하는 MCP 클라이언트에서 이 주소를 구성하고, 동일한 Bearer 토큰을 추가하십시오. MCP 도구에는 `whatsapp_capabilities`, `whatsapp_whoami`, `whatsapp_chats`, `whatsapp_contacts`, `whatsapp_messages`, `whatsapp_events`, `whatsapp_send`, `whatsapp_send_status`, `whatsapp_media`, `whatsapp_mark_read`, `whatsapp_group` 및 `whatsapp_group_update`가 포함됩니다. Agent는 자신의 작업에 따라 메시지를 읽을 수 있습니다. 제3자에게 메시지를 보내거나, 메시지를 변경하거나, 그룹을 변경하기 전에는 사용자가 구체적인 대상과 내용을 확인하도록 해야 합니다. MCP를 구성해도 어떤 전송도 자동으로 실행되지 않습니다. ## REST 예시 ```bash theme={null} BASE='https://whatsapp-bot-<实例 ID>.app.acedata.cloud' TOKEN='<管理页显示的访问令牌>' curl "$BASE/api/auth/status" -H "Authorization: Bearer $TOKEN" curl "$BASE/api/chats?limit=20" -H "Authorization: Bearer $TOKEN" curl "$BASE/api/chats/123%40s.whatsapp.net/messages?limit=20" -H "Authorization: Bearer $TOKEN" ``` **본인의 기존 대화 또는 연락처**에게만 메시지를 보내십시오. `target`은 `/api/chats` 또는 `/api/contacts`가 반환한 JID를 사용해야 하며, 임의의 전화번호를 사용하여 선발송해서는 안 됩니다. 먼저 본인이 수신자와 내용을 확인하십시오. ```bash theme={null} curl -X POST "$BASE/api/messages" \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: my-confirmed-message-20261004-1" \ -H 'Content-Type: application/json' \ -d '{"target":"123@s.whatsapp.net","action":"text","text":"你好"}' ``` `action`은 `text`, `media`, `edit`, `revoke` 또는 `reaction`일 수 있습니다. 미디어 전송에는 `media_base64`와 `mime_type`을 전달하고, 답장에는 `reply_to`를 전달하며, 편집 및 회수에는 로컬에서 조회할 수 있는 본인의 `message_id`를 전달하고, 반응에는 `message_id`와 `emoji`를 전달합니다. `GET /api/chats/{target}/messages/{id}/media`를 통해 미디어를 다운로드할 수 있고, `POST /api/chats/{target}/read`를 통해 읽음으로 표시할 수 있습니다. 전송에는 반드시 8–128자 길이의 `Idempotency-Key`가 포함되어야 합니다. 반환되는 `message_id`는 고정되며, 상태는 `pending`, `accepted`, `unknown`, `delivered` 또는 `read`입니다. `accepted`는 로컬 연결이 전송을 수락했음을 의미할 뿐, **상대방이 수신했음을 의미하지는 않습니다**. `unknown`이 발생하면 `GET /api/sends/{Idempotency-Key}` 및 메시지 이벤트를 조회하십시오. 중복을 방지하기 위해 새 키로 동일한 메시지를 다시 보내지 마십시오. 에이전트는 불확실한 작업을 자동으로 재전송하지 않습니다. 전송 기록은 자동으로 제거되지 않습니다. 100,000건에 도달하면 인스턴스는 새로운 전송을 거부합니다(HTTP 507). 이는 이전 멱등성 키가 정리된 후 중복 전송이 발생하는 것을 방지하기 위함입니다. ## 실시간 이벤트 `GET /api/events?after=<마지막 next_cursor>&wait_ms=25000`은 최대 25초의 롱 폴링을 지원하며, `GET /api/events/stream?after=<커서>`는 SSE를 제공합니다. 이벤트에는 단조 증가하는 `seq`가 포함됩니다. 응답의 `next_cursor`는 Agent의 영구 상태에 저장해야 합니다. `gap=true`인 경우 이전 이벤트가 정리되었음을 의미하므로, 현재 대화 상태를 다시 가져오고 `oldest_cursor`부터 계속해야 합니다. 메시지 이벤트, 전송 상태 및 연결 상태는 각각 독립적으로 보고됩니다. ## 일반적인 상태 | HTTP / 상태 | 처리 방식 | | - | - | | 401 | Bearer 토큰과 요청 헤더를 확인합니다. | | 404 | 대상 대화, 연락처 또는 메시지가 이 인스턴스의 로컬 기록에 없습니다. | | 409 | 계정이 연결되지 않았거나, 동일한 멱등성 키가 다른 내용에 대응합니다. | | 413 | 미디어가 10 MiB를 초과합니다. | | 403 / 429 | 작업이 거부되었거나 빈도 제한이 발생했습니다. 전송 중 발생한 경우에도 먼저 해당 멱등성 키의 결과를 확인해야 합니다. | | 502 / 503 | 연결 또는 원격 작업에 실패했습니다. 전송 결과가 불확실한 경우 먼저 작업 상태와 이벤트를 확인합니다. | 무제한 기록, 모든 미디어의 장기 이용 가능성 또는 모든 그룹 작업이 항상 WhatsApp에 의해 수락되는 것은 보장되지 않습니다. 구체적인 인스턴스를 확인해야 하는 경우, 먼저 `/api/auth/status` 및 `/api/capabilities`를 확인하십시오. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.