API

واجهة TelegramOS HTTP API: المصادقة بمفتاح API وإدارة الحسابات وصندوق الوارد والبوتات والتحليلات وسير العمل برمجياً.

كل ما تفعله لوحة التحكم تفعله عبر واجهة HTTP API هذه. كل مسار ونص طلب ورمز حالة أدناه جرى اختباره على مساحة عمل حقيقية قبل نشر هذه الصفحة.

عنوان URL الأساسي

https://telegramos.net

الطلبات والاستجابات بصيغة JSON (Content-Type: application/json). تُعيد عمليات التصدير ملفاً (.xlsx / .csv) وتُعيد تنزيلات الوسائط بايتات خام.

المصادقة

أنشئ مفتاحاً من الإعدادات ← مفاتيح API، ثم أرسله في ترويسة X-API-Key:

curl -H "X-API-Key: tgp_your_key_here" \
     https://telegramos.net/api/accounts

يُعرض المفتاح مرة واحدة فقط عند إنشائه. يُخزَّن على شكل تجزئة SHA-256، لذا لا يستطيع أحد — بمن فيهم نحن — استرجاعه. إن فقدته فأنشئ مفتاحاً جديداً.

تغيير كلمة المرور أو إعادة تعيينها أو تعطيل المصادقة الثنائية أو تسجيل الخروج من كل الأجهزة يُلغي كل مفتاح صدر قبل تلك اللحظة، بشكل دائم.

أما جلسة المتصفح فتستخدم ملف تعريف ارتباط بدلاً من ذلك. المساران لا يختلطان أبداً: الطلب الذي يحمل X-API-Key يُصادَق عليه بذلك المفتاح وحده، وإدارة المفاتيح (/api-keys) ترفض المفاتيح عمداً — فلا يمكن لمفتاح أن يُنشئ مفتاحاً آخر أو يُلغيه (403).

الصلاحيات

الصلاحيات التي تحددها عند الإنشاء تُطبَّق على كل طلب.

الأفعال — واحد منها مطلوب دائماً:

المجالات — اختيارية. المفتاح الذي لا يحدد أي مجال يصل إلى كل المجالات؛ والمفتاح الذي يحدد مجالاً أو أكثر يبقى محصوراً فيها:

read وحدها تعني مفتاحاً للقراءة فقط على المنصة كلها. read + write + inbox تستطيع فعل أي شيء داخل صندوق الوارد فقط — وتحصل على 403 عند /api/accounts.

معرّفات الطلبات

كل استجابة تحمل ترويسة X-Request-ID. أرسل معرّفك الخاص ونحن نستخدمه؛ ولا ترسل شيئاً فنولّد واحداً:

curl -i -H "X-API-Key: $KEY" -H "X-Request-ID: my-job-42" \
     https://telegramos.net/api/accounts
...
x-request-id: my-job-42

يُسجَّل كل طلب من جهتنا بذلك المعرّف والمسار والحالة والمدة وبادئة المفتاح (وليس المفتاح نفسه أبداً) ومساحة العمل:

api.request service=account-service request_id=my-job-42 method=GET
path=/api/accounts status=200 duration_ms=144 auth=key:tgp_t24zIO user=<workspace>

سجّل المعرّف من جهتك. ما دامت المنصة في مرحلة البيتا فهذه أسرع طريقة لنا للعثور على استدعائك بالضبط — اذكره في تذكرة دعم ونستطيع سحب مسار الطلب كاملاً دون تخمين.

الأخطاء

الأخطاء تحمل حقل detail:

{"detail": "This API key is scoped to inbox — not 'accounts'."}

كائن مساحة عمل أخرى يُعيد 404 وليس 403 أبداً — فواجهة API لا تؤكد أبداً وجود معرّف ما.

الاصطلاحات

