Connectly AI
كيف يعمل المميزات المعمارية التكاملات لماذا نحن الأسعار الأسئلة الشائعة المطورون
تسجيل دخول تسجيل
المطورون

ابنِ مع Connectly

أضف محادثة عملاء يقودها الذكاء الاصطناعي - مع التحويل إلى موظفيك - إلى موقعك أو تطبيقك.

في هذه الصفحة
قبل أن تبدأالتثبيتعرض المحادثةالتخصيصالاستدعاءاتالمحادثاتالزوار المعرّفونالسلوك المدمجمرجع الواجهة البرمجية
01

قبل أن تبدأ

كل تكامل يتصل بـ تطبيق محادثة (Chatting App) - واحد لكل موقع أو تطبيق جوال. اطلب من مسؤول مساحة عمل Connectly إنشاء واحد (Desk ← Chatting App) وإرسال ما يلي إليك:

  • المفتاح العام (pk_…) - يعرّف تطبيقك. آمن لتضمينه في صفحة ويب أو تطبيق.
  • المفتاح السري - فقط إذا كنت تربط المحادثة بمستخدميك المسجّلين (انظر الزوار المعرّفون). احتفظ به على خادمك فقط، وليس في التطبيق أبداً.
  • عنوان الخادم - https://connectly.wowdigital.sa (يُستخدم للواجهة البرمجية والاتصال اللحظي معاً).
تطبيقات الويب: لا يقبل تطبيق المحادثة الزوار إلا من المواقع المدرجة في Allowed Origins (مثل https://www.your-site.com). اطلب إضافة عناوين موقعك الفعلي وموقع الاختبار.
هذا التبويب خاص بـالمحادثة الجاهزة - واجهة محادثة كاملة تضعها في صفحتك وتخصّص مظهرها وخياراتها. معظم المواقع تحتاج هذه فقط. تريد رسم المحادثة بنفسك؟ انظر تبويب واجهة مخصصة.
02

التثبيت

أضف وسم script واحداً إلى صفحتك. لا حاجة لأدوات بناء أو مدير حزم.

html
<script src="https://connectly.wowdigital.sa/assets/connectly/chatting-sdk/connectly-chat.js"></script>
تحمّل المكتبة socket.io-client تلقائياً. وإذا كانت صفحتك تتضمن socket.io-client الإصدار 4 فستُستخدم تلك النسخة.
03

عرض المحادثة

ConnectlyChatWidget محادثة كاملة: الرسائل والصور والملفات والرسائل الصوتية ومؤشر الكتابة وخيار "التحدث مع موظف". أضف عنصراً حاوياً إلى صفحتك وضع المحادثة بداخله - وستملأ العنصر بالكامل.

html
<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>
حدّد ارتفاعاً للعنصر الحاوي - تأخذ المحادثة حجمه (وإن لم يكن له ارتفاع يكون ارتفاع المحادثة 600px). يمكن أن تكون قيمة container محدِّد CSS أو العنصر نفسه أيضاً.

زر محادثة عائم

احذف container لتحصل بدلاً من ذلك على زر محادثة دائري في زاوية الصفحة. يفتح المحادثة فوقه (بملء الشاشة على الجوال) ويعرض عدد الردود غير المقروءة. ولا يتصل إلا عندما يفتحه الزائر أول مرة.

javascript
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 conversation
القيمتان apiBaseUrl وwsUrl تساويان افتراضياً الخادم الذي حُمّل منه السكربت (https://connectly.wowdigital.sa). حدّدهما فقط إذا كنت تستضيف connectly-chat.js بنفسك.
04

التخصيص

طابق هوية علامتك عبر theme، وفعّل الميزات أو غيّر أي نص عبر options. مرّر فقط ما تريد تغييره. الأسماء نفسها المستخدمة في ConnectlyChatTheme وConnectlyChatOptions في حزمة Flutter؛ والأوقات بالملي ثانية.

javascript
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...",
  },
});

الخيارات

