دمج Telegram

اربط الـ Agent الخاص بك بـ Telegram ودَع المستخدمين يتحدّثون معه مباشرةً داخل تطبيق Telegram.

نظرة عامة

يوفّر دمج Telegram ما يلي:

• ردود بثّ مباشر (Bot API 9.5 sendMessageDraft مع آلية احتياطية لتعديل الرسائل)
• رسائل صوتية تُنسخ تلقائيًا باستخدام Whisper
• تنسيق MarkdownV2 يُعرض بشكل نظيف في كل مرة
• حملات الروابط العميقة (deep-link) مع رسائل ترحيب مخصّصة وردود مقترحة
• تفاعلات إيموجي بنقرة واحدة مع تصنيف المشاعر
• أوامر slash مدمجة (/start و/help و/reset و/new)
• الرسائل المباشرة ومحادثات المجموعات (جلسات لكل مستخدم في المجموعات)
• Storefront مدمج داخل الروبوت — كتالوج منتجات متعدّد الصفحات، ودردشة ذكية لكل منتج، وأخذ طلبات بسيط، كل ذلك داخل Telegram (مجانًا على كل خطة)
• مساعد طيّار اختياري بـ Telegram Premium لمستخدمي Premium (عملية دمج منفصلة)
• Saba on Telegram للمشغّلين (عملية دمج منفصلة)

المتطلّبات المسبقة

• حساب Telegram
• الوصول إلى BotFather (أداة إنشاء الروبوتات في Telegram)

خطوات الإعداد

1. أنشئ روبوت Telegram

1. افتح Telegram وابحث عن @BotFather
2. ابدأ محادثة وأرسل /newbot
3. اتبع التعليمات:
   • أدخل اسمًا لروبوتك (مثل “My Support Bot”)
   • أدخل اسم مستخدم (يجب أن ينتهي بـ “bot”، مثل “mysupportbot”)
4. سيمنحك BotFather رمز الروبوت (Bot Token) — احفظه بأمان

2. اربطه بـ Cuneiform Chat

1. انتقل إلى Integrations في الشريط الجانبي
2. افتح بطاقة Telegram
3. الصق رمز الروبوت (Bot Token)
4. انقر على Connect

3. اضبط روبوتك

إعدادات اختيارية للروبوت عبر BotFather:

• /setdescription — ما يفعله الروبوت
• /setabouttext — معلومات في ملف الروبوت الشخصي
• /setuserpic — صورة الملف الشخصي لروبوتك

4. اختبر روبوتك

1. اعثر على روبوتك في Telegram بالبحث عن اسم المستخدم الخاص به
2. ابدأ محادثة بـ /start
3. أرسل رسالة وتأكّد من حصولك على رد

كيف يعمل

المستخدم يرسل رسالة → Telegram → Cuneiform Chat → الـ Agent يعالجها → يُرسَل الرد

تُعالَج الرسائل في الوقت الفعلي. يبحث الـ Agent في المحتوى الخاص بك ويولّد الردود بناءً على إعداداتك.

الميزات

ردود البثّ المباشر

يصل رد الروبوت خلال أجزاء من الثانية وينمو في مكانه بينما يفكّر الـ Agent — باستخدام sendMessageDraft الأصلي في Telegram (Bot API 9.5) حيثما كان مدعومًا، مع آلية احتياطية مُنظَّمة لتعديل الرسائل في الأماكن الأخرى. لا مزيد من 5–15 ثانية من الصمت بين السؤال والإجابة.

الرسائل الصوتية

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

تنسيق MarkdownV2

يُعرض النص الغامق والمائل وكتل الكود والقوائم والروابط تمامًا كما قصدها الـ Agent — بلا markdown معطّل أو علامات نجمية شاردة. تُدار آلية الهروب (escaping) مركزيًا في المنصّة بحيث يبقى كل رد نظيفًا. MarkdownV2 هو الوضع الافتراضي؛ ووضع HTML متاح لكل عملية دمج إذا لزم الأمر.

الروابط العميقة وحملات الإحالة

