GramClaw API

قُد تواصلك عبر تيليجرام من النصوص البرمجية أو وكلاء الذكاء الاصطناعي أو خادم 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

المصادقة

تحتاج كل طلب إلى مفتاح 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 (الرسائل، البثّ، الحملات) — اخترها عند إنشاء المفتاح. تقبل طلبات 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 للاطلاع على قائمة الأدوات.

عنوان 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.