الخيارالافتراضيالوصف
enableAttachmentstrueإرفاق الملفات والصور
enableVoiceRecordingtrueتسجيل رسائل صوتية (يظهر في صفحات HTTPS وفي المتصفحات التي تدعم التسجيل)
enableTalkToHumantrueإظهار "التحدث مع موظف" داخل المحادثة
enableTypingIndicatortrueنقاط متحركة أثناء كتابة الطرف الآخر
enableSoundstrueتنبيه صوتي خفيف عند وصول رسالة
allowedFileExtensionspng, jpg, jpeg, gif, webp, pdf, doc, docx, txtأنواع الملفات المسموحة
maxFileSizeBytes10485760 (10 MB)أكبر حجم للمرفق
maxRecordingDuration120000 (2 min)أطول رسالة صوتية، بالملي ثانية
messageCharacterLimit2000أطول رسالة نصية (0 = بلا حد)
typingThrottle2000معدل إرسال إشارة "يكتب" أثناء كتابة الزائر، بالملي ثانية
resumeInterruptedChatWithin1800000 (30 min)إذا أُعيد تحميل الصفحة أو أُغلقت أثناء فتح المحادثة، تُستكمل نفس المحادثة عند العودة خلال هذه المدة (0 = إيقاف)
direction"auto""ltr" أو "rtl" أو "auto" لاتباع <html dir> في الصفحة
welcomeMessage, inputPlaceholder, …Labelنصوص إنجليزيةيمكن استبدال كل نص ظاهر - بترجماتك مثلاً (انظر أدناه)

المظهر

الخاصيةالافتراضيالوصف
primaryColor#4F46E5زر الإرسال وزر المحادثة والعناصر المميزة
backgroundColor#F3F4F6خلفية منطقة الرسائل
backgroundImagenullصورة خلف الرسائل: رابط، أو { url, fit, opacity } حيث fit هي "cover" أو "contain" أو "repeat"
visitorBubbleColor / visitorTextColor#4F46E5 / #FFFFFFرسائل الزائر نفسه
otherBubbleColor / otherTextColor#F1F1F4 / rgba(0,0,0,.87)رسائل المساعد الذكي والموظفين
bubbleBorderRadius16زوايا الفقاعات: بالبكسل، أو أي قيمة CSS مثل "16px 16px 4px 16px"
headerBackgroundColor / headerTextColor#4F46E5 / #FFFFFFشريط العنوان
messageTextStyle / timestampTextStylenullخصائص 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} داخل النص بالقيمة الفعلية.

javascript
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: "إعادة المحاولة",
  },
});
05

الاستدعاءات

تابع أحداث المحادثة دون بناء واجهتك الخاصة:

javascript
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.

06

المحادثات

في كل مرة تُضاف فيها الواجهة تبدأ محادثة جديدة. وإذا أعاد الزائر تحميل الصفحة (أو غادرها ثم عاد) أثناء فتح المحادثة فإنها تُستكمل خلال مدة resumeInterruptedChatWithin. تصغير المحادثة العائمة لا ينهيها؛ أما destroy() فينهيها. لاستكمال محادثة بعينها، احفظ المعرّف من onChatStarted ومرّره مجدداً في chatId - وتُحمّل رسائلها السابقة تلقائياً.

javascript
// 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),
});
07

الزوار المعرّفون

يمكن ربط المستخدمين المسجّلين بحساباتهم، فيرى الموظفون من يحادثون وتتبع محادثات المستخدم بين أجهزته. خادمك هو من يوقّع رمزاً قصير الأجل بالمفتاح السري للتطبيق - وليس المتصفح أبداً.

javascript
// 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 باستخدام المفتاح السري لتطبيق المحادثة:

node.js
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 });
});
python
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}
08

السلوك المدمج

  • رسائل فورية: تظهر الرسالة فوراً مع 🕓 ثم ✓ - أو "لم تُرسل، اضغط لإعادة المحاولة". لا تُسلّم إعادة المحاولة مرتين أبداً.
  • الملفات والرسائل الصوتية: تظهر الصور داخل المحادثة، وتُفتح المستندات في تبويب جديد، وتُشغَّل الرسائل الصوتية - المسجّلة من المتصفح مباشرة - داخل المحادثة. وأثناء قراءة المساعد للمرفق تظهر نقاط الكتابة.
  • إعادة اتصال صامتة: إذا انقطع الاتصال (سكون الجهاز، تبويب في الخلفية، تغيّر الشبكة) تعود المحادثة لنفس الجلسة وتُحمّل ما فات. ولا يظهر شريط إعادة المحاولة إلا إذا فشل ذلك.
  • التحويل إلى موظف: يظهر "التحدث مع موظف" فوق مربع الكتابة، ثم سطر انتظار بعد الطلب، ويختفي أثناء وجود موظف في المحادثة.
  • الحدود: حتى 15 رسالة في الدقيقة لكل زائر؛ بعدها تظهر "لم تُرسل" مع مدة الانتظار.
  • تنسيقاتك تبقى كما هي: المحادثة معزولة (Shadow DOM) - لا تؤثر تنسيقات CSS في صفحتك عليها، ولا تؤثر هي على صفحتك.
  • التذييل: تعرض المحادثة سطراً صغيراً "Powered by Connectly" أسفل مربع الكتابة.