• المعرّفات هي UUID. أي مقطع مسار ليس UUID يُعيد 400 أو 404، وليس 500 أبداً.
• الإرسال يوضع في طابور، وليس متزامناً. نقاط النهاية التي تجعل الحساب يقوم بفعل تُعيد 202 مع task_id. ثم يُرسل الحساب وفق قواعد الإيقاع المضادة للحظر (انظر الحدود والحصص). استعلم عن المورد لرؤية النتيجة.
• كل شيء محصور بمساحة العمل. لا تمرّر معرّف مساحة عمل أبداً؛ فالمفتاح يحمله.
• نقاط نهاية القوائم تقبل limit/offset أو page/page_size بحسب المورد؛ وكلاهما اختياري.

الحسابات

المجال: accounts.

يحمل كل صف حساب هوية الحساب نفسه على Telegram بمجرد اتصال العامل: tg_user_id (معرّف Telegram الرقمي)، وtg_username، وtg_first_name، وtg_last_name. وtg_user_id هو القيمة التي تظهر في peer_id عندما تشير محادثة شخص آخر إلى هذا الحساب.

تقع خزنة الجلسة تحت الحساب نفسه: POST /api/accounts/{id}/vault/enable، و/disable، و/lock، و/unlock، و/rotate، مع GET /api/accounts/{id}/vault للحالة الحالية.

ملاحظة /group-invites هي أكثر نقاط النهاية صرامة في المنتج، لأن إضافة الأشخاص هي أسرع طريقة لخسارة حساب. ترفض بـ 409 ما لم يكن الحساب قد أنهى الإحماء، ويحمل حكماً نظيفاً من ⁦@SpamBot⁩ عمره أقل من 36 ساعة، وليس في وضع الرد فقط.

ملاحظة /sessions مخصصة للحسابات المستأجرة. على حساب تملكه تُجيب بـ 404 no live allocation for this account on your workspace — وهذه هي الإجابة الصحيحة، وليست عطلاً.

البروكسيات

الإحماء

حدود مكافحة الحظر

كل آلية تقييد في واجهة API هذه — ميزانيات التواصل البارد والردود، ومنحنى تصاعد الإحماء، وإبطاء PeerFlood، والسقف اليومي للحملات، والتباعد داخل المجموعة الواحدة، والتأخيرات الشبيهة بالبشر — هي حماية المنصة نفسها، وليست من Telegram. على خطة مدفوعة يمكنك تغييرها أو إيقافها لكل حساب عبر POST /api/accounts/{id}/safety، أو لكل الحسابات دفعة واحدة عبر POST /api/accounts/bulk/safety:

{
  "mode": "custom",
  "cold_hourly": 30, "cold_daily": 200,
  "reply_hourly": 120, "reply_daily": 600,
  "per_minute": 6, "min_gap_seconds": 3,
  "campaign_daily": 200, "group_spacing_minutes": 30,
  "content_filter": true, "spam_circuit": true,
  "warmup_ramp": false, "human_delay": true,
  "trial_cap": true, "spambot_throttle": true,
  "join_hourly": 40, "join_daily": 60,
  "forward_hourly": 20, "forward_daily": 200,
  "invite_hourly": 4, "invite_daily": 20,
  "report_hourly": 5, "report_daily": 20,
  "massdm_daily": 30, "massdm_delay_min": 45, "massdm_delay_max": 120,
  "massdm_warmup_ramp": true, "massdm_flood_hold": true, "massdm_circuit": true
}

mode تكون default (قواعد المنصة)، أو custom (الأرقام التي ترسلها؛ وكل ما تتركه يحتفظ بقيمة المنصة؛ و0 في per_minute أو min_gap_seconds أو campaign_daily أو group_spacing_minutes تعني بلا حد)، أو off (لا تقييد من جهة المنصة إطلاقاً). الأزواج join_* وforward_* وinvite_* وreport_* هي الميزانيات لكل إجراء؛ وحقول massdm_* تحكم موزّع الرسائل الجماعية المباشرة (massdm_daily ترفع السقف لكل حساب الذي يمكن لمهمة أن تطلبه، وmassdm_circuit تقرر ما إذا كانت المهمة تتوقف عندما تعود حساباتها مغمورة بالفيضان أو محظورة؛ وتبقى المهمة محمية ما دام أي من حساباتها يُبقي ذلك مفعّلاً). يعود الملف الحالي في حقل safety على كائن الحساب، ويسري مفعوله عند الإرسال التالي — دون إعادة اتصال. وتبقى قيود FloodWait والسبام الخاصة بـ Telegram نفسها سارية مهما ضبطت، ومخاطر حظر الحساب الذي خُففت حدوده تقع على عاتقك. الخطة المجانية تُجيب بـ 402. قاعدة «شخص واحد، حساب واحد» منفصلة عن هذا الملف وتبقى مفعّلة حتى في وضع off؛ بدّلها لكل حساب عبر /api/accounts/{id}/contact-policy.

