بداية سريعة: من الصفر إلى التشغيل، بلا تخطي أي خطوة

المسار الافتراضي هو الاستضافة السحابية: هاتف فقط و~10 دقائق — بلا خادم، بلا برمجة. كل خطوة تخبرك أي شاشة تفتح وماذا تضغط، إضافة إلى العقبات التي يصطدم بها الناس فعلًا.

المحتويات قائمة التحقق الخطوة 1 · أنشئ بوتك في BotFather (مفتاحان حاسمان) الخطوة 2 · اربط البوت في Telegram Business الخطوة 3 · أنشئ مجموعة منتدى الكونسول الخطوة 4 · اختر واحدًا: ☁️ استضافة سحابية (موصى بها) / 💻 استضافة ذاتية الخطوة 5 · محادثة تجريبية استكشاف الأخطاء وإصلاحها

🧾 قائمة التحقق

1أنشئ بوتك في BotFather

في Telegram، ابحث عن @BotFather (ابحث عن شارة التحقق الزرقاء) وأجرِ هذه المحادثة:

🤖 BotFather
/newbot
BotFatherAlright, a new bot. How are we going to call it? Please choose a name for your bot.
LingoDesk Assistant
BotFatherGood. Now let's choose a username for your bot. It must end in bot.
my_lingodesk_bot
BotFatherDone! Use this token to access the HTTP API:
8123456789:AAHfK3xxxxxxxxxxxxxxxxxxxxxxxxx
Keep your token secure and store it safely…

1a. فعّل Secretary Mode (مطلوب؛ كان يُسمّى سابقًا "Business Mode")

⚠️ في مايو 2026 أعاد Telegram تسمية هذا المفتاح إلى Secretary Mode؛ قد تظل التطبيقات الأقدم تسميه Business Mode — وهو الشيء نفسه. نفّذ هذا داخل محادثة @BotFather (لا في صفحة ملف بوتك، ولا في إعدادات Telegram على هاتفك). واجهتان — كلتاهما تعمل:

الواجهة ① الأوامر الكلاسيكية — أرسل الرسائل فقط:

/mybots→ @my_lingodesk_bot→ Bot Settings→ Secretary Mode→ Turn on

الواجهة ② لوحة الإدارة الجديدة — اضغط زر Open الأزرق بجوار صندوق رسائل BotFather:

Open (اللوحة)→ اختر بوتك→ Settings→ Mode Settings→ فعّل Secretary Mode
لا تجده؟ ① له اسمان: Secretary Mode في التطبيقات الجديدة، وBusiness Mode في الأقدم — ابحث عن أيهما؛ ② تأكد أنك داخل @BotFather، لا في إعدادات بوتك الخاص؛ ③ هذا المفتاح لا علاقة له بـ Telegram Premium — Premium مهم فقط للربط من جهة حسابك في الخطوة 2؛ يمكن لأي شخص تفعيل هذا المفتاح.
بدون Secretary Mode، يعرض Telegram نافذة منبثقة — "This bot doesn't support Telegram Business yet" — عند محاولة إضافته في الخطوة 2. وهو أكثر العوائق شيوعًا على الإطلاق. فعّل المفتاح: يسري مفعوله فورًا، بلا حاجة لإعادة إنشاء البوت؛ فقط أعد محاولة الإضافة.

1b. عطّل Group Privacy (مطلوب)

/mybots→ @my_lingodesk_bot→ Bot Settings→ Group Privacy→ Turn off
الخصوصية مفعّلة افتراضيًا، وطالما هي مفعّلة فإن البوت لا يستطيع رؤية الردود التي تكتبها في مجموعة الكونسول — والعَرَض هو "أكتب في الموضوع ولا يحدث شيء". عطّلها (يجب أن يقول BotFather Privacy mode is disabled).

2اربط البوت في Telegram Business

على تطبيق Telegram على الهاتف (هذا الإعداد موجود حاليًا على الهاتف فقط):

⚙️ الإعدادات→ 💼 Telegram Business→ 🤖 Chatbots

