REST API — أتمِت Telm من كودك الخاص

1ما الذي يتيحه لك API

يمنح Telm REST API شفرتك الخاصة الصلاحيات نفسها التي تمنحها لوحة التحكم: مرّر أي نص عبر مسار مكافحة الرسائل المزعجة، واستعلم عن مستخدم Telegram قبل أن تسمح له بالدخول، واقرأ إعدادات حماية المجموعة وغيّرها، وأدِر القواعد المخصّصة والقوائم البيضاء، واسحب سجلّ الإشراف والتحليلات، وسجّل Webhooks للأحداث في الوقت الحقيقي.

وهكذا يتحوّل Telm من بوت يعيش داخل مجموعاتك إلى بنية تحتية يمكنك ربطها في أي مكان — نموذج تسجيل في موقع، أو بوت CRM، أو بوتات Telegram الخاصة بك، أو سكربت يضبط مئة مجموعة دفعة واحدة.

• عنوان القاعدة: api.telm.com/api/public/v1 — مسار ثابت ذو إصدار (v1 هو إصدار العقد).
• كل طلب وكل رد بصيغة JSON عبر HTTPS.
• الوثائق التفاعلية ومواصفة OpenAPI 3.1 المقروءة آليًا متاحة في صفحة المطوّرين — حمّل المواصفة في Postman أو مولّد شفرة أو وكيل ذكاء اصطناعي لتجهيز تكامل خلال دقائق.
• الاستدعاءات المقيَّسة تعيد الترويسات X-Quota-Limit وX-Quota-Used وX-Quota-Reset في كل رد.

2كيف يمرّ الطلب عبر Telm

يقع API العام على بادئة مسار خاصة به، /api/public/، منفصلة عن لوحة التحكم. يُصادَق كل استدعاء بمفتاح API بدلًا من جلسة متصفح، ويُتحقَّق منه مقابل خطتك وحصتك، ويُشغَّل على المحرّك الحي نفسه الذي يشرف على مجموعاتك، ثم يُعاد الرد بصيغة JSON.

ولأن API يصل إلى المحرّك والبيانات نفسها التي يصل إليها البوت، فكل ما يمكنك رؤيته أو تغييره في لوحة التحكم يمكنك فعله في الشفرة أيضًا — وأي تغيير تجريه في الشفرة يظهر في لوحة التحكم فورًا.

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

3المصادقة بمفاتيح API

يُصادَق كل طلب بمفتاح API على الشكل tk_live_ متبوعًا بأحرف عشوائية — لا بتسجيل دخولك إلى لوحة التحكم. تنشئ المفاتيح في حسابك وترسل المفتاح في ترويسة Authorization كرمز Bearer، أو في ترويسة X-API-Key.

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

• أرسل المفتاح بالشكل Authorization: Bearer tk_live_your_key_here (ترويسة X-API-Key تعمل أيضًا).
• تحمل المفاتيح نطاق قراءة أو كتابة — القراءة لطلبات GET، والكتابة لأي شيء يغيّر البيانات. المفتاح المقصور على القراءة لا يمكنه الإنشاء أو التعديل.
• يمكنك الاحتفاظ بما يصل إلى عشرة مفاتيح نشطة في آنٍ واحد، فتستخدم مفتاحًا منفصلًا لكل سكربت أو خدمة.
• المفتاح المفقود أو غير الصالح يعيد 401؛ والمفتاح الذي يفتقر إلى النطاق المطلوب يعيد 403 insufficient_scope.

4نقاط النهاية المتاحة

ينتظم API حول فحوص الرسائل المزعجة والمستخدمين، وإدارة المجموعات، والخدمة الذاتية للحساب. نقطة نهاية فحص الرسائل المزعجة الفردية مفتوحة لكل خطة؛ أما بقية الواجهة فجزء من Pro وBusiness.

