GramClaw API

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

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

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

Reads scoped Telegram history without changing read state.

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.

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

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

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

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

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

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

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.

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.

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.

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.

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

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.

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

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.

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

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.

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

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.

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"

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