GramClaw API

Drive your Telegram outreach from scripts, AI agents, or the Telegram MCP server: search messages, manage the CRM pipeline, set custom columns, and send messages, broadcasts, and campaigns. Create a key in Settings → API Keys.

Start with an outcome

Popular recipes

View all

Read an existing Telegram conversation

Select an eligible account, list its existing chats, and read history without changing Telegram read state.

5 minutes

Send one message to an existing conversation

Send one plain-text message using an exact account/chat scope and a stable caller-generated idempotency key.

5 minutes

Search persisted Telegram history

Search only the workspace-owned, account-scoped messages already persisted by GramClaw.

3 minutes

Connect a read-only AI client through MCP

Give an MCP client read-only access to eligible Telegram accounts, chats, participants, and persisted search.

5 minutes

Authentication

Every request needs a workspace API key as a Bearer token. Create one in Settings → API Keys — the full key ( gc_live_…) is shown once.

Base URL

https://gramclaw.com

Every request

Authorization: Bearer gc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quick start

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

Heads up: API calls execute directly — there is no confirmation step (unlike the in-app AI). The key is the authorization; guard it like a password. Rate limit: 120 requests / minute per key, with X-RateLimit-* headers on every response. Errors return { "error": "…" } with a 4xx/5xx status.

Scopes: keys carry read (chats, messages, search, analytics), write (pipeline, columns, webhooks), and/or send (messages, broadcasts, campaigns), or campaign for separately authorized internal campaign reads (and, behind a separate mutation gate and allowlists, campaign creation and cancellation). — choose them when creating the key. Send-type POSTs accept an Idempotency-Key header so retries never double-send.

Endpoints

GET/api/v1/me— Verify key & list Telegram accountsscope: read

Returns only currently eligible, workspace-scoped internal Telegram accounts plus explicit capabilities.

GET/api/v1/chats— List existing Telegram chatsscope: read

Reads an exact eligible account through scoped Telegram v2. No conversation is created and no message is marked read.

Field	Type	Notes
account_id*	string
cursor	string
limit	number	default 50, max 100

GET/api/v1/chats/{id}— Get chat and participantsscope: read

Returns provider-neutral metadata and participants for the exact account/chat scope.

Field	Type	Notes
account_id*	string
participant_cursor	string
participant_limit	number

GET/api/v1/chats/{id}/messages— Read message historyscope: read

Reads scoped Telegram history without changing read state.

Field	Type	Notes
account_id*	string
before	string
limit	number

POST/api/v1/chats/start— Open a chat by Telegram usernamescope: send

Resolves a Telegram username and opens its private chat under one exact eligible account. Requires a send-scoped key, the Start Chat feature gate, and a caller-supplied Idempotency-Key. It never sends a message.

Field	Type	Notes
account_id*	string
identifier*	string	username, @username, or t.me username link
Idempotency-Key header*	string

POST/api/v1/search— Search persisted Telegram messagesscope: read

Searches only account-scoped history already persisted by GramClaw and reports that completeness limitation.

Field	Type	Notes
query*	string
account_id	string
chat_id	string

GET/api/v1/contacts— List observed Telegram contactsscope: read

Reads account-scoped contacts already observed by GramClaw. Requires both REST API and CRM read access; it never performs a Telegram lookup.

Field	Type	Notes
account_id	string
q	string
cursor	string
limit	number	default 100, max 200

GET/api/v1/pipeline— Read scoped Telegram pipelinescope: read

Returns workspace stages and account-qualified Telegram chat placements. Requires both REST API and Pipeline read access.

POST/api/v1/pipeline/move— Move a scoped Telegram chatscope: write

Assigns an existing chat to a visible workspace stage. Requires an explicit write-scoped key plus the REST API and Pipeline gates.

Field	Type	Notes
account_id*	string
chat_id*	string
stage_key*	string	visible key from GET /api/v1/pipeline

GET/api/v1/columns— Read custom columns and scoped valuesscope: read

Returns workspace column definitions plus values keyed by both Telegram account and chat. Requires both REST API and CRM read access.

Field	Type	Notes
account_id	string	optional exact account filter for values

POST/api/v1/columns/set— Set a scoped Telegram column valuescope: write

Sets or clears a configured value for one exact account/chat. Requires an explicit write-scoped key plus the REST API and CRM gates.

Field	Type	Notes
account_id*	string
chat_id*	string
column_id*	string
value*	string[]	empty array clears the value

GET/api/v1/analytics— Read truthful Telegram analyticsscope: read

Reports persisted message activity and durable campaign-send ledger counts. Delivery, read, and engagement are null rather than inferred. Requires both REST API and Analytics read access.

