GramClaw API

스크립트, AI 에이전트 또는 텔레그램 MCP 서버에서 메시지 검색, CRM 파이프라인 관리, 사용자 지정 열 설정, 메시지·브로드캐스트·캠페인 전송을 할 수 있습니다. 키 생성 위치: 설정 → API 키.

Start with an outcome

Popular recipes

View all

Send your first Telegram message

Verify an API key, choose a connected Telegram account, and start a direct conversation by username.

5 minutes

Build an automated follow-up sequence

Create a personalized campaign with two timed follow-ups that stop automatically when a recipient replies.

10 minutes

Connect an AI agent through MCP

Give Claude Desktop, Cursor, or another MCP client controlled access to your GramClaw workspace.

10 minutes

Broadcast to a pipeline stage

Send a personalized update to the reachable contacts in one pipeline stage without assembling a contact list by hand.

7 minutes

Distribute a campaign across accounts

Queue a larger campaign across a controlled pool of Telegram accounts with per-account daily limits.

10 minutes

Find and qualify conversations

Search message history for buying signals, inspect the matching chats, and move relevant conversations into a pipeline stage.

8 minutes

Receive signed workspace events

15 minutes

Build a campaign performance report

Read workspace totals, compare recent campaigns, and inspect the recipients behind an unusual result.

6 minutes

Export a filtered inbox safely

Page through GramClaw's conversation store with an account or pipeline filter instead of requesting an unbounded inbox.

10 minutes

인증

모든 요청에는 Bearer 토큰으로 사용할 워크스페이스 API 키가 필요합니다. 설정 → API 키에서 생성하세요 — 전체 키( gc_live_…)는 한 번만 표시됩니다.

기본 URL

https://gramclaw.com

모든 요청

Authorization: Bearer gc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

빠른 시작

BASE="https://gramclaw.com"
KEY="gc_live_…"
curl -s "$BASE/api/v1/me" -H "Authorization: Bearer $KEY"

참고: API 호출은 확인 단계 없이 곧바로 실행됩니다(앱 내 AI와 달리). 키가 곧 인증 수단이므로 비밀번호처럼 관리하세요. 속도 제한: 분당 120건의 요청 (키당). 모든 응답에 X-RateLimit-* 헤더가 포함됩니다. 오류는 { "error": "…" } 를 4xx/5xx 상태 코드와 함께 반환합니다.

스코프: 키에는 read (채팅, 메시지, 검색, 분석), write (파이프라인, 열, 웹훅), 및/또는 send (메시지, 브로드캐스트, 캠페인) — 키를 생성할 때 선택합니다. 전송 유형 POST 요청은 Idempotency-Key 헤더를 허용하므로 재시도 시 중복 전송되지 않습니다.

엔드포인트

GET/api/v1/me— Verify key & list accounts스코프: read

Confirms a key works and returns the workspace plus the connected accounts it can act on (with account ids for broadcasting).

응답

{
  "workspace_id": "cbf805da-…",
  "key": { "name": "Claude MCP", "prefix": "gc_live_ab12cd34", "scopes": ["read","send"] },
  "accounts": [
    { "id": "acc_…", "provider": "Telegram", "type": "MESSAGING", "name": "…" }
  ]
}

GET/api/v1/chats— List conversations스코프: read

The workspace's conversations newest-first, served from GramClaw's own store (fast — no provider calls). Cursor-paginated; filter by account, pipeline stage, or column value.

필드	유형	비고
cursor	string	from previous next_cursor
limit	number	default 50, max 100
account_id	string
stage_key	string	only chats in this stage
column_id	string	with column_value: only matching chats
column_value	string

요청

curl -s "$BASE/api/v1/chats?stage_key=qualified&limit=20" \
  -H "Authorization: Bearer $KEY"

응답

{
  "chats": [{ "id": "…", "name": "Sarah K", "provider": "TELEGRAM",
              "last_message_text": "…", "last_message_at": "…", "unread_count": 2 }],
  "next_cursor": "bzoyMA", "has_more": true
}

GET/api/v1/chats/{id}— Get one chat스코프: read

One chat enriched with its pipeline stage and custom-column values.

응답