09

مرجع الواجهة البرمجية

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 الذي تعمل عليه - للاستماع إلى أحداثه
في هذه الصفحة
قبل أن تبدأالتثبيتالبدء السريععرض الرسائلالإرسال وحالة التسليمالملفات والرسائل الصوتيةالتحدث مع موظفالاتصال وإعادة الاتصالالمحادثاتالزوار المعرّفونمرجع الواجهة البرمجية
01

قبل أن تبدأ

كل تكامل يتصل بـ تطبيق محادثة (Chatting App) - واحد لكل موقع أو تطبيق جوال. اطلب من مسؤول مساحة عمل Connectly إنشاء واحد (Desk ← Chatting App) وإرسال ما يلي إليك:

  • المفتاح العام (pk_…) - يعرّف تطبيقك. آمن لتضمينه في صفحة ويب أو تطبيق.
  • المفتاح السري - فقط إذا كنت تربط المحادثة بمستخدميك المسجّلين (انظر الزوار المعرّفون). احتفظ به على خادمك فقط، وليس في التطبيق أبداً.
  • عنوان الخادم - https://connectly.wowdigital.sa (يُستخدم للواجهة البرمجية والاتصال اللحظي معاً).
تطبيقات الويب: لا يقبل تطبيق المحادثة الزوار إلا من المواقع المدرجة في Allowed Origins (مثل https://www.your-site.com). اطلب إضافة عناوين موقعك الفعلي وموقع الاختبار.
هذا التبويب خاص بـواجهتك الخاصة: ConnectlyChat هو المحرك بدون واجهة - نفس المحرك الذي تعمل عليه المحادثة الجاهزة. تريد محادثة جاهزة في صفحتك فقط؟ انظر تبويب محادثة جاهزة.
02

التثبيت

أضف وسم script واحداً إلى صفحتك. لا حاجة لأدوات بناء أو مدير حزم.

html
<script src="https://connectly.wowdigital.sa/assets/connectly/chatting-sdk/connectly-chat.js"></script>
تحمّل المكتبة socket.io-client تلقائياً. وإذا كانت صفحتك تتضمن socket.io-client الإصدار 4 فستُستخدم تلك النسخة.
03

البدء السريع

يتولى ConnectlyChat الاتصال والمحادثة وإعادة الاتصال، وأنت تعرض الرسائل بواجهتك الخاصة، لذا يناسب أي تصميم.

javascript
const chat = new ConnectlyChat({
  publicKey: "pk_xxx",
  apiBaseUrl: "https://connectly.wowdigital.sa",
  wsUrl: "https://connectly.wowdigital.sa",
});

// The whole conversation - on first load, after a page reload and after every reconnect.
chat.on("history", (messages) => {
  clearMessages();
  messages.forEach(renderMessage);
});

// New messages from the AI assistant or a human agent.
chat.on("message", (message) => renderMessage(message));

chat.on("typing", () => showTypingIndicator());

await chat.connect();
04

عرض الرسائل

تحتوي كل رسالة على id وrole وtype (text أو image أو audio أو document) وcontent وfile وtimestamp، وعلى status لرسائل الزائر نفسه. رسائل السجل والرسائل اللحظية لها نفس الشكل.

javascript
function renderMessage(m) {
  // Only "is it the visitor?" decides the side. Other roles are free-form:
  // "assistant" for the AI, an agent's user name for a human agent.
  const mine = m.role === "user";
  addBubble({
    side: mine ? "right" : "left",
    type: m.type,                 // "text" | "image" | "audio" | "document"
    text: m.content,              // the caption for files (may be empty)
    file: m.file,                 // absolute URL for images, voice notes, documents
    time: new Date(m.timestamp),  // when it was sent
    status: m.status,             // "sent" on the visitor's stored messages
  });
}
حدّد شكل الفقاعة بالشرط role === "user" فقط. رسائل الموظفين تحمل اسم المستخدم كـ role (مثل Administrator)، فلا تستخدم قيمة role نفسها كاسم class.
05

الإرسال وحالة التسليم

اعرض رسالة الزائر فوراً ثم أكّدها. تكتمل sendMessage() عندما يستلم الخادم الرسالة، وتنتظر خلال انقطاع قصير بدلاً من أن تفشل.

javascript
async function send(text) {
  const clientId = crypto.randomUUID();     // keep it to resend the same message
  const bubble = addBubble({ side: "right", text, status: "sending" }); // show it right away

  try {
    await chat.sendMessage(text, { clientId });
    bubble.setStatus("sent");              // ✓ - the server has it
  } catch (err) {
    bubble.setStatus("failed");            // show "Not sent" + a Resend button
    if (err.code === "rate_limited") {
      showNotice(`You're sending messages too fast. Try again in ${err.retryAfter}s.`);
    }
  }
}
// Resend = call sendMessage again with the SAME clientId - never delivered twice.
يمكن لكل زائر إرسال 15 رسالة في الدقيقة كحد أقصى. بعدها ترفض sendMessage() بالخطأ err.code === "rate_limited" مع err.retryAfter (بالثواني)؛ لم تُعالج الرسالة ويمكن إعادة إرسالها.
06

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

ترفع sendAttachment() ملفاً من نوع File أو Blob - صورة أو مستنداً أو رسالة صوتية مسجّلة عبر MediaRecorder. يحدد الخادم نوع الرسالة (صورة أو صوت أو مستند) من نوع الملف. تكتمل عند حفظ الملف، ويصل رد المساعد كحدث message.

javascript
fileInput.onchange = async () => {
  const file = fileInput.files[0];
  const clientId = crypto.randomUUID();     // same idea as sendMessage - retries are safe
  const bubble = addBubble({ side: "right", file: URL.createObjectURL(file), status: "sending" });

  try {
    const { file: url, type } = await chat.sendAttachment(file, { clientId, caption: "" });
    bubble.setStatus("sent");               // url: the stored file; type: image | audio | document
  } catch (err) {
    bubble.setStatus("failed");             // same rate limit as sendMessage (err.code, err.retryAfter)
  }
};

// A voice note: pass the recorded Blob with a file name.
await chat.sendAttachment(blob, { fileName: "voice.webm" });
07

التحدث مع موظف

تبدأ المحادثات مع المساعد الذكي. يمكن للزائر طلب موظف في أي وقت؛ فيتوقف المساعد عن الرد وتظهر المحادثة في صندوق المحادثات المباشرة لدى موظفيك. أخفِ الزر ما دامت chat.isLive صحيحة - فالمحادثة لدى موظف بالفعل.

javascript
chat.on("ready", ({ is_live, handoff_status }) => updateHandoffUI());
chat.on("handoff_requested", () => showWaiting("Connecting you with a human agent..."));
chat.on("handoff_accepted",  () => showNotice("A human agent has joined the chat."));
chat.on("handoff_resolved",  () => showNotice("The agent has left. Our assistant is back."));
chat.on("live_changed", ({ is_live }) => updateHandoffUI());

function updateHandoffUI() {
  // Offer the button only while the AI is answering.
  talkToHumanButton.hidden = chat.isLive;
}

talkToHumanButton.onclick = () => chat.requestHuman("Customer asked for an agent");
08

الاتصال وإعادة الاتصال

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

javascript
chat.on("connection", ({ state }) => {
  // "connecting" | "connected" | "reconnecting" | "failed"
  retryBar.hidden = state !== "failed";    // only shown after automatic retries gave up
});

retryButton.onclick = () => chat.retry();
09

المحادثات

مع ConnectlyChat يكمل الزائر العائد محادثته السابقة افتراضياً (يُحفظ الزائر في localStorage).

javascript
// Default: the visitor returns to their previous conversation.
new ConnectlyChat({ publicKey, apiBaseUrl, wsUrl });

// Always start a fresh conversation:
new ConnectlyChat({ publicKey, apiBaseUrl, wsUrl, newChat: true });

// Resume a specific conversation (an id you saved from the "ready" event):
chat.on("ready", ({ chat_id }) => localStorage.setItem("my_chat_id", chat_id));
await chat.connect({ chatId: localStorage.getItem("my_chat_id") });
10

الزوار المعرّفون

يمكن ربط المستخدمين المسجّلين بحساباتهم، فيرى الموظفون من يحادثون وتتبع محادثات المستخدم بين أجهزته. خادمك هو من يوقّع رمزاً قصير الأجل بالمفتاح السري للتطبيق - وليس المتصفح أبداً.

javascript
// 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());

await chat.connect({ identifyToken: identify_token });
الحقلإلزاميالغرض
user_idنعممعرّف المستخدم لديك
expنعموقت الانتهاء (Unix) - اجعله قصيراً، مثل 5 دقائق
name, email, phoneلاتظهر للموظفين

يُوقّع بخوارزمية HS256 باستخدام المفتاح السري لتطبيق المحادثة:

node.js
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 });
});
python
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}
11