الاستخراج

الاستخراج عملية سحب لمرة واحدة، وليس مراقبة: يمرّ حساب على سجل رسائل الهدف مرة واحدة ويستخرج أرقام الهواتف (أو الأنماط التي تعطيه إياها). قنوات البث تعمل كأهداف، لكن منشوراتها تأتي من القناة نفسها، لذا نادراً ما تُنتج عملية على قناة أي أرقام. لمتابعة ما تنشره قناة، استخدم مراقبة قناة بدلاً من ذلك. التجربة المجانية تحسب النتائج، وليس الرسائل المفحوصة، لذا فالعملية التي لا تجد شيئاً لا تكلّف شيئاً.

POST /api/scraping/jobs
{
  "name": "leads",
  "group_links": ["https://t.me/somepublicgroup"],
  "limit_per_group": 300,
  "max_accounts": 5,
  "patterns": [],
  "keyword_filter": []
}

patterns الفارغة تعني أرقام الهواتف؛ والأنواع المسبقة الأخرى هي email وusername وurl وprice، والنمط custom يقبل تعبيرك النمطي الخاص. group_links تقبل المجموعات العامة والقنوات العامة على حد سواء.

العملية العميقة المدفوعة تُحاسب لكل رسالة مفحوصة وتُعيد 402 إذا كانت المحفظة لا تغطي أسوأ الحالات. أما التجربة المجانية فتُحسب بطريقة مختلفة: هي 50 نتيجة، لذا فالعملية التي لا تجد شيئاً لا تكلّفك شيئاً. وهي محدودة من الجهة الأخرى أيضاً — تتوقف العمليات المجانية بعد قراءة 2,000 رسالة إجمالاً، مهما أعادت. GET /api/scraping/usage يُبلغ عن العدّادين كليهما (used / limit و scanned / scan_limit).

مكتشف المجالات المتخصصة

POST /api/niche/jobs
{
  "name": "crypto traders",
  "keywords": ["trading", "signals"],
  "active_within_days": 30,
  "msg_scan_limit": 3000,
  "max_accounts": 5,
  "extract_members": false
}

extract_members يُفرغ قوائم الأعضاء الخام؛ وهو معطّل افتراضياً لأنه القراءة الأكثر خطورة من حيث الحظر.

حزم العملاء المحتملين والمراقبات الدورية

الرسائل الجماعية المباشرة

POST /api/mass-dm/jobs
{
  "recipients": [{"tg_user_id": 123456789, "username": "someone"}],
  "message_text": "hi {first_name}",
  "account_ids": ["<account-uuid>"],
  "per_account_daily_cap": 20,
  "followups": []
}

قدّم إما recipients أو niche_job_id، وليس كليهما. قائمة الحجب تقبل قائمة:

POST /api/mass-dm/suppression
{"tg_user_ids": [777000777], "reason": "opted out"}

صندوق الوارد

المجال: inbox.

مرشحات القائمة: account_id، وpeer_type (user / bot / group / channel)، وstatus، وtags، وunread_only، وsource (campaign / mass_dm)، وcampaign_id، وjob_id، وpage، وpage_size.

reply-stats تتطلب source=campaign&campaign_id=... أو source=mass_dm&job_id=...؛ ومن دونها تُجيب بـ 422/400 مع تسمية ما هو مفقود.

مراقبة قناة