{
  "chat": { "id": "…", "name": "Sarah K", "stage_key": "qualified",
            "columns": [{ "column_id": "…", "value": ["High"] }] }
}

GET/api/v1/chats/{id}/messages— Read message history스코프: read

A chat's messages, oldest-first within the page. Pass `before` (ISO timestamp) to page older messages; the response's next_before feeds the next call.

필드	유형	비고
limit	number	default 30, max 100
before	string	ISO timestamp — messages older than this

요청

curl -s "$BASE/api/v1/chats/CHAT_ID/messages?limit=50" \
  -H "Authorization: Bearer $KEY"

응답

{
  "messages": [{ "id": "…", "text": "Hey!", "is_sender": false,
                 "timestamp": "2026-07-06T10:00:00Z", "attachments": [] }],
  "source": "db", "next_before": "2026-07-01T08:00:00Z"
}

POST/api/v1/chats/start— Start a new conversation스코프: send

Start (or find) a DM with someone by phone, @username, or provider id — including people never messaged before. Optionally sends a first message. Supports Idempotency-Key.

필드	유형	비고
account_id*	string	account to send from (see /me)
identifier*	string	phone, @username, or provider id
provider	string	hint: TELEGRAM, WHATSAPP, …
text	string	optional first message

요청

curl -s "$BASE/api/v1/chats/start" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"acc_…","identifier":"@newlead","text":"Hi!"}'

응답

{ "chat": { "id": "…" } }

GET/api/v1/contacts— List contacts스코프: read

The workspace's contact cache (name + provider id per account). Cursor-paginated, searchable by name.

필드	유형	비고
cursor	string
limit	number	default 100, max 200
account_id	string
q	string	name search

응답

{
  "contacts": [{ "account_id": "…", "provider_id": "…", "name": "Sarah K" }],
  "next_cursor": null, "has_more": false
}

POST/api/v1/search— Search messages & email

Search connected platforms by people, keywords, and date range. Returns matching excerpts plus the chats they came from — use a returned chat_id with the move / message endpoints.

필드	유형	비고
people	string[]	Person names
keywords	string[]	Topic keywords (not names)
time_after	string	ISO date lower bound
time_before	string	ISO date upper bound
account_types	"messaging" \| "email" \| "all"	Default all

요청

curl -s "$BASE/api/v1/search" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"people":["Sarah"],"keywords":["invoice"]}'

응답

{
  "match_count": 3,
  "platforms_searched": ["Telegram", "Gmail"],
  "chats": [{ "chat_id": "…", "chat_name": "Sarah", "provider": "Telegram" }],
  "context": "### Sarah (Telegram) …"
}

GET/api/v1/pipeline— Get pipeline

The workspace's pipeline stages and which chats sit in each stage. Chats not in placements are in the default 'new' stage.

응답

{
  "stages": [{ "key": "new", "label": "New", "terminal": false }, …],
  "placements": [{ "chat_id": "…", "stage_key": "qualified" }]
}

POST/api/v1/pipeline/move— Move a chat to a stage

Move a chat into a pipeline stage.

필드	유형	비고
chat_id*	string
stage_key*	string	from GET /api/v1/pipeline

요청

curl -s "$BASE/api/v1/pipeline/move" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"…","stage_key":"qualified"}'

응답

{ "ok": true, "message": "Moved to **Qualified**." }

GET/api/v1/columns— List custom columns

The workspace's custom columns (tags) with ids, types, and allowed option values.

응답

{
  "columns": [
    { "id": "…", "name": "Priority", "type": "select",
      "options": [{ "value": "High", "color": "#f87171" }] }
  ]
}

POST/api/v1/columns/set— Set a column value

Set (or clear) a custom-column value on a chat. An empty value array clears it.

필드	유형	비고
column_id*	string	from GET /api/v1/columns
chat_id*	string
value*	string[]	empty clears

요청

curl -s "$BASE/api/v1/columns/set" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"column_id":"…","chat_id":"…","value":["High"]}'

응답

{ "ok": true, "message": "Set **Priority** = High." }

POST/api/v1/messages— Send a message

Send a single message to an existing chat.

필드	유형	비고
chat_id*	string
text*	string