في التطبيقات الأحدث يُسمّى هذا العنصر "Chat Automation" — تسمية مختلفة، ونفس المدخل.

  1. اكتب اسم مستخدم بوتك (مثل my_lingodesk_bot) في صندوق البحث واختره.
  2. الأذونات: فعّل "Reply to messages" — بدونها يستطيع البوت القراءة لكن لا يمكنه الإرسال نيابةً عنك أبدًا.
  3. بالنسبة إلى "أي المحادثات"، اختر All 1:1 Chats؛ وأضف أي جهات اتصال خاصة تريد إبقاءها خارج المُرحِّل إلى قائمة Excluded Chats.
بمجرد الربط، تُرسَل نسخة صامتة من كل رسالة خاصة تصلك إلى البوت — الطرف الآخر لا يلاحظ شيئًا، وتجربة محادثتك الخاصة لا تتغير إطلاقًا.

3أنشئ مجموعة منتدى الكونسول

هذه المجموعة هي طاولة عملك: موضوع واحد لكل جهة اتصال، تظهر بداخله بطاقات رسائل ثنائية اللغة.

  1. أنشئ مجموعة: New ← New Group، أضف بوتك بوصفه العضو الوحيد (ابحث عن اسم مستخدمه). سمّها بأي اسم، مثل "LingoDesk Console".
  2. فعّل Topics: افتح المجموعة ← اضغط الاسم لعرض الملف ← Edit ← فعّل Topics. تُرقّى المجموعة إلى مجموعة خارقة وتحصل على قائمة مواضيع.
  3. رقِّ البوت إلى مشرف: الملف ← Administrators ← Add Admin ← بوتك ← حدّد "Manage Topics" (اترك الباقي كما هو) ← احفظ.
البوت ينشئ موضوعًا تلقائيًا لكل جهة اتصال. وبدون صلاحيات المشرف + "Manage Topics" يفشل ذلك — والعَرَض هو "راسلني عميل لكن لا شيء يظهر في المجموعة".
المجموعة تحتاج إليك وإلى البوت فقط — لا بشر آخرين. وإن أضفت شريكًا، فإن ردوده في أي موضوع تُطلق الترجمة والإرسال تمامًا كردودك.

4اختر واحدًا: ☁️ استضافة سحابية أو 💻 استضافة ذاتية

كل ما يخص الهاتف قد اكتمل. الآن اختر مسارك — لا خادم لديك؟ اختر A: لا شيء لتثبيته.

☁️ الخيار A · استضافة سحابية (موصى به: بلا خادم، بلا برمجة، فوري)

  1. راسِل بوت التفعيل الرسمي @LingoDeskbot في رسالة خاصة، أرسل /start، ثم الصق BOT_TOKEN من الخطوة 1 مباشرة في المحادثة.
  2. تفعيل تلقائي فوري: بمجرد التحقق من الرمز يرد بـ "🎉 Activated" (ويحذف رسالة الرمز). تغطي الخطة المجانية 300 رد مترجم/شهريًا؛ ارتقِ إلى Pro (500 ⭐/شهريًا) في أي وقت للحصول على استخدام غير محدود. محرك الترجمة على حسابنا — بلا مفاتيح API للتسجيل.
  3. اتبع رده لإكمال الربط، ثم أرسل /bind في مجموعة الكونسول — يرد البوت بـ "✅ bound" وتكون قد انتهيت. انتقل إلى الخطوة 5 للاختبار. راسله /status في أي وقت، أو /native en لضبط لغتك أنت.
قلق من تسليم الرمز؟ يُخزَّن مشفَّرًا ويُستخدَم فقط لترحيل المحادثات التي أذنت بها في Telegram Business — وتبقى المتحكم: ألغِه في أي وقت في BotFather (‏/mybots ← API Token ← Revoke) فيموت الرمز القديم فورًا.

💻 الخيار B · استضافة ذاتية (جهازك الخاص، بياناتك الخاصة)

أولًا احصل على مفتاح ترجمة من console.anthropic.com ← API Keys ← Create Key (‏sk-ant-…؛ بضعة دولارات من الرصيد تكفي وقتًا طويلًا بمعدل ~0.001$ لكل رسالة). ثم:

git clone https://github.com/sanxiaozi/lingodesk.git cd lingodesk npm install cp .env.example .env # open .env — only BOT_TOKEN and ANTHROPIC_API_KEY are required npm run db:push # initialize the database (first run only) npm run dev 🚀 LingoDesk is up, bot = @my_lingodesk_bot

بمجرد أن ترى الشعار، أرسل /bind في مجموعة الكونسول لربطه (يُكتشف معرّف المجموعة ومعرّفك تلقائيًا — لا أرقام للبحث عنها). على خادم، يكون Docker أمرًا واحدًا: docker compose up -d — انظر GitHub README.

رمز بوت واحد = نسخة قيد التشغيل واحدة عالميًا (‏409 Conflict = هناك عملية قديمة لا تزال تحتفظ به). إن كنا نستضيفك، فلا تشغّل نسخة محلية أيضًا.

5محادثة تجريبية

من حساب Telegram مختلف (حساب ثانٍ أو صديق)، أرسل رسالة خاصة بلغة أجنبية إلى حسابك الشخصي (لا إلى البوت!) — قل مثلًا "Hola, ¿cuánto cuesta?" بالإسبانية. خلال ثوانٍ، يجب أن يظهر في مجموعة الكونسول موضوع جديد باسم المُرسِل:

📋 LingoDesk Console · الموضوع: @amigo_es
my_lingodesk_bot🆕 جهة اتصال جديدة @amigo_es (es)
الأصل: Hola, ¿cuánto cuesta?
🌐 مرحبًا، كم يكلّف؟
─────
↳ اكتب هنا بلغتك — يخرج بلغة es، باسمك أنت
الباقة A بسعر 100$ وتشمل كل المزايا.
my_lingodesk_bot📤 معاينة الترجمة (‏←es)، لا تُرسَل إلا بعد تأكيدك:

El paquete A cuesta 100 dólares e incluye todas las funciones.

(رسالتك: Package A is $100…)

[ ✅ إرسال إلى العميل ] [ ✏️ إلغاء ]

اضغط "✅ إرسال إلى العميل" — يرى الطرف الآخر حسابك الشخصي يرد بإسبانية طليقة. الحلقة كاملة الآن قيد التشغيل 🎉

🔧 استكشاف الأخطاء وإصلاحها

راسلني عميل لكن لا شيء يظهر في مجموعة الكونسول

تحقق بالترتيب: ① BotFather ← Business Mode مفعّل (الخطوة 1a)؛ ② Telegram Business ← Chatbots فيه بوتك مربوط وتلك المحادثة ضمن النطاق (الخطوة 2)؛ ③ البوت مشرف في المجموعة بصلاحية "Manage Topics" (الخطوة 3)؛ ④ مجموعة الكونسول مربوطة — أرسل /bind فيها؛ ⑤ للمستضيفين ذاتيًا: عملية البوت لا تزال تعمل بلا أخطاء.

نافذة منبثقة عند إضافة البوت: "This bot doesn't support Telegram Business yet"

Business Mode غير مفعّل في BotFather (الخطوة 1a). اذهب إلى @BotFather ← /mybots ← بوتك ← Bot Settings ← Business Mode ← Turn on. يسري مفعوله فورًا — بلا حاجة لإعادة إنشاء البوت أو إعادة إرسال الرمز؛ فقط عد إلى Telegram Business ← Chatbots وأضفه من جديد. يمكن لمستخدمي الاستضافة السحابية مراسلة @LingoDeskbot بـ /status للتحقق من هذا البند.

أرسل /bind في المجموعة ولا يحدث شيء

① Group Privacy لا يزال مفعّلًا (الخطوة 1b) — عطّله، ثم أزل البوت وأعد إضافته؛ ② Topics غير مفعّل في المجموعة؛ ③ لمستخدمي الاستضافة السحابية: تأكد أن @LingoDeskbot رد بـ "Activated" (راسله /status للتحقق)؛ ④ للمستضيفين ذاتيًا: تأكد أن العملية قيد التشغيل.