قناة البث محادثة كأي محادثة أخرى — peer_type فيها هو channel — لكن منشوراتها تحتاج إلى اشتراك صريح. القناة المزدحمة قد تدفع مئات الميغابايتات يومياً عبر بروكسي الحساب، لذا يُسقط المستمع منشورات أي قناة لم تطلبها. ولهذا لا تُظهر القناة التي انضممت إليها شيئاً حتى تضيفها: ليس الأمر نقصاً في الدعم، بل هو معطّل عن قصد.

لتشغيل واحدة:

1. انضم إلى القناة بأحد حساباتك (من داخل تيليجرام نفسه).
2. أضفها إلى قائمة المراقبة: POST /api/groups مع الجسم {"identifier": "@thechannel", "type": "channel", "via_account_id": "<uuid>"}.
3. اقرأ المنشورات: GET /api/conversations?peer_type=channel ثم GET /api/conversations/{id}/messages?after_msg_id=<last seen>.

identifier يقبل @username عاماً، أو رابط t.me/name، أو معرّف طرف رقمياً. type قد يكون group أو supergroup أو channel؛ وأي قيمة تمرّرها تُصحَّح من Telegram عند المزامنة الأولى، مع members_count وposts_per_day ومعرّف الطرف المعلَّم.

القنوات الخاصة ليس لها @username، ورابط الدعوة (t.me/+…) لا يحمل معرّف طرف، لذا لا يمكن لأي منهما تحديدها. زامن قائمة محادثات الحساب مرة واحدة فتظهر القناة بمعرّفها الرقمي، ثم تضيفها بالطريقة المعتادة:

POST /api/accounts/{account_id}/backfill-history?discover_only=true
   → registers the account's chats, pulls no messages, costs almost no proxy data

GET /api/conversations?peer_type=channel
   → the private channel is now listed, with its peer_id

POST /api/groups
{"identifier": "-1001234567890", "type": "channel", "via_account_id": "<uuid>"}

في لوحة التحكم، التدفق نفسه هو منتقي القنوات في المجموعات ← تتبّع مجموعة.

بمجرد التتبّع، تصل المنشورات الجديدة كأي رسالة واردة أخرى: عبر حدث websocket inbox.new_message وعبر webhook مشترك فيه. القناة التي كتمتها في Telegram تظل توصّل كليهما، مع conversation.muted: true، فلا يفوّت التكامل منشوراً أبداً؛ ولوحة التحكم وحدها تبقى صامتة.

peer_type له أربع قيم: user وbot وgroup وchannel. المجموعات الفائقة تكون group — الفرق لا يهم إلا في /api/groups، التي تُبلغ عن supergroup بعد مزامنتها الأولى.

بمجرد مراقبة قناة، تصل منشوراتها كأي رسالة أخرى: في GET /api/conversations/{id}/messages، وعبر حدث websocket inbox.new_message، ومن خلال webhook مشترك في inbox.new_message.

أمران *ليسا* هذه الميزة: /api/channel-syncs تعكس المنشورات من قناة إلى قناة أخرى تتحكم فيها (هي أداة إعادة توجيه، وليست قارئاً)، و /api/warmup/channels هي قائمة القنوات التي ينضم إليها حساب جديد أثناء الإحماء. لا يُعيد أي منهما محتوى القنوات. POST /api/groups/{id}/sync تحدّث أعداد الأعضاء والمنشورات فقط — ولا تجلب المنشورات.

متابعة محادثة

تُسجَّل الرسائل الواردة فقط للحسابات التي يكون مستمع الرسائل فيها مفعّلاً. الحساب الذي يحمل power_sender_only: true في GET /api/accounts يُرسل ولا يستلم أبداً، لذا تبقى محادثاته فارغة مهما استعلمت — فعّل المستمع له أولاً.

GET /api/conversations/{id}/messages تُصفّح إلى الخلف افتراضياً (before، وbefore_msg_id، وlimit حتى 200) — وهذا ما تريده واجهة المستخدم عندما تمرّر لأعلى.

أما المراقب فيريد العكس. مرّر after_msg_id مع telegram_msg_id لأحدث رسالة تحتفظ بها بالفعل فتحصل على ما وصل منذ ذلك الحين فقط، الأقدم أولاً:

GET /api/conversations/{id}/messages?after_msg_id=19626585&limit=200

telegram_msg_id يتزايد بشكل رتيب داخل المحادثة، لذا لا يكرّر المؤشر رسالة أبداً ولا يتخطى واحدة. احتفظ بأعلى معرّف رأيته، واستعلم به، فلا يبقى ما تحتاج إلى إزالة تكراره. after_msg_id يتجاوز before/before_msg_id إذا أرسلت كليهما.

كل رسالة تحمل direction: in للرسائل التي استلمها الحساب، وout للرسائل المُرسلة عبر هذه المنصة. الرسائل المكتوبة يدوياً في عميل Telegram على الحساب نفسه لا تُسجَّل — إذ يوصّلها Telegram كتحديثات صادرة خاصة بك ويتجاهلها المستمع.

للدفع بدلاً من الاستعلام الدوري، انظر Webhooks والأحداث الفورية أدناه.

الإرسال

الرد داخل محادثة قائمة:

POST /api/conversations/{id}/messages
{"content": "Thanks — one moment.", "media_key": null}

بدء محادثة مع شخص ليس في صندوق الوارد بعد:

POST /api/conversations
{
  "account_id": "<account-uuid>",
  "recipient_type": "username",
  "recipient": "someone",
  "content": "hello"
}

recipient_type يكون username أو phone أو user_id. كلتا نقطتي النهاية تُجيبان بـ 202:

{"task_id": "...", "conversation_id": null, "queued": true,
 "note": "Message queued. It will appear in the inbox once Telegram acknowledges the send."}

تظهر الرسالة في GET /api/conversations/{id}/messages بمجرد أن يؤكدها Telegram — عادةً خلال ثوانٍ، وأطول إذا كان الحساب عند سقف إيقاعه الساعي.

تُجيب حمايات مكافحة الحظر قبل وضع أي شيء في الطابور، فتعامل معها:

• حساب مقيَّد بسبب السبام يبدأ محادثة باردة: Telegram has limited this account, so it can't start new conversations right now — it can still reply to people who messaged it.
• الحساب في مرحلة الإحماء لا يستطيع البدء، بل الرد فقط.
• مرشح المحتوى يرفض النص بـ 422 ورمز بين قوسين مربعين — [REPEATED_CHARS]، [EXCESSIVE_CAPS]، [TOO_MANY_LINKS]، [BLOCKED_LINK]، [SPAM_PATTERN]. صحّح النص وأعد الإرسال؛ فإعادة إرسال النص نفسه تفشل دائماً.
• ميزانية الإرسال المتحركة تُجيب بـ 429 مع [HOURLY_MESSAGE_LIMIT] أو [DAILY_MESSAGE_LIMIT]. التواصل البارد محدود بـ 10 رسائل في الساعة و40 في اليوم لكل حساب. وبمجرد أن يردّ الطرف الآخر، تُحسب كل رسالة لاحقة في تلك المحادثة رداً وتحصل على 60 في الساعة و300 في اليوم بدلاً من ذلك — سواء أرسلتها عبر POST /api/conversations/{id}/messages أو واصلت استدعاء POST /api/conversations بالمستلم نفسه. النافذة الساعية تتحرك باستمرار، لذا تراجع بدلاً من إعادة كتابة الرسالة. الحساب الذي انخفضت درجة صحته يحصل على ميزانية أصغر بشكل متناسب. الخطط المدفوعة تستطيع تغيير هذه الميزانيات أو إزالتها لكل حساب — انظر حدود مكافحة الحظر؛ والملف المخصص يضيف [MINUTE_MESSAGE_LIMIT] و[MESSAGE_GAP_LIMIT] إلى رموز 429 المحتملة.

فقط 202 تعني أن الإرسال في طريقه. وإذا فشل لاحقاً رغم ذلك — حظر المستلم الحساب، أو انقطع الحساب عن الاتصال — يصل السبب في webhook من نوع inbox.message_failed يحمل task_id نفسه.

المجموعات والردود والقواعد والإشعارات

POST /api/groups
{"identifier": "https://t.me/somepublicgroup", "type": "group", "via_account_id": "<uuid>"}