مرجع الواجهة البرمجية

new ConnectlyChat(options)

الخيارالوصف
publicKeyإلزامي. المفتاح العام لتطبيق المحادثة
apiBaseUrlإلزامي. عنوان الخادم
wsUrlإلزامي. عنوان الاتصال اللحظي - عادةً نفس apiBaseUrl
newChatبدء محادثة جديدة بدلاً من استكمال الأخيرة (الافتراضي false)
chatIdاستكمال هذه المحادثة
الدالةالوصف
connect(options?)يفتح المحادثة. الخيارات: identifyToken وchatId وnewChat
sendMessage(text, { clientId })يرسل نصاً؛ يكتمل عند استلام الخادم له
sendAttachment(file, { clientId, caption, fileName })يرفع ملفاً أو رسالة صوتية؛ يكتمل بـ { id, file, type }
sendTyping()يُعلم الطرف الآخر أن الزائر يكتب (مرة كل ثانيتين تقريباً)
requestHuman(reason?)يطلب موظفاً
getHistory({ page, pageSize })المحادثة حتى الآن، من الأقدم
on(event, fn) / off(event, fn)الاستماع إلى حدث / إيقاف الاستماع
retry()إعادة الاتصال بعد حالة "failed"
ensureConnected()يتحقق من الاتصال الآن ويعيده إن كان منقطعاً (يحدث تلقائياً عند عودة التبويب)
disconnect()يغلق الاتصال
الحدثالبياناتمتى
ready{ chat_id, is_live, handoff_status }عند الاتصال بالمحادثة (وبعد كل إعادة اتصال)
history[message]المحادثة كاملة - اعرضها
message{ role, type, content, file, timestamp }رسالة جديدة من المساعد أو موظف
typing-الطرف الآخر يكتب
handoff_requested, handoff_accepted, handoff_resolved{ handoff }مراحل التحويل إلى موظف
live_changed{ is_live }تولّى موظف المحادثة / أعادها
connection{ state }connecting أو connected أو reconnecting أو failed
error{ stage, message }للتسجيل - الأعطال التي تهم المستخدم تظهر كحالة failed
في هذه الصفحة
قبل أن تبدأالتثبيتإعداد المنصاتالإعدادعرض المحادثةالتخصيصالاستدعاءاتالمحادثاتالزوار المعرّفونالسلوك المدمجواجهة مخصصة (العميل)
01

