GramClaw API

スクリプト、AI エージェント、または Telegram MCP サーバーでメッセージの検索、CRM パイプラインの管理、カスタム列の設定、メッセージ・ブロードキャスト・キャンペーンの送信ができます。キーの作成はこちら：設定 → API キー.

認証

すべてのリクエストには 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 （パイプライン、列、Webhook）, および/または 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 から接続（Telegram MCP）

最も簡単 — リモートコネクター（URL）。 MCP クライアントでカスタムコネクターを追加し、個人 URL を貼り付けます。設定 → API キーでキーを作成すると、キー付きの完全な URL が取得できます。ツール一覧は Telegram 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 ヘルプガイド.