요청

curl -s "$BASE/api/v1/messages" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"…","text":"Hi there!"}'

응답

{ "ok": true, "message": "Message sent." }

POST/api/v1/broadcast— Broadcast to an audience

Send one message to everyone in a pipeline stage or with a custom-column value. Supports {{name}} personalization. Capped at 30 recipients per call.

필드	유형	비고
account_id*	string	account to send from (see /me)
audience_type*	"stage" \| "column"
audience_ref*	string	stage_key, or column_id for column
column_value	string	required for column audiences
message_text*	string	may include {{name}}

요청

curl -s "$BASE/api/v1/broadcast" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"acc_…","audience_type":"stage",
       "audience_ref":"qualified","message_text":"Hi {{name}}!"}'

응답

{ "ok": true, "message": "Broadcast sent to **12** recipients.",
  "recipients": 12, "audience_total": 12, "capped": false }

POST/api/v1/campaigns— Create a campaign (large sends)스코프: send

The API path for sends larger than broadcast's 30-recipient cap (max 5,000 contacts). GramClaw's background worker delivers every message — initial + optional follow-up steps — respecting per-account daily quotas. Supports Idempotency-Key. Also: GET /api/v1/campaigns lists campaigns; GET /api/v1/campaigns/{id} returns status + per-contact detail.

필드	유형	비고
name	string
account_id	string	or account_pool: string[] to rotate accounts
message_text*	string	may include {{name}}
contacts*	array	[{ name?, identifier, chat_id? }]
steps	array	follow-ups: [{ branch, wait_hours, variants[] }]
daily_quota_per_account	number	default 30

요청

curl -s "$BASE/api/v1/campaigns" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-jul-06" \
  -d '{"account_id":"acc_…","message_text":"Hi {{name}}!",
       "contacts":[{"name":"Sarah","identifier":"@sarahk"}]}'

응답

{ "campaign": { "id": "…", "status": "queued" }, "queued": true }

GET/api/v1/analytics— Campaign analytics스코프: read

Workspace campaign totals (sent, failed, replies, reply rate) plus the 50 most recent campaigns.

응답

{
  "totals": { "campaigns": 12, "sent": 452, "replies": 87, "reply_rate": 0.1925 },
  "campaigns": [ … ]
}

POST/api/v1/webhooks— Register a webhook스코프: write

Get pushed events instead of polling: message.received, message.edited, message.deleted, pipeline.moved, campaign.replied. Deliveries are signed (X-GramClaw-Signature: sha256=HMAC_SHA256(secret, body)); the secret is returned once at creation. GET lists endpoints; PATCH /api/v1/webhooks/{id} updates url/events/active; DELETE removes. Max 10 per workspace; 20 consecutive failures auto-disable an endpoint.

필드	유형	비고
url*	string	your HTTPS endpoint
events	string[]	omit or ["*"] for all events

요청

curl -s "$BASE/api/v1/webhooks" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/gramclaw",
       "events":["message.received","pipeline.moved"]}'

응답

{ "webhook": { "id": "…", "events": ["message.received","pipeline.moved"] },
  "secret": "whsec_…  ← shown once, signs every delivery" }

Claude / Cursor에서 연결 (텔레그램 MCP)

가장 쉬움 — 원격 커넥터(URL). MCP 클라이언트에서 사용자 지정 커넥터를 추가하고 개인 URL을 붙여넣으세요. 설정 → API 키에서 키를 생성하면 키가 포함된 전체 URL을 받을 수 있습니다. 텔레그램 MCP 개요 에서 도구 목록을 확인하세요.

원격 MCP URL

https://gramclaw.com/api/mcp?key=gc_live_…

대안 — 로컬 서버 (Cursor 또는 Claude Desktop 구성 파일):

claude_desktop_config.json

{
  "mcpServers": {
    "gramclaw": {
      "command": "npx",
      "args": ["-y", "gramclaw-mcp"],
      "env": {
        "GRAMCLAW_API_KEY": "gc_live_…",
        "GRAMCLAW_BASE_URL": "https://gramclaw.com"
      }
    }
  }
}

설정에 도움이 필요하신가요? API 및 MCP 도움말 가이드.