مرجع SDK

كل حزمة تطوير برمجيات من Telybot — Android، وiOS، وReact Native، وFlutter، وIonic — تنفذ نفس العقد البسيط. إذا استخدمت واحدة منها، فقد استخدمتها جميعاً.

واجهة برمجة التطبيقات (API)

اتصال	ما الذي يفعله
`init` / `initialize`	يخزن Client ID الخاص بك. يقوم بالتحقق منه ويصدر تنبيهاً واضحاً إذا كان بتنسيق خاطئ.
`show`	يعرض المحادثة فوق تطبيقك. يقبل سؤالًا اختياريًا لصندوق الرسالة (0.2.0).
`dismiss`	يغلقها.
`isShowing`	ما إذا كان يتم عرضه الآن.
محادثة مضمّنة	المحادثة داخل إحدى شاشاتك، مثل علامة تبويب «المساعدة» (0.2.0).
`onShow` / `onDismiss`	يُبلَّغ عند فتح المحادثة وإغلاقها، على Android وiOS (0.2.0).
`setVisitor`	اسم عميلك المسجّل دخوله وهاتفه وبريده الإلكتروني، تُعرض في نماذج المحادثة (0.2.0).
`hasUnreadReply` / `onReply`	رد من فريقك لم يره العميل بعد (0.2.0).

الفتح بسؤال. مرّر سؤالًا إلى show فيوضع في صندوق رسالة المحادثة؛ يقرأه العميل ويضغط إرسال. ينتقل في #fragment الرابط، فلا يصل أبدًا إلى سجل الخادم. حتى 500 حرف، في سطر واحد.

المحادثة داخل شاشتك. KeydaBotView في Android، وKeydaBot.makeChatViewController في iOS أو KeydaBotView في SwiftUI، و<KeydaBotChat /> في React Native، وKeydaBotChat في Flutter، وembedWidget() في حزمة Ionic. لا يوجد زر إغلاق — التنقل في شاشتك هو المخرج. في Android، يغلق زر الرجوع أولًا أي عنصر أو سلة مفتوحة: يقوم React Native وFlutter بذلك عنك ما دامت المحادثة هي الشاشة في المقدمة، ومع KeydaBotView الأصلي تستدعي معالجة الرجوع لديك goBack() الخاص به.

عميلك المسجّل دخوله. أعطِ SDK اسم عميلك أو رقم هاتفه أو بريده الإلكتروني، فتملأ المحادثة ما يعرفه تطبيقك مسبقًا. تُعرض التفاصيل ولا تُرسل أبدًا: تظهر في نموذج «التحدث إلى شخص»، وفي طلب، وحجز، وسؤال ترحيبي يطلب اسمًا أو هاتفًا أو بريدًا إلكترونيًا، والعميل هو من يرسلها. تنتقل في #fragment الرابط، وهي قول تطبيقك لا هوية موثّقة. أي قيمة كانت المحادثة سترفضها تُستبعد: اسم أطول من 80 حرفًا، أو رقم هاتف لا يحوي 8 إلى 15 رقمًا، أو عنوان بريد إلكتروني بلا نطاق صحيح. تُفتح محادثة Ionic بملء الشاشة في متصفح النظام الذي يحتفظ بالعناوين في سجله، لذلك لا تقبلها؛ أما أداتها المضمّنة فتقبلها.

رد أثناء إغلاق المحادثة. عندما يطلب العميل التحدث إلى شخص ثم يغلق المحادثة، ينتظر ردك من لوحة التحكم داخل المحادثة. تتحقق مجموعات SDK لـ Android وiOS وReact Native وFlutter من ذلك عندما يعود تطبيقك إلى المقدمة وتُبلغ تطبيقك، فتستطيع إظهار نقطة على زر المحادثة حتى يفتحها العميل. وهي تسأل فقط عن المحادثات التي طلب فيها العميل شخصًا خلال آخر 14 يومًا. المحادثة التي يبقيها تطبيقك محمّلة بعيدًا عن الأنظار، مثل علامة تبويب «المساعدة» في الخلفية، لا تُحسب مقروءة: تبقى النقطة حتى ينظر العميل. هذا ليس إشعارًا فوريًا: يُلاحَظ الرد عند فتح التطبيق.

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

الرابط (URL) الذي يفتحه كل SDK

{baseUrl}/chat/{clientId}

baseUrl يتم تعيينه افتراضياً إلى https://telybot.com ويمكن تجاوزه على أي منصة، سواء للبيئة التجريبية أو للتثبيت الذاتي.