أنشئ روابط t.me/your-bot?start=your-code من بطاقة الدمج. يمكن أن يحمل كل رمز رسالة ترحيب مخصّصة وحتى ثلاثة ردود مقترحة. يُتتبّع معدّل النقر والمستخدمون الفريدون وتحويل المحادثة لكل رمز — مفيد للحملات الإعلانية ورموز QR وإسناد القنوات المتعددة.

تفاعلات الإيموجي بنقرة واحدة

يتفاعل المستخدمون مع رسائل الروبوت بـ 👍 أو ❤ أو 😡 أو أي إيموجي. يُقرّ الروبوت بالنبرة الصحيحة عبر ردود قصيرة للإقرار بالتفاعل. يربط مصنّف مدمج أي إيموجي بإشارة إيجابية أو سلبية أو محايدة يمكنك تحليلها لاحقًا. نشط حاليًا في الرسائل المباشرة (DMs).

أوامر slash

تسجّل عملية الدمج قائمة أوامر افتراضية مع Telegram عند الربط، بحيث يرى المستخدمون /start و/help و/reset وأي أوامر مخصّصة تؤلّفها في قائمة الإكمال التلقائي الأصلية في Telegram. تُعالَج /start و/help و/reset و/new ضمنيًا بتكلفة ذكاء اصطناعي صفرية. اسحب لإعادة الترتيب؛ حتى 32 إدخالًا.

الرسائل المباشرة

يتحدّث المستخدمون مع روبوتك وجهًا لوجه لمحادثات دعم خاصة. لكل مستخدم جلسته الخاصة.

محادثات المجموعات

أضف روبوتك إلى محادثات المجموعات:

1. أضف الروبوت إلى مجموعة
2. اجعله مشرفًا (للوصول الكامل إلى الرسائل — راجع خصوصية المجموعة أدناه)
3. يذكر المستخدمون الروبوت (@your_bot) أو يردّون على رسائله

لكل مستخدم في المجموعة سلسلة محادثته الخاصة — لا يخلط الروبوت الجلسات بين الأعضاء. مجموعات مواضيع المنتدى (forum-topic) مدعومة؛ تبقى السلاسل محصورة في موضوعها.

Storefront مدمج داخل الروبوت

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

يُربَط تلقائيًا عند الاتصال: يفتح زر قائمة الدردشة الـ Storefront، بعنوان “Shop” إذا نشرت منتجًا أو “Open” بخلاف ذلك. متاح على كل خطة بما في ذلك الفترة التجريبية المجانية.

دليل الميزة الكامل — المُؤلّف، والكتل (blocks)، والثيمات (themes)، والدردشة لكل منتج، ودعوات إجراء الطلب (order CTAs)، وحدود الخطط — موجود في صفحة مخصّصة:

← Telegram Storefront للإعداد الكامل، ومرجع الكتل، وتدفّق العميل.

تُثبَّت لوحة دعم صغيرة في Help Center في نهاية قائمة صفحات الـ Storefront للأسئلة الشائعة العارضة واختصارات سؤال الروبوت. معظم المتاجر لا تعتمد عليها كثيرًا — فالمنتجات ودعوات الطلب تجيب عن أسئلة تدفّق الشراء على الـ Storefront نفسه. ألّف الإدخالات من القائمة ثلاثية النقاط لبطاقة الروبوت ← Help Center (حتى ~100 إدخال، إعادة ترتيب بالسحب، تخزين مؤقت على الخادم ~5 دقائق).

مساعد طيّار Telegram Premium

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

الإعداد عملية دمج منفصلة في لوحة الإدارة (“Telegram Premium co-pilot”). الثوابت الأساسية:

• روبوت واحد = Agent عميل واحد. يمكن لروبوت Telegram أن يشير إلى webhook واحد فقط في كل مرة — لا يمكنك مشاركة روبوت مع دمج Telegram العادي أو مع Saba on Telegram. أنشئ روبوت BotFather جديدًا لوضع Business.
• تبديل وضع Business في BotFather مطلوب. بدونه، يرى مستخدمو Premium “this bot doesn’t support Telegram Business yet” عند إضافته. فعّله ضمن Bot Settings ← Business Mode.
• N من مستخدمي Premium لكل عملية دمج. يربط كل واحد حسابه مرة واحدة عبر /start <code> في رسالة مباشرة عادية مع الروبوت.
• الرسائل المباشرة فقط. لا تغطّي اتصالات Business محادثات المجموعات.
• الاستلام اليدوي تلقائي. عندما يكتب مستخدم Premium ردًا بنفسه، يتوقّف الروبوت مؤقتًا في تلك المحادثة لفترة منزلقة كي لا يتحدّث فوق محادثة حية.
• مفتاح إيقاف على مستوى الاتصال. فعّل “Disable auto-reply” على بطاقة الدمج لإيقاف الروبوت مؤقتًا عبر كل مستخدمي Premium المرتبطين دون قطع الاتصال.

راجع Connect Premium bot ضمن قسم Telegram Premium co-pilot في صفحة Integrations بلوحة الإدارة للحصول على دليل الإعداد الكامل.

Saba on Telegram

يمكن للمشغّلين أيضًا التحدّث مع Saba (مساعد المنصّة) من روبوت Telegram مخصّص. نفس الصلاحيات ونفس الوصول إلى البيانات كما في لوحة الإدارة — مفيد عندما تكون بعيدًا عن حاسوبك المحمول وتحتاج إلى التحقّق من إحصائيات الـ Agent أو الفوترة أو النشاط الأخير.

سطحان فوق نفس القناة:

• روبوت الرسائل المباشرة (DM bot) — ردود نصية في رسالة Telegram مباشرة عادية، مع أزرار إجراء مدمجة تُحيل عميقًا إلى صفحة لوحة الإدارة الصحيحة (?from=saba_telegram للإسناد).
• Saba Mini App — سطح دردشة أغنى داخل Telegram على saba-mini.cuneiform.chat مع سجلّ المحادثات وتفاصيل استدعاء الأدوات والإدخال الصوتي عبر المتصفّح والتصدير بصيغة markdown. يأتي كل رد في الرسائل المباشرة مع زر مدمج “Open in Mini App” للتبديل بين الأسطح في منتصف المحادثة.

الإعداد من جانب الإدارة: اربط روبوت BotFather جديدًا ضمن “Saba on Telegram” في Integrations. بعد ذلك يربط كل عضو في المؤسّسة حسابه الشخصي برمز صالح لمدة 10 دقائق.

راجع Platform Assistant ← From Telegram لتجربة جانب المستخدم.

أوامر الروبوت

يمكنك ضبط أوامر مخصّصة عبر BotFather:

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

الروبوت لا يستجيب

1. تحقّق من صحة رمز الروبوت (token)
2. تأكّد من أن عملية الدمج مرتبطة في Cuneiform Chat
3. تأكّد من أن الـ Agent الخاص بك مُعدّ بشكل صحيح
4. اختبر الـ Agent في الـ Playground أولًا

مشكلات الرمز (Token)

إذا احتجت إلى رمز جديد:

1. انتقل إلى BotFather
2. أرسل /mybots ← اختر روبوتك ← API Token ← Revoke
3. حدّث الرمز الجديد في Cuneiform Chat

مشكلات محادثة المجموعة

• تأكّد من أن للروبوت صلاحيات المشرف
• تحقّق من إعدادات وضع الخصوصية عبر BotFather (/setprivacy)

الأمان

• تُشفَّر رموز الروبوت وتُخزَّن بأمان
• تُعالَج المحادثات عبر اتصالات آمنة

قطع الاتصال

لإزالة دمج Telegram:

1. انتقل إلى Integrations في الشريط الجانبي
2. افتح بطاقة Telegram وانقر على Disconnect

يوقف ذلك الروبوت عن الاستجابة لكنه لا يحذف روبوت Telegram نفسه. احذفه عبر BotFather إذا لزم الأمر.