قبل أن تبدأ
كل تكامل يتصل بـ تطبيق محادثة (Chatting App) - واحد لكل موقع أو تطبيق جوال. اطلب من مسؤول مساحة عمل Connectly إنشاء واحد (Desk ← Chatting App) وإرسال ما يلي إليك:
- المفتاح العام (
pk_…) - يعرّف تطبيقك. آمن لتضمينه في صفحة ويب أو تطبيق. - المفتاح السري - فقط إذا كنت تربط المحادثة بمستخدميك المسجّلين (انظر الزوار المعرّفون). احتفظ به على خادمك فقط، وليس في التطبيق أبداً.
- عنوان الخادم -
https://connectly.wowdigital.sa(يُستخدم للواجهة البرمجية والاتصال اللحظي معاً).
https://www.your-site.com). اطلب إضافة عناوين موقعك الفعلي وموقع الاختبار.التثبيت
أضف وسم script واحداً إلى صفحتك. لا حاجة لأدوات بناء أو مدير حزم.
<script src="https://connectly.wowdigital.sa/assets/connectly/chatting-sdk/connectly-chat.js"></script>socket.io-client تلقائياً. وإذا كانت صفحتك تتضمن socket.io-client الإصدار 4 فستُستخدم تلك النسخة.عرض المحادثة
ConnectlyChatWidget محادثة كاملة: الرسائل والصور والملفات والرسائل الصوتية ومؤشر الكتابة وخيار "التحدث مع موظف". أضف عنصراً حاوياً إلى صفحتك وضع المحادثة بداخله - وستملأ العنصر بالكامل.
<div id="support-chat" style="height: 600px"></div>
<script src="https://connectly.wowdigital.sa/assets/connectly/chatting-sdk/connectly-chat.js"></script>
<script>
const widget = ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat", // the wrapper element's id
title: "Support",
});
</script>container محدِّد CSS أو العنصر نفسه أيضاً.زر محادثة عائم
احذف container لتحصل بدلاً من ذلك على زر محادثة دائري في زاوية الصفحة. يفتح المحادثة فوقه (بملء الشاشة على الجوال) ويعرض عدد الردود غير المقروءة. ولا يتصل إلا عندما يفتحه الزائر أول مرة.
const widget = ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
position: "right", // or "left"
startOpen: false,
});
widget.open(); // open the chat from your own "Contact us" button
widget.close(); // minimise it - the conversation continues
widget.destroy(); // remove it and end the conversationapiBaseUrl وwsUrl تساويان افتراضياً الخادم الذي حُمّل منه السكربت (https://connectly.wowdigital.sa). حدّدهما فقط إذا كنت تستضيف connectly-chat.js بنفسك.التخصيص
طابق هوية علامتك عبر theme، وفعّل الميزات أو غيّر أي نص عبر options. مرّر فقط ما تريد تغييره. الأسماء نفسها المستخدمة في ConnectlyChatTheme وConnectlyChatOptions في حزمة Flutter؛ والأوقات بالملي ثانية.
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
theme: {
primaryColor: "#16A34A",
headerBackgroundColor: "#16A34A",
visitorBubbleColor: "#16A34A",
backgroundImage: "https://www.your-site.com/chat-bg.png",
bubbleBorderRadius: 16,
},
options: {
enableAttachments: true,
enableVoiceRecording: false,
enableTalkToHuman: true,
welcomeMessage: "Hi! How can we help you today?",
inputPlaceholder: "Type a message...",
},
});الخيارات
| الخيار | الافتراضي | الوصف |
|---|---|---|
enableAttachments | true | إرفاق الملفات والصور |
enableVoiceRecording | true | تسجيل رسائل صوتية (يظهر في صفحات HTTPS وفي المتصفحات التي تدعم التسجيل) |
enableTalkToHuman | true | إظهار "التحدث مع موظف" داخل المحادثة |
enableTypingIndicator | true | نقاط متحركة أثناء كتابة الطرف الآخر |
enableSounds | true | تنبيه صوتي خفيف عند وصول رسالة |
allowedFileExtensions | png, jpg, jpeg, gif, webp, pdf, doc, docx, txt | أنواع الملفات المسموحة |
maxFileSizeBytes | 10485760 (10 MB) | أكبر حجم للمرفق |
maxRecordingDuration | 120000 (2 min) | أطول رسالة صوتية، بالملي ثانية |
messageCharacterLimit | 2000 | أطول رسالة نصية (0 = بلا حد) |
typingThrottle | 2000 | معدل إرسال إشارة "يكتب" أثناء كتابة الزائر، بالملي ثانية |
resumeInterruptedChatWithin | 1800000 (30 min) | إذا أُعيد تحميل الصفحة أو أُغلقت أثناء فتح المحادثة، تُستكمل نفس المحادثة عند العودة خلال هذه المدة (0 = إيقاف) |
direction | "auto" | "ltr" أو "rtl" أو "auto" لاتباع <html dir> في الصفحة |
welcomeMessage, inputPlaceholder, …Label | نصوص إنجليزية | يمكن استبدال كل نص ظاهر - بترجماتك مثلاً (انظر أدناه) |
المظهر
| الخاصية | الافتراضي | الوصف |
|---|---|---|
primaryColor | #4F46E5 | زر الإرسال وزر المحادثة والعناصر المميزة |
backgroundColor | #F3F4F6 | خلفية منطقة الرسائل |
backgroundImage | null | صورة خلف الرسائل: رابط، أو { url, fit, opacity } حيث fit هي "cover" أو "contain" أو "repeat" |
visitorBubbleColor / visitorTextColor | #4F46E5 / #FFFFFF | رسائل الزائر نفسه |
otherBubbleColor / otherTextColor | #F1F1F4 / rgba(0,0,0,.87) | رسائل المساعد الذكي والموظفين |
bubbleBorderRadius | 16 | زوايا الفقاعات: بالبكسل، أو أي قيمة CSS مثل "16px 16px 4px 16px" |
headerBackgroundColor / headerTextColor | #4F46E5 / #FFFFFF | شريط العنوان |
messageTextStyle / timestampTextStyle | null | خصائص CSS، مثل { fontSize: "15px" } |
fontFamily | خطوط النظام | خط المحادثة بالكامل |
composerBackgroundColor / inputTextColor | #FFFFFF / #111827 | منطقة مربع الكتابة |
النصوص والعربية
كل نص تعرضه المحادثة هو خيار: title, welcomeMessage, inputPlaceholder, talkToHumanLabel, talkToHumanHint, connectingLabel, onlineLabel, waitingForAgentLabel, agentConnectedLabel, agentLeftLabel, connectionLostLabel, connectErrorLabel, retryLabel, rateLimitedLabel, notSentLabel, fileTooLargeLabel, fileTypeNotAllowedLabel, microphonePermissionLabel, recordingLabel, recordingTooShortLabel, loadMessagesFailedLabel, attachmentLabel. وتُستبدل {seconds} و{size} و{max} داخل النص بالقيمة الفعلية.
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
title: "تواصل معنا",
options: {
direction: "rtl",
welcomeMessage: "أهلاً بك! كيف نقدر نساعدك؟",
inputPlaceholder: "اكتب رسالتك...",
onlineLabel: "متصل",
connectingLabel: "جارٍ الاتصال...",
talkToHumanHint: "تحتاج موظفاً؟",
talkToHumanLabel: "التحدث مع موظف",
waitingForAgentLabel: "جارٍ تحويلك إلى موظف...",
agentConnectedLabel: "أنت الآن تتحدث مع موظف",
agentLeftLabel: "غادر الموظف المحادثة. المساعد الذكي عاد لمساعدتك.",
notSentLabel: "لم تُرسل. اضغط لإعادة المحاولة",
rateLimitedLabel: "أنت ترسل بسرعة كبيرة. حاول بعد {seconds} ثانية.",
retryLabel: "إعادة المحاولة",
},
});الاستدعاءات
تابع أحداث المحادثة دون بناء واجهتك الخاصة:
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
onChatStarted: (chatId) => localStorage.setItem("my_chat_id", chatId), // keep it to resume later
onMessageReceived: (m) => console.log(m.role, m.content),
onMessageSend: (m) => analytics.track("chat_send", { type: m.type }),
onMessageStatusChanged: (m) => console.log(m.id, m.status), // "sent" or "failed"
onClose: () => console.log("chat closed"),
});للرسائل نفس الحقول الموضحة في واجهة مخصصة: id وrole وtype وcontent وfile وtimestamp وstatus.
المحادثات
في كل مرة تُضاف فيها الواجهة تبدأ محادثة جديدة. وإذا أعاد الزائر تحميل الصفحة (أو غادرها ثم عاد) أثناء فتح المحادثة فإنها تُستكمل خلال مدة resumeInterruptedChatWithin. تصغير المحادثة العائمة لا ينهيها؛ أما destroy() فينهيها. لاستكمال محادثة بعينها، احفظ المعرّف من onChatStarted ومرّره مجدداً في chatId - وتُحمّل رسائلها السابقة تلقائياً.
// Open the conversation the visitor had before (null = start a new one):
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
chatId: localStorage.getItem("my_chat_id"),
onChatStarted: (chatId) => localStorage.setItem("my_chat_id", chatId),
});الزوار المعرّفون
يمكن ربط المستخدمين المسجّلين بحساباتهم، فيرى الموظفون من يحادثون وتتبع محادثات المستخدم بين أجهزته. خادمك هو من يوقّع رمزاً قصير الأجل بالمفتاح السري للتطبيق - وليس المتصفح أبداً.
// In the browser - get a short-lived token from YOUR backend, then pass it in:
const { identify_token } = await fetch("/api/chat-token").then((r) => r.json());
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
identifyToken: identify_token,
});| الحقل | إلزامي | الغرض |
|---|---|---|
user_id | نعم | معرّف المستخدم لديك |
exp | نعم | وقت الانتهاء (Unix) - اجعله قصيراً، مثل 5 دقائق |
name, email, phone | لا | تظهر للموظفين |
يُوقّع بخوارزمية HS256 باستخدام المفتاح السري لتطبيق المحادثة:
const jwt = require("jsonwebtoken");
app.get("/api/chat-token", requireLogin, (req, res) => {
const token = jwt.sign(
{ user_id: req.user.id, name: req.user.name, email: req.user.email },
process.env.CONNECTLY_SECRET_KEY,
{ algorithm: "HS256", expiresIn: "5m" }
);
res.json({ identify_token: token });
});import time, jwt # PyJWT
@app.get("/api/chat-token")
def chat_token(user=Depends(require_login)):
token = jwt.encode(
{"user_id": user.id, "name": user.name, "email": user.email,
"exp": int(time.time()) + 300},
CONNECTLY_SECRET_KEY,
algorithm="HS256",
)
return {"identify_token": token}السلوك المدمج
- رسائل فورية: تظهر الرسالة فوراً مع 🕓 ثم ✓ - أو "لم تُرسل، اضغط لإعادة المحاولة". لا تُسلّم إعادة المحاولة مرتين أبداً.
- الملفات والرسائل الصوتية: تظهر الصور داخل المحادثة، وتُفتح المستندات في تبويب جديد، وتُشغَّل الرسائل الصوتية - المسجّلة من المتصفح مباشرة - داخل المحادثة. وأثناء قراءة المساعد للمرفق تظهر نقاط الكتابة.
- إعادة اتصال صامتة: إذا انقطع الاتصال (سكون الجهاز، تبويب في الخلفية، تغيّر الشبكة) تعود المحادثة لنفس الجلسة وتُحمّل ما فات. ولا يظهر شريط إعادة المحاولة إلا إذا فشل ذلك.
- التحويل إلى موظف: يظهر "التحدث مع موظف" فوق مربع الكتابة، ثم سطر انتظار بعد الطلب، ويختفي أثناء وجود موظف في المحادثة.
- الحدود: حتى 15 رسالة في الدقيقة لكل زائر؛ بعدها تظهر "لم تُرسل" مع مدة الانتظار.
- تنسيقاتك تبقى كما هي: المحادثة معزولة (Shadow DOM) - لا تؤثر تنسيقات CSS في صفحتك عليها، ولا تؤثر هي على صفحتك.
- التذييل: تعرض المحادثة سطراً صغيراً "Powered by Connectly" أسفل مربع الكتابة.
مرجع الواجهة البرمجية
ConnectlyChatWidget.mount(config)
| الخيار | الوصف |
|---|---|
publicKey | إلزامي. المفتاح العام لتطبيق المحادثة |
container | معرّف العنصر الحاوي أو محدِّد CSS أو العنصر نفسه. احذفه لزر محادثة عائم |
title | عنوان الشريط العلوي (الافتراضي "Chat with us") |
theme | الألوان والمظهر - انظر التخصيص |
options | الميزات والحدود والنصوص - انظر التخصيص |
identifyToken | رمز من خادمك لمستخدم مسجّل |
chatId | استكمال هذه المحادثة |
position, startOpen | للزر العائم فقط: الزاوية "right" أو "left"؛ والفتح مباشرة |
onChatStarted, onMessageReceived, onMessageSend, onMessageStatusChanged, onClose | انظر الاستدعاءات |
apiBaseUrl, wsUrl | فقط إذا كنت تستضيف السكربت بنفسك - افتراضياً الخادم الذي حُمّل منه |
| الدالة | الوصف |
|---|---|
open() | يفتح المحادثة العائمة |
close() | يصغّر المحادثة العائمة (تستمر المحادثة) |
toggle() | يفتحها أو يغلقها |
destroy() | يزيل المحادثة وينهيها |
client | كائن ConnectlyChat الذي تعمل عليه - للاستماع إلى أحداثه |