• POST /spam/check — مرّر نصًا واحدًا عبر محرّك القواعد نفسه الذي يشرف على حركة المرور الحية (كل الخطط). يمكن تفعيل فحص اختياري بالذكاء الاصطناعي على Pro فأعلى.
• POST /spam/check-batch — افحص حتى 20 نصًا في استدعاء واحد، بالقواعد فقط (Pro+).
• POST /users/check — استعلم عن مستخدم Telegram: حالة CAS، وإشارات قرارات الرسائل المزعجة في Telm، والسمعة في مجموعاتك (Pro+).
• GET /groups وGET /groups/{id} — اعرض مجموعاتك واقرأها (Pro+).
• GET وPATCH /groups/{id}/settings — اقرأ إعدادات حماية المجموعة وغيّرها (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — أدِر قواعد الإشراف المخصّصة (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — أدِر القائمة البيضاء للمجموعة (Pro+).
• GET /groups/{id}/journal وGET /groups/{id}/analytics — اقرأ سجلّ الإشراف والتحليلات (Pro+).
• GET/POST/PATCH/DELETE /webhooks — أدِر Webhooks أحداث الوقت الحقيقي (Pro+).
• GET /usage وGET /me — تحقّق من حصتك ومعلومات مفتاحك؛ ولا تستهلكان الحصة أبدًا (كل الخطط).

5نقطة نهاية فحص الرسائل المزعجة بالتفصيل

‏POST /spam/check هي قلب API ونقطة النهاية الوحيدة التي يمكنك تجربتها على أي خطة. أرسل جسم JSON يحتوي النص المراد فحصه؛ فيعيد الرد حكمًا، ودرجة رقمية، وقيمة ثقة، وإجراءً موصى به يمكنك تطبيقه في منتجك الخاص.

يمكن أن يصل النص الواحد إلى 10,000 حرف. على Pro فأعلى يمكنك اختيار فحص بالذكاء الاصطناعي للحالات الأصعب، يُخصَم من رصيد يومي منفصل لفحوص الذكاء الاصطناعي. وللأحجام الكبيرة، تفحص نقطة النهاية الدُّفعية حتى 20 نصًا في استدعاء واحد وتحتسب الحصة لكل عنصر.

• استخدم الحكم والدرجة لتقرّر ما يفعله منتجك — احجب إرسال نموذج، أو ضع علامة على عميل محتمل، أو احذف رسالة تلقائيًا في بوتك الخاص.
• نقطة النهاية الدُّفعية تعمل بالقواعد فقط؛ أما سلّم الذكاء الاصطناعي فمتاح على نقطة نهاية النص الفردي وحدها.
• أجسام الطلبات محدودة الحجم (نحو 64 KB للفحص الفردي، و256 KB للدُّفعة)؛ والأجسام التي تتجاوز ذلك تعيد 413.

6الخطط وحدود المعدّل والحصص اليومية

يُقاس الوصول بطريقتين: حد معدّل لكل دقيقة (سقف اندفاع) وحصة استدعاءات يومية تُعاد عند منتصف الليل UTC. كلاهما يُحسَب لكل حساب ويُشارَك عبر كل مفاتيح API لديك. يمكنك تجربة نقطة نهاية فحص الرسائل المزعجة الفردية على أي خطة، لكن التكامل الحقيقي الذي يمسّ القواعد والإعدادات والفحوص الدُّفعية وWebhooks يحتاج إلى Pro أو أعلى.

• Free — 100 استدعاء في اليوم، فحص الرسائل المزعجة فقط.
• Pro — 10,000 استدعاء في اليوم، وAPI الكامل وWebhooks، إضافةً إلى 1,000 فحص بالذكاء الاصطناعي يوميًا.
• Business — 50,000 استدعاء في اليوم، وAPI الكامل وWebhooks، إضافةً إلى 10,000 فحص بالذكاء الاصطناعي يوميًا.
• تتدرّج حدود المعدّل لكل دقيقة أيضًا — 60 طلبًا في الدقيقة على Free، و600 على Pro، و1,800 على Business.
• ‏GET /usage وGET /me لا تُحتسَبان أبدًا من حصتك، فيمكنك التحقق من ميزانيتك المتبقية في أي وقت.

7معالجة الأخطاء ورموز الحالة

يستخدم API رموز حالة HTTP القياسية مع رمز خطأ مقروء آليًا في جسم الرد. ابنِ عميلك ليقرأ هذه الرموز فيتراجع أو يعرض اقتراح ترقية، بدل إعادة المحاولة عشوائيًا.

حين تتجاوز حصتك اليومية، يعيد الاستدعاء المقيَّس 429 مع رمز daily_quota_exceeded، وترويسة Retry-After، وجسم يذكر خطتك وحدّك وعدد المُستخدَم ووقت الإعادة وتلميح ترقية. أما نقاط النهاية التي تحتاج إلى خطة أعلى فتعيد 403 plan_required مع الخطة المطلوبة.

• 401 — مفتاح API مفقود أو غير صالح.
• 403 plan_required — تحتاج نقطة النهاية إلى Pro أو أعلى.
• 403 insufficient_scope — يفتقر المفتاح إلى نطاق الكتابة لاستدعاء يغيّر البيانات.
• 429 daily_quota_exceeded أو rate_limit_exceeded — انتظر وقت الإعادة أو رقِّ خطتك؛ واحترم ترويسة Retry-After.
• اقرأ ترويسات الرد X-Quota-* لتسبق الحدّ.

8أفضل الممارسات لتكامل متين

بضع عادات تُبقي التكامل موثوقًا وآمنًا مع نموّه.

• خزّن المفاتيح في مدير أسرار، لا في شفرة جانب العميل أو مستودع git أبدًا؛ واستخدم مفتاحًا منفصلًا لكل خدمة كي تبطل واحدًا دون تعطيل الآخرين.
• راقب الترويستين X-Quota-Used وX-Quota-Limit (أو استعلم دوريًا عبر GET /usage) وأبطئ قبل أن تصطدم بالحدّ، لا بعده.
• عند 429، احترم Retry-After وتراجع؛ وعند 403 plan_required، اعرض اقتراح ترقية بدل إعادة المحاولة.
• للتفاعل في الوقت الحقيقي، فضّل Webhooks على الاستطلاع الدوري — دع Telm يدفع الأحداث إليك.
• دوّر المفاتيح دوريًا، وفورًا إن احتُمل تسرّب أحدها.

9سيناريوهات التكامل الشائعة

يُستخدَم API لما هو أبعد بكثير من الإشراف على رسائل Telegram.

• التسجيل في المواقع والتطبيقات: مرّر النص المُرسَل أو أسماء المستخدمين عبر POST /spam/check قبل قبول تسجيل أو تعليق.
• بوتات Telegram الخاصة بك: أعِد استخدام ذكاء Telm في بوت لا يديره Telm باستدعاء نقطة نهاية الفحص من معالج الرسائل لديك.
• الضبط الجماعي: اكتب سكربتًا يطبّق القواعد والقوائم البيضاء والإعدادات نفسها على عشرات المجموعات عبر نقاط نهاية الإعدادات والقواعد.
• البيانات والتنبيهات: سجّل Webhooks لبثّ أحداث الإشراف إلى مستودع بيانات أو لوحة معلومات أو قناة تنبيه في الوقت الحقيقي.