لماذا تحتاج إلى عرض ويب، وما هي تكلفته عليك

هناك واجهة دردشة واحدة، يتم تقديمها بواسطة المنصة، وتقوم جميع الواجهات بتحميلها.

ما تحصل عليه: أي تغيير يجريه المالك في لوحة التحكم — لون التمييز، رسالة الترحيب، اسم الـ bot، تفعيل الخدمة — يصل إلى كل تطبيق على الفور، دون الحاجة لإصدار جديد. أي إصلاح يطبق في كل مكان في وقت واحد. الدردشة متطابقة عبر جميع المنصات.

التكلفة: تحتاج المحادثة إلى اتصال. لا يوجد وضع غير متصل بالإنترنت، ولا توجد إشعارات دفع حتى الآن.

نفضل أن تعرف هذا قبل الإطلاق بدلاً من اكتشافه لاحقاً.

الضمانات التي تقدمها كل حزمة تطوير برمجيات (SDK)

خروج التنقل. أي رابط لمصدر خارجي يفتح في متصفح النظام بدلاً من استبدال نافذة الدردشة. بدون هذا، نقرة واحدة على رابط في التذييل ستنهي محادثة العميل دون وسيلة للعودة.
استمرارية المحادثة. تم تفعيل تخزين DOM، لذا يجد العميل الذي يغلق التطبيق ويعود إليه محادثته في المكان الذي توقف عنده (لمدة 24 ساعة).
لوحة المفاتيح لا تغطي حقل الإدخال أبداً.
يتم احترام المناطق الآمنة — لا يتم رسم الدردشة تحت نتوء الشاشة أو مؤشر الصفحة الرئيسية.
لا يصل أي عطل إلى تطبيقك. فشل التحميل يظهر خيار إعادة المحاولة.
لا توجد تحليلات، ولا معرفات أجهزة، ولا تبعيات من أطراف خارجية. إضافة Telybot SDK لا تضيف أي متتبع إلى تطبيقك.
زر الرجوع يغلق أولًا ما ينظر إليه العميل. في Android، الرجوع فوق عنصر أو سلة أو حجز مفتوح يغلقه، ثم يغلق المحادثة بعد ذلك فقط (SDK 0.2.0 وما بعده).

داخل المحادثة

كل هذا يأتي من الصفحة المستضافة، فيصل إلى كل تطبيق دون تحديث SDK:

رسالة ترحيب مع أزرار اقتراحات، باللغة المحددة للبوت.
تُحفظ المحادثة على الجهاز لمدة 24 ساعة، ولا تنشئ المحادثة معرّف زائر. على موقع ويب، تدوم المحادثة لعلامة تبويب واحدة في المتصفح. (تحتاج محادثة Ionic SDK بملء الشاشة إلى 0.2.0 لهذا.)
الطلبات والحجوزات، عندما يقبلها النشاط التجاري: سلة، وتواريخ وأوقات الحجز، ورابط للاتصال بالنشاط التجاري عندما يطول انتظار طلب أو حجز، و«أضف إلى التقويم» للحجز المؤكد.
المرفقات: الصور (JPEG وPNG وWebP وGIF) وملفات PDF وDOCX وTXT وCSV وMD. تحتاج مجموعتا SDK لـ Android وFlutter إلى الإصدار 0.1.4 أو أحدث لزر الإرفاق، ويحتاج Flutter إلى 0.2.0 للمستندات.
«أضف إلى التقويم» رابط إلى ملف .ics. يفتحه iOS في التقويم كتقويم يمكن الاشتراك فيه. يقترح Android تطبيق التقويم في الهاتف إن كان يستورد ملفات .ics — وتقويم Google الحالي يفعل — وإلا فإن المتصفح ينزّل الملف.

تنسيق Client id

kb_live_ followed by 8-48 hexadecimal characters

أي شيء آخر يتم رفضه عند البدء بدلاً من فتح صفحة 404 أمام العميل. معرف العميل (Client ID) عام بطبيعته — فهو مرئي في أي موقع ويب يدمج الأداة — ولا يحمل أي قدرة على قراءة أو تغيير حسابك. انظر الحدود والأمان.

المصدر

عام، مرخص بموجب MIT: github.com/telybotai/telybot-Sdks. العقد المشترك الذي تلتزم به كل حزمة موجود في CONTRACT.md في أعلى ذلك المستودع.