Field	Type	Notes
period	"7d" \| "30d" \| "all"	default 7d

GET/api/v1/campaigns— List internal Telegram campaignsscope: campaign

Lists only workspace-owned internal Telegram campaigns with truthful durable reporting. Requires an explicitly issued campaign scope plus the independent Campaigns gate and user allowlist.

Field	Type	Notes
cursor	string
limit	number	default 50, max 100

GET/api/v1/campaigns/{id}— Read internal Telegram campaign detailscope: campaign

Returns durable recipients, sequence steps, operation state, and reporting. capabilities reflect the key scope, allowlists, gates, and current status. Legacy campaigns remain outside the public execution plane.

POST/api/v1/campaigns— Create a campaign for existing private chatsscope: campaign

Disabled by default behind a separate mutation gate plus exact user and workspace allowlists. Requires a campaign-scoped key and Idempotency-Key. Recipients must be existing private chats of READY internal Telegram accounts (max 20). No @usernames, attachments, or client-supplied names; suppressed recipients reject the request. Campaign, steps and recipients are stored atomically and queued for the worker — this call never sends a message.

Field	Type	Notes
message_text*	string	1-4096 chars; [[name]]/[[username]] come from Telegram
recipients*	{ account_id, chat_id }[]	1-20 existing private chats
name	string	up to 200 chars
steps	{ branch, wait_hours, variants }[]	follow-ups; branch no_reply, or seen/unseen when branching is enabled
branching_enabled	boolean	requires the U4 branching gate
daily_quota_per_account	number	1-50 campaign ceiling, default 50; account tier may enforce a lower limit
max_followups	number	0-5, default 2
scheduled_at / schedule_timezone	string	ISO time (≤ 1 year ahead) / IANA zone
Idempotency-Key header*	string

Response

{ "campaign": { "id": "…", "status": "queued" }, "recipients": 2, "dispatch": "worker" }

POST/api/v1/campaigns/{id}/pause— Pause an internal sequence campaignscope: campaign

Requires campaign scope, the REST/campaign mutation gates and Idempotency-Key. Pausing changes queue state only; the durable worker remains the only dispatcher. Sequence campaigns only.

Field	Type	Notes
Idempotency-Key header*	string

Response

{ "campaign": { "id": "…", "status": "paused" }, "changed": true, "dispatch": "worker" }

POST/api/v1/campaigns/{id}/resume— Resume an internal sequence campaignscope: campaign

Requires campaign scope, the REST/campaign mutation gates and Idempotency-Key. Resuming changes queue state only; the durable worker remains the only dispatcher. Sequence campaigns only.

Field	Type	Notes
Idempotency-Key header*	string

Response

{ "campaign": { "id": "…", "status": "sending" }, "changed": true, "dispatch": "worker" }

POST/api/v1/campaigns/{id}/cancel— Permanently cancel a campaignscope: campaign

Same gates as creation plus Idempotency-Key. Atomically cancels a scheduled, queued, sending or paused campaign and stops queued recipients; idempotent and irreversible. A send already handed to Telegram may still complete.

Field	Type	Notes
Idempotency-Key header*	string

Response

{ "campaign": { "id": "…", "status": "cancelled", "cancelled_at": "…" }, "changed": true }

POST/api/v1/messages— Send text and optionally one attachmentscope: send

Requires an explicit send-scoped key and caller-supplied Idempotency-Key. Sends only to an existing eligible account/chat. JSON supports plain text; multipart/form-data supports exactly one file up to 25 MiB with optional text. No multi-file support. Ambiguous outcomes are never retried.

Field	Type	Notes
account_id*	string
chat_id*	string
text	string	required for JSON; optional with an attachment
attachments	one file	multipart only; maximum 25 MiB; multiple files rejected
Idempotency-Key header*	string

Request

curl -s "$BASE/api/v1/messages" \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: unique-operation-123" \
  -F "account_id=ACCOUNT_ID" -F "chat_id=telegram:chat:123" \
  -F "text=See attached" -F "attachments=@./file.pdf"

Response

{ "ok": true, "operation_id": "…", "message": { "id": "telegram:message:…" } }

Connect from Claude / Cursor (Telegram MCP)

Easiest — remote connector (a URL). In your MCP client, add a custom connector and paste your personal URL. Create a key in Settings → API Keys to get the full URL with your key. See the Telegram MCP overview for the tool list.

Remote MCP URL

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

Alternative — local server (Cursor, or Claude Desktop config file):

claude_desktop_config.json

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

Need setup help? Visit the API & MCP help guide.