POST /api/saved-replies
{"title": "greeting", "content": "Hi {first_name}", "variables": ["first_name"]}

POST /api/auto-reply-rules
{
  "account_id": "<account-uuid>",
  "match_type": "contains",
  "match_value": "price",
  "reply_text": "Our pricing is on the site.",
  "is_active": true,
  "delay_min": 2,
  "delay_max": 8
}

match_type يكون واحداً من any أو exact أو contains أو regex.

البوتات

المجال: bots.

الحملات

POST /api/campaigns
{
  "name": "launch",
  "message_a": {"text": "..."},
  "message_b": {"link": "https://t.me/channel/123"},
  "interval_minutes": 30,
  "delay_min_seconds": 15,
  "delay_max_seconds": 90,
  "assignments": [{"account_id": "<uuid>", "group_chat_ids": [-1001234567890]}]
}

الإنشاء لا يبدأها — استدعِ /start.

مزامنات القنوات وقاعدة بيانات البوت

POST /api/botdb/collections
{"name": "leads", "schema": {"fields": [{"key": "email", "type": "text"}]}}

POST /api/botdb/collections/{id}/records
{"data": {"email": "a@b.com"}}

تعريفات الحقول تستخدم key (وليس name)، والسجل الذي يحتوي data فيه على مفتاح غير مُعلَن يُرفض مع unknown field(s): ....

التحليلات

المجال: analytics.

مع إيقاف مفتاح التحليلات في مساحة العمل، تُعيد هذه سلاسل فارغة بدلاً من خطأ. نقاط نهاية الذكاء الاصطناعي تستهلك من حصة الذكاء الاصطناعي: تحقق من /api/analytics/ai/quota أولاً، وتوقّع 429 بمجرد نفادها.

سير العمل

المجال: tasks.

POST /api/workflows
{"name": "nightly", "definition": {"nodes": [], "edges": []}}

الدعم

بلا مجال — أي مفتاح يصل إلى هذه.

الهوية

تعديل الملف الشخصي (PATCH /auth/me)، مثل إدارة المفاتيح، يحتاج إلى جلسة متصفح — والمفتاح يُجيب بـ 403.

Webhooks

الـ webhook هو الطريقة المتينة لاستلام الأحداث: نكتب الحدث في قاعدة بياناتنا أولاً، ثم نرسله بطلب POST إلى عنوان URL الخاص بك ونعيد المحاولة عند الفشل. المقبس الذي انقطع أثناء نشرك يفقد الحدث؛ أما الـ webhook فلا.

أدرها من الإعدادات ← مفاتيح API ← Webhooks، أو عبر واجهة API (المجال inbox):

POST /api/webhooks
{"url": "https://your-server.example/telegramos",
 "events": ["inbox.new_message"],
 "description": "prod monitor"}

قائمة events الفارغة تعني كل الأنواع. حتى عشر نقاط نهاية لكل مستخدم؛ ويجب أن يكون عنوان URL عنوان http(s) عاماً (تُرفض العناوين الخاصة وعناوين الحلقة المحلية).

الأحداث

إغلاق الحلقة على إرسال. الإرسال يُجيب بـ 202 مع task_id ولا شيء غيره — فما زال على الحساب تمريره عبر إيقاع Telegram. اشترك في كلٍّ من inbox.new_message وinbox.message_failed لتعرف أيهما حدث: يصل النجاح كرسالة بـ direction: "out"، والفشل كحدث inbox.message_failed يحمل task_id نفسه، وerror_code (blocked_by_user، privacy_restricted، account_offline، cannot_write، account_banned، …) وجملة يمكنك عرضها للمستخدم.

الطلب الذي نرسله

POST /your-path
Content-Type: application/json
X-TGP-Event: inbox.new_message
X-TGP-Delivery: 82a91c75-7446-4ebe-8f79-3013cceaa1d7
X-TGP-Timestamp: 1787308800
X-TGP-Signature: v1=<hex>

