GramClaw API

قُد تواصلك عبر تيليجرام من النصوص البرمجية أو وكلاء الذكاء الاصطناعي أو خادم MCP الخاص بتيليجرام: ابحث في الرسائل، وأدر مسار CRM، وحدّد أعمدة مخصصة، وأرسل الرسائل والبثّ والحملات. أنشئ مفتاحًا في الإعدادات ← مفاتيح API.

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

المصادقة

تحتاج كل طلب إلى مفتاح API خاص بمساحة العمل كرمز Bearer. أنشئ واحدًا في الإعدادات ← مفاتيح 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 مباشرةً — لا توجد خطوة تأكيد (على عكس الذكاء الاصطناعي داخل التطبيق). المفتاح هو التفويض؛ احمِه مثل كلمة المرور. حدّ المعدل: 120 طلبًا / دقيقة لكل مفتاح، مع ترويسات X-RateLimit-* في كل استجابة. تُعيد الأخطاء { "error": "…" } مع رمز حالة 4xx/5xx.

النطاقات: تحمل المفاتيح read (المحادثات والرسائل والبحث والتحليلات), write (المسار، الأعمدة، الويب هوك), و/أو send (الرسائل، البثّ، الحملات), or campaign for separately authorized internal campaign reads (and, behind a separate mutation gate and allowlists, campaign creation and cancellation). — اخترها عند إنشاء المفتاح. تقبل طلبات POST من نوع الإرسال ترويسة Idempotency-Key حتى لا تؤدي المحاولات المتكررة إلى إرسال مزدوج.

نقاط النهاية

GET/api/v1/me— Verify key & list Telegram accountsالنطاق: read

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

GET/api/v1/chats— List existing Telegram chatsالنطاق: read

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

الحقل	النوع	ملاحظات
account_id*	string
cursor	string
limit	number	default 50, max 100

GET/api/v1/chats/{id}— Get chat and participantsالنطاق: read

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

الحقل	النوع	ملاحظات
account_id*	string
participant_cursor	string
participant_limit	number

GET/api/v1/chats/{id}/messages— Read message historyالنطاق: read

Reads scoped Telegram history without changing read state.

الحقل	النوع	ملاحظات
account_id*	string
before	string
limit	number

POST/api/v1/chats/start— Open a chat by Telegram usernameالنطاق: 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.

الحقل	النوع	ملاحظات
account_id*	string
identifier*	string	username, @username, or t.me username link
Idempotency-Key header*	string

POST/api/v1/search— Search persisted Telegram messagesالنطاق: read

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

الحقل	النوع	ملاحظات
query*	string
account_id	string
chat_id	string

GET/api/v1/contacts— List observed Telegram contactsالنطاق: read

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

الحقل	النوع	ملاحظات
account_id	string
q	string
cursor	string
limit	number	default 100, max 200

GET/api/v1/pipeline— Read scoped Telegram pipelineالنطاق: 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 chatالنطاق: write

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

الحقل	النوع	ملاحظات
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 valuesالنطاق: read

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

الحقل	النوع	ملاحظات
account_id	string	optional exact account filter for values

POST/api/v1/columns/set— Set a scoped Telegram column valueالنطاق: 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.

الحقل	النوع	ملاحظات
account_id*	string
chat_id*	string
column_id*	string
value*	string[]	empty array clears the value

GET/api/v1/analytics— Read truthful Telegram analyticsالنطاق: 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.

الحقل	النوع	ملاحظات
period	"7d" \| "30d" \| "all"	default 7d

GET/api/v1/campaigns— List internal Telegram campaignsالنطاق: 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.

الحقل	النوع	ملاحظات
cursor	string
limit	number	default 50, max 100

GET/api/v1/campaigns/{id}— Read internal Telegram campaign detailالنطاق: 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 chatsالنطاق: 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.

الحقل	النوع	ملاحظات
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

الاستجابة

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

POST/api/v1/campaigns/{id}/pause— Pause an internal sequence campaignالنطاق: 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.

الحقل	النوع	ملاحظات
Idempotency-Key header*	string

الاستجابة

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

POST/api/v1/campaigns/{id}/resume— Resume an internal sequence campaignالنطاق: 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.

الحقل	النوع	ملاحظات
Idempotency-Key header*	string

الاستجابة

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

POST/api/v1/campaigns/{id}/cancel— Permanently cancel a campaignالنطاق: 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.

الحقل	النوع	ملاحظات
Idempotency-Key header*	string

الاستجابة

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

POST/api/v1/messages— Send text and optionally one attachmentالنطاق: 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.

الحقل	النوع	ملاحظات
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

الطلب

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:…" } }

الاتصال من Claude / Cursor (تيليجرام MCP)

الأسهل — موصّل عن بُعد (عنوان URL). في عميل MCP الخاص بك، أضِف موصّلاً مخصصًا والصق عنوان URL الشخصي الخاص بك. أنشئ مفتاحًا في الإعدادات ← مفاتيح API للحصول على عنوان URL الكامل مع مفتاحك. راجع نظرة عامة على تيليجرام MCP للاطلاع على قائمة الأدوات.

عنوان URL لـ MCP عن بُعد

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.