هل تسليم BOT_TOKEN للاستضافة السحابية آمن؟

يُخزَّن الرمز مشفَّرًا ويُستخدَم فقط لترحيل المحادثات ضمن النطاق الذي أذنت به في Telegram Business — ويمكنك استثناء جهات الاتصال الخاصة (الخطوة 2). تبقى المتحكم: ألغِه في أي وقت عبر BotFather ← /mybots ← API Token ← Revoke؛ فيموت الرمز القديم فورًا وتتوقف الخدمة. لاستئنافها، فقط أرسل الرمز الجديد إلى @LingoDeskbot.

أكتب في موضوع والبوت لا يفعل شيئًا

في تسع حالات من عشر يكون السبب Group Privacy لا يزال مفعّلًا (الخطوة 1b). BotFather ← Bot Settings ← Group Privacy ← Turn off، ثم أزل البوت من المجموعة وأعد إضافته (التغيير لا يسري إلا بعد إعادة الانضمام)، ورقِّه إلى مشرف من جديد.

التشغيل يفشل بـ 409 Conflict

نسختان تعملان على الرمز نفسه. اعثر على العملية القديمة وأوقفها (‏Ctrl+C أو pkill -f "tsx.*main.ts")، انتظر عشر ثوانٍ، ثم شغّل من جديد.

"إرسال إلى العميل" يفشل بخطأ عام

تحقق بترتيب الاحتمال: ① إذن "Reply to messages" معطّل (الأكثر شيوعًا) — Settings ← Telegram Business ← Chat Automation (Chatbots) ← بوتك ← فعّل "Reply to messages"؛ بدونه يستطيع البوت القراءة لكن لا يرسل أبدًا؛ ② محادثة العميل خارج نطاق المحادثات المتاحة للبوت (الصفحة نفسها)؛ ③ لم يراسلك العميل منذ أكثر من 24 ساعة — يمنع Telegram الإرسال الذي يبدأه البوت؛ اطلب منه إرسال أي شيء أولًا. لمستخدمي الاستضافة السحابية: راسِل @LingoDeskbot بـ /status — سطر "إذن الرد" يعطيك الإجابة مباشرة.

"إرسال إلى العميل" يفشل: جهة الاتصال غير نشطة منذ وقت طويل

قيد من Telegram: إذا ظلت المحادثة خاملة وقتًا طويلًا، فلا يستطيع البوت البدء نيابةً عنك (‏BUSINESS_PEER_USAGE_MISSING). اطلب منهم إرسال أي شيء لإعادة التنشيط، أو رد يدويًا من هاتفك هذه المرة.

الإرسال يفشل: اتصال العمل غير صالح

اذهب إلى Settings ← Telegram Business ← Chatbots، أزل البوت وأعد إضافته — أو ببساطة انتظر رسالة العميل التالية، التي تتيح للبوت التقاط اتصال جديد تلقائيًا.

اللغة المكتشفة خاطئة / أريد لغة هدف مختلفة

تُثبَّت اللغة عند أول رسالة لجهة الاتصال (لتفادي التذبذب في النصوص القصيرة). أرسل /lang code في موضوع تلك الجهة لتصحيحها، مثل /lang pt (البرتغالية) أو /lang ar (العربية).

بعد إعادة التشغيل، توقفت أزرار "إرسال / إلغاء" القديمة عن العمل

المعاينات المعلّقة تعيش في الذاكرة وتنتهي صلاحيتها عند إعادة التشغيل (سيخبرك الزر بذلك). فقط اكتب ردك من جديد في الموضوع. جهات الاتصال وسجل المحادثة يعيشان في قاعدة البيانات — لا شيء يُفقد.

🎉 كل شيء يعمل؟

من الآن فصاعدًا، يكتب العملاء بأي لغة يحبونها — وأنت تكتب بلغتك فقط. إن تعطّل شيء، فراجع أولًا قائمة استكشاف الأخطاء أعلاه؛ وإن بقيت عالقًا، راسلنا بالبريد الإلكتروني مع لقطة شاشة لخطأ الطرفية.

✉️ [email protected]