{"id": "<delivery id>", "type": "inbox.new_message",
 "created_at": "2026-08-20T10:27:04+00:00",
 "data": {"user_id": "...", "account_id": "...", "conversation_id": "...",
          "message": {"id": "...", "direction": "in", "sender_id": 123, "sender_username": "...",
                      "content": "...", "sent_at": "..."},
          "conversation": {"id": "...", "title": "...", "peer_id": 123,
                           "peer_username": "...", "peer_type": "channel", "muted": false}}}

conversation.id ثابت لمحادثة حساب واحد مع طرف واحد، أياً كان اتجاه الرسالة: رسالة الحساب الصادرة والرد عليها يحملان conversation.id نفسه، لذا فهذا هو المفتاح الذي تشترك عليه. peer_id هو دائماً معرّف Telegram للطرف الآخر، وليس معرّف الحساب نفسه أبداً، وmessage.direction يقول من كتبها: out هو الحساب، وin هو الطرف الآخر. message.sender_id / message.sender_username يوضحان ذلك صراحةً: معرّف Telegram واسم المستخدم للطرف الآخر في in، ومعرّف الحساب نفسه في out (null لعضو مجموعة أو قناة، الذي لا نحمل هويته). حسابان من حساباتك يتحدثان معاً يُنتجان محادثتين (واحدة لكل حساب)، لكل منهما معرّفها الخاص.

التحقق من التوقيع. HMAC-SHA256 على {timestamp}.{raw body} بسرّك، مقارناً بالقيمة الست عشرية بعد v1=. استخدم البايتات الخام — فإعادة تسلسل JSON تغيّرها.

import hmac, hashlib

def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts = headers["X-TGP-Timestamp"]
    expected = "v1=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(headers["X-TGP-Signature"], expected)

الطابع الزمني داخل المادة الموقَّعة، لذا ارفض أي شيء أقدم من بضع دقائق فلا يمكن إعادة تشغيل تسليم مُلتقَط ضدك لاحقاً.

قواعد التسليم

• أي 2xx يُحسب قبولاً. أجب بسرعة وقم بالعمل بعد ذلك — فنحن نتخلى عن الطلب بعد 10 ثوانٍ ونعتبره فشلاً.
• الإخفاقات تُعاد المحاولة فيها بعد 10 ثوانٍ، ودقيقة، و5 دقائق، و30 دقيقة، وساعتين — ست محاولات إجمالاً — ثم يُعلَّم التسليم بـ failed.
• خمسة أحداث متتالية تستنفد كل المحاولات تُوقف نقطة النهاية؛ وتُظهر لوحة التحكم السبب. إعادة تشغيلها تُصفّر العدّاد.
• لا تُتبَع عمليات إعادة التوجيه. وجّهنا إلى عنوان URL النهائي.
• معرّف التسليم ثابت عبر المحاولات — اعتمد عليه في إزالة التكرار.
• تُحفظ سجلات التسليم الناجحة 7 أيام، والفاشلة 30 يوماً.

الأحداث الفورية

تبثّ لوحة التحكم التحديثات الحية عبر Socket.IO:

wss://telegramos.net/ws

صادِق بـ JWT للجلسة (auth.token)، أو ملف تعريف ارتباط الجلسة، أو مفتاح API — مرّره في auth.apiKey أثناء المصافحة أو في ترويسة X-API-Key. يحتاج المفتاح إلى read، وإذا كان محصوراً بمجالات أصلاً فيجب أن يتضمن inbox.

import { io } from 'socket.io-client'

const socket = io('https://telegramos.net', {
  path: '/ws',
  transports: ['websocket'],
  auth: { apiKey: process.env.TGP_API_KEY },
})
socket.on('inbox.new_message', (e) => console.log(e.conversation_id, e.message.content))

تصل الأحداث كرسائل Socket.IO مسمّاة: system.connected عند الاتصال، ثم inbox.new_message وnotification.new وaccount.status_change وaccount.power_changed وما شابهها؛ اشترك في حساب واحد عبر subscribe:account.

أمران يجب معرفتهما قبل أن تبني عليه:

• المتصفحات مقيَّدة. تتحقق المصافحة من Origin، ونطاقاتنا وحدها مسموح بها. العميل من جهة الخادم لا يُرسل Origin ويتصل دون مشكلة؛ أما صفحة على نطاقك الخاص فتُرفض. مرّر الاتصال عبر الواجهة الخلفية لديك.
• المقبس يوصّل مرة واحدة. كل ما يُنشر أثناء انقطاعك يضيع. استخدم webhooks للتسليم الذي لا يمكنك تحمّل فقدانه، أو صالِح عند إعادة الاتصال بـ after_msg_id.

ما لا تغطيه واجهة API

• الفرق والفوترة والمحفظة والسوق متاحة للجلسة فقط: /wallet، و/payments/*، و/subscriptions/*، و/billing/*، و/bundles/purchase، و/account-resale/*، و/referrals/*، و/teams/* تُجيب بـ 401 لمفتاح API أياً كان نطاقه. لا يوجد مسار عبر مفتاح لإنفاق المال أو استئجار حساب أو تغيير المقاعد — افعل ذلك في لوحة التحكم. الاستثناءان هما قراءتا الفهرس العام GET /listings وGET /bundles/availability، اللتان لا تحتاجان إلى أي مصادقة إطلاقاً.
• لا توجد SDK. HTTP خام؛ استخدم أي عميل لديك.
• لا حد للمعدل لكل مفتاح. الطلبات زهيدة، لكن الإجراءات وراءها تُضبط إيقاعياً لكل حساب بحدود مكافحة الحظر في الحدود والحصص، لذا فدفعة من الإرسالات توضع في الطابور بدلاً من أن تنطلق.

مثال عملي

الرد على أحدث محادثة غير مقروءة والانتظار حتى يصل الإرسال:

KEY="tgp_your_key_here"
BASE="https://telegramos.net"

CONV=$(curl -s -H "X-API-Key: $KEY" \
  "$BASE/api/conversations?unread_only=true&page_size=1" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -H "X-Request-ID: reply-$CONV" \
     -d '{"content":"Thanks for reaching out — one moment."}' \
     "$BASE/api/conversations/$CONV/messages"
# -> 202 {"task_id": "...", "queued": true, ...}

curl -s -H "X-API-Key: $KEY" "$BASE/api/conversations/$CONV/messages" | tail -c 400

مراقبة محادثة

ثلاثة أجزاء متحركة، بالترتيب الذي تُعدّها به.

1. أعد التعبئة مرة واحدة، إذا أردت السجل. POST /api/accounts/{id}/backfill-history تضع في الطابور استيراداً لمرة واحدة للمحادثات القائمة (الحسابات المملوكة، بلا وسائط، حتى 1000 رسالة لكل محادثة؛ وقنوات البث تُشمل فقط بعد تتبّعها عبر POST /api/groups). استعلم عن GET /api/accounts/{id}/backfill-history حتى تصير state هي done — الحالات هي queued وrunning وdone وcancelled، وidle تعني أنه لا مهمة مسجَّلة (إما لم تبدأ أبداً أو انتهت صلاحية الحالة بعد 6 ساعات). شغّلها مرة واحدة لكل حساب؛ فهي ثقيلة على بيانات البروكسي وكل ما بعدها يصل من تلقاء نفسه.

2. خذ التدفق الحي. سجّل webhook لحدث inbox.new_message. لا يلزم شيء آخر لتستمر الرسائل في التدفق إلى صندوق الوارد — فعامل الحساب يستمع بالفعل.

3. صالِح. بعد أي انقطاع من جهتك، تقدّم في كل محادثة إلى الأمام بـ after_msg_id من آخر معرّف خزّنته. هذا يُغلق الفجوة دون إعادة قراءة المحادثة.

KEY="tgp_your_key_here"
BASE="https://telegramos.net"

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"url":"https://your-server.example/telegramos","events":["inbox.new_message"]}' \
     "$BASE/api/webhooks"
# -> 201 {"id": "...", "secret": "whsec_...", ...}   <- store the secret

curl -s -H "X-API-Key: $KEY" \
     "$BASE/api/conversations/$CONV/messages?after_msg_id=$LAST_SEEN&limit=200"