قبل أن تبدأ

كل تكامل يتصل بـ تطبيق محادثة (Chatting App) - واحد لكل موقع أو تطبيق جوال. اطلب من مسؤول مساحة عمل Connectly إنشاء واحد (Desk ← Chatting App) وإرسال ما يلي إليك:

  • المفتاح العام (pk_…) - يعرّف تطبيقك. آمن لتضمينه في صفحة ويب أو تطبيق.
  • المفتاح السري - فقط إذا كنت تربط المحادثة بمستخدميك المسجّلين (انظر الزوار المعرّفون). احتفظ به على خادمك فقط، وليس في التطبيق أبداً.
  • عنوان الخادم - https://connectly.wowdigital.sa (يُستخدم للواجهة البرمجية والاتصال اللحظي معاً).
تطبيقات الويب: لا يقبل تطبيق المحادثة الزوار إلا من المواقع المدرجة في Allowed Origins (مثل https://www.your-site.com). اطلب إضافة عناوين موقعك الفعلي وموقع الاختبار.
02

التثبيت

قريباً على pub.dev باسم connectly_chat. الشيفرة المصدرية: github.com/WOW-DIT/connectly_chat_flutter
shell
flutter pub add connectly_chat

أو أضفها إلى pubspec.yaml:

yaml
dependencies:
  connectly_chat: ^1.0.0

إلى أن تُنشر على pub.dev، ثبّتها مباشرة من GitHub (يتطلب صلاحية الوصول إلى المستودع):

yaml · github
dependencies:
  connectly_chat:
    git:
      url: https://github.com/WOW-DIT/connectly_chat_flutter.git
03

إعداد المنصات

لا تستطيع حزم Flutter تعديل ملف manifest لتطبيقك، لذا أضف ما يلي بنفسك:

xml · android
<!-- android/app/src/main/AndroidManifest.xml, inside <manifest> -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- only if voice messages are enabled -->
<uses-permission android:name="android.permission.RECORD_AUDIO"/>

<!-- lets the chat open documents (Android 11+), inside <queries> -->
<queries>
  <intent>
    <action android:name="android.intent.action.VIEW"/>
    <data android:scheme="https"/>
  </intent>
</queries>
xml · ios
<!-- ios/Runner/Info.plist - only if voice messages are enabled -->
<key>NSMicrophoneUsageDescription</key>
<string>Used to record voice messages in chat.</string>
04

الإعداد

اضبط الإعدادات مرة واحدة قبل runApp(). بيانات الاتصال جزء من بناء التطبيق - وليست شاشة إعدادات أبداً.

dart
import 'package:connectly_chat/connectly_chat.dart';
import 'package:flutter/material.dart';

void main() {
  ConnectlyChat.configure(const ConnectlyChatConfig(
    publicKey: 'pk_xxx',
    apiBaseUrl: 'https://connectly.wowdigital.sa',
    wsUrl: 'https://connectly.wowdigital.sa',
  ));
  runApp(const MyApp());
}

أو أبقها خارج الشيفرة ومرّرها عند البناء:

dart · shell
// main.dart
ConnectlyChat.configure(ConnectlyChatConfig.fromEnvironment());

// build / run with:
flutter run \
  --dart-define=CONNECTLY_PUBLIC_KEY=pk_xxx \
  --dart-define=CONNECTLY_API_BASE_URL=https://connectly.wowdigital.sa \
  --dart-define=CONNECTLY_WS_URL=https://connectly.wowdigital.sa
تشغّل من بيئة التطوير؟ أضف الأعلام الثلاثة --dart-define إلى إعدادات التشغيل - بدونها يتوقف التطبيق عند البدء برسالة توضح القيمة الناقصة.
05

عرض المحادثة

ConnectlyChatWidget شاشة محادثة كاملة: الرسائل والصور والملفات والرسائل الصوتية ومؤشر الكتابة وخيار "التحدث مع موظف". افتحها كصفحة أو ضمّنها في أي مكان.

dart
Navigator.push(context, MaterialPageRoute(
  builder: (_) => Scaffold(
    body: SafeArea(
      child: ConnectlyChatWidget(
        title: 'Support',
        onClose: () => Navigator.pop(context),
      ),
    ),
  ),
));
06

التخصيص

طابق هوية علامتك عبر ConnectlyChatTheme، وفعّل الميزات أو غيّر أي نص عبر ConnectlyChatOptions.

dart
ConnectlyChatWidget(
  theme: const ConnectlyChatTheme(
    primaryColor: Color(0xFF16A34A),
    headerBackgroundColor: Color(0xFF16A34A),
    visitorBubbleColor: Color(0xFF16A34A),
  ),
  options: const ConnectlyChatOptions(
    enableAttachments: true,
    enableVoiceRecording: false,
    enableTalkToHuman: true,
    welcomeMessage: 'Hi! How can we help you today?',
    inputPlaceholder: 'Type a message...',
  ),
)

الخيارات

الخيارالافتراضيالوصف
enableAttachmentstrueإرفاق الملفات والصور
enableVoiceRecordingtrueتسجيل رسائل صوتية
enableTalkToHumantrueإظهار "التحدث مع موظف" داخل المحادثة
enableTypingIndicatortrueنقاط متحركة أثناء كتابة الطرف الآخر
allowedFileExtensionspng, jpg, jpeg, gif, webp, pdf, doc, docx, txtأنواع الملفات المسموحة
maxFileSizeBytes10 MBأكبر حجم للمرفق
maxRecordingDuration2 minأطول رسالة صوتية
messageCharacterLimit2000أطول رسالة نصية (0 = بلا حد)
resumeInterruptedChatWithin30 minإذا أغلق النظام التطبيق أثناء فتح المحادثة، تُستكمل نفس المحادثة عند فتحها خلال هذه المدة
welcomeMessage`, `inputPlaceholder`, `…Labelنصوص إنجليزيةيمكن استبدال كل نص ظاهر - بترجماتك مثلاً

المظهر

primaryColor وbackgroundColor وbackgroundImage وvisitorBubbleColor وotherBubbleColor وvisitorTextColor وotherTextColor وbubbleBorderRadius وheaderBackgroundColor وheaderTextColor وmessageTextStyle وtimestampTextStyle.

07

الاستدعاءات

تابع أحداث المحادثة دون بناء واجهتك الخاصة:

dart
ConnectlyChatWidget(
  onChatStarted: (chatId) => saveChatId(chatId),          // keep it to resume later
  onMessageReceived: (m) => debugPrint('${m.role}: ${m.content}'),
  onMessageSend: (m) => analytics.log('chat_send', m.type.name),
  onMessageStatusChanged: (m) => debugPrint('${m.id} -> ${m.status}'), // sent / failed
)
08

المحادثات

في كل مرة تُفتح شاشة المحادثة تبدأ محادثة جديدة. لاستكمال محادثة، احفظ المعرّف من onChatStarted ومرّره مجدداً في chatId - وتُحمّل رسائلها السابقة تلقائياً.

dart
// Open the conversation the user had before (null = start a new one):
ConnectlyChatWidget(
  chatId: await loadSavedChatId(),
  onChatStarted: saveChatId,
)
09

الزوار المعرّفون

مرّر رمزاً يصدره خادمك (نفس الرمز والأمثلة في تبويب الويب). اطلب رمزاً جديداً في كل مرة تُفتح المحادثة.

dart
final token = await myApi.getChatToken(); // minted by YOUR backend (see the Web tab for examples)
ConnectlyChatWidget(identifyToken: token)
10

السلوك المدمج

  • رسائل فورية: تظهر الرسالة فوراً مع 🕓 ثم ✓ - أو "لم تُرسل، اضغط لإعادة المحاولة". لا تُسلّم إعادة المحاولة مرتين أبداً.
  • إعادة اتصال صامتة: إذا قطع النظام الاتصال (إطفاء الشاشة، منتقي الملفات، الكاميرا، التنقل بين التطبيقات) تعود المحادثة لنفس الجلسة عند عودة التطبيق وتُحمّل ما فات. ولا يظهر زر إعادة المحاولة إلا إذا فشل ذلك.
  • التحويل إلى موظف: يظهر "التحدث مع موظف" فوق مربع الكتابة، ثم سطر انتظار بعد الطلب، ويختفي أثناء وجود موظف في المحادثة.
  • الحدود: حتى 15 رسالة في الدقيقة لكل زائر؛ بعدها تظهر "لم تُرسل" مع مدة الانتظار.
11

واجهة مخصصة (العميل)

تبني شاشة محادثة خاصة؟ استخدم ConnectlyChatClient مباشرة - نفس المحرك الذي تعمل عليه الواجهة.

dart
final client = ConnectlyChatClient(ConnectlyChat.config);

client.messages.listen((m) => setState(() => messages.add(m)));
client.connectionChanges.listen((state) => setState(() => connection = state));

await client.connect();                       // or connect(chatId: saved)
final past = await client.fetchHistory();     // the conversation so far
await client.sendMessage('Hi', clientId: id); // throws ConnectlyRateLimitException past 15/min
await client.sendAttachment(File(path));
client.requestHuman();

// Back in the foreground (screen on, picker closed): check the connection.
await client.ensureConnected();

client.dispose();
© 2025 كونكتلي. جميع الحقوق محفوظة.
الأسئلة الشائعة سياسة الخصوصية العودة للرئيسية