FlowHunt JS API: دليل التكامل للمستخدمين المتقدمين

مرجع شامل لتكامل FlowHunt JS API الإصدار الثاني. تعلم كيفية تضمين روبوت الدردشة والاشتراك في جميع الأحداث العشرة واستخدام متغيرات التدفق وتتبع التفاعلات باستخدام معلمات URL والتحكم في نافذة الدردشة برمجياً.

FlowHunt JavaScript API Chatbot Integration

يمنحك FlowHunt JS API تحكماً كاملاً في كيفية تكامل روبوت الدردشة مع موقعك الإلكتروني. باستخدام كود التكامل الإصدار الثاني، يمكنك تضمين روبوت الدردشة والاشتراك في أحداث دورة الحياة والتفاعل وتمرير البيانات الديناميكية عبر متغيرات التدفق وتتبع التفاعلات باستخدام معلمات URL والتحكم في نافذة الدردشة برمجياً.

يغطي هذا الدليل كل جانب من جوانب JS API مع أمثلة كود يمكنك نسخها وتكييفها مع مشروعك.

كود التكامل (الإصدار الثاني)

عندما تنشئ روبوت دردشة في FlowHunt، تحصل على مقتطف تكامل. انسخه والصقه في HTML الخاص بك قبل وسم الإغلاق </body> مباشرة:

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // The chatbot is ready — use chatbotManager here
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

استبدل YOUR_CHATBOT_ID و YOUR_WORKSPACE_ID بالقيم من لوحة تحكم FlowHunt الخاصة بك. معرف روبوت الدردشة في اسم المتغير العام (window.FHChatbot_YOUR_CHATBOT_ID) يستخدم الشرطات السفلية بدلاً من الواصلات.

تجاوز التكوين باستخدام setConfig()

قبل استدعاء init()، يمكنك تجاوز إعدادات روبوت الدردشة الافتراضية باستخدام setConfig():

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      headerTitle: 'Support Assistant',
      maxWindowWidth: '700px',
      showChatButton: false,
      flowVariables: {
        userId: '12345',
        plan: 'enterprise'
      },
      urlSuffix: '?utm_source=chatbot'
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Chatbot initialized with custom config
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

خيارات التكوين المتاحة

OptionTypeDescription
headerTitlestringنص عنوان رأسي مخصص
maxWindowWidthstringالحد الأقصى لعرض نافذة الدردشة (مثال '700px')
maxWindowHeightstringالحد الأقصى لارتفاع نافذة الدردشة
inputPlaceholderstringنص العنصر النائب لحقل إدخال الرسالة
showChatButtonbooleanإظهار أو إخفاء زر الدردشة العائم الافتراضي
openChatPanelbooleanفتح لوحة الدردشة تلقائياً عند تحميل الصفحة
flowVariablesobjectأزواج المفتاح والقيمة للبيانات المخصصة المُمررة إلى التدفق
urlSuffixstringسلسلة استعلام تُلحق بجميع عناوين URL التي ينشئها روبوت الدردشة
cookieConsentbooleanتفعيل استمرار الجلسة عبر ملفات تعريف الارتباط
embeddedstringتعيين لتفعيل الوضع المضمّن (بدون زر إغلاق)
themestringوضع السمة
Logo

هل أنت مستعد لتنمية عملك؟

ابدأ تجربتك المجانية اليوم وشاهد النتائج في غضون أيام.

طلب عرض توضيحي تسجيل الدخول

متغيرات التدفق: تمرير البيانات الديناميكية

تتيح لك متغيرات التدفق إرسال بيانات مخصصة من موقعك الإلكتروني إلى تدفق روبوت الدردشة. يتيح هذا محادثات مخصصة بناءً على سياق المستخدم.

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  flowVariables: {
    userId: getCurrentUserId(),
    userEmail: getCurrentUserEmail(),
    currentPage: window.location.pathname,
    plan: 'enterprise'
  }
});

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

URL Suffix: تتبع تفاعلات روبوت الدردشة

يُلحق معلمة urlSuffix سلسلة استعلام بكل عنوان URL ينشئه روبوت الدردشة. هذا مفيد لتتبع حركة المرور الناتجة عن روبوت الدردشة في أدوات التحليل:

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  urlSuffix: '?utm_source=chatbot&utm_medium=widget'
});

حالات الاستخدام:

  • تتبع التحويلات من تفاعلات روبوت الدردشة في Google Analytics.
  • تحليل سلوك المستخدم بعد التفاعل مع روبوت الدردشة.
  • نسب الحملات التي تعزز مشاركة روبوت الدردشة.

مرجع الأحداث

يرسل FlowHunt JS API عشرة أحداث مخصصة على كائن window. تستخدم جميع الأحداث واجهة CustomEvent مع bubbles: true و composed: true.

onFHChatbotReady

يُطلق عندما يكتمل عرض ودجت روبوت الدردشة ويصبح جاهزاً للاستخدام.

  • بيانات الحدث: لا شيء
  • متى: بعد تركيب DOM الودجت وظهور زر الدردشة.

onFHChatbotSessionCreated

يُطلق عند إنشاء جلسة دردشة جديدة على الخادم. يُطلق أيضاً عند إعادة تشغيل الجلسة.

  • بيانات الحدث: لا شيء
  • متى: بعد استدعاء API ناجح لإنشاء الجلسة.

onFHChatbotWindowOpened

يُطلق عندما يفتح المستخدم نافذة الدردشة.

  • بيانات الحدث: لا شيء
  • متى: عندما تصبح لوحة الدردشة مرئية.
  • ملاحظة: لا يُطلق في الوضع المضمّن.

onFHChatbotWindowClosed

يُطلق عندما يغلق المستخدم نافذة الدردشة.

  • بيانات الحدث: لا شيء
  • متى: عندما تُخفى لوحة الدردشة.
  • ملاحظة: لا يُطلق في الوضع المضمّن.

onFHMessageSent

يُطلق عندما يرسل المستخدم رسالة.

  • بيانات الحدث (event.detail.metadata):
{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

يُطلق عندما يستقبل روبوت الدردشة رداً ويعرضه.

  • بيانات الحدث (event.detail.metadata):
{
  "flow_id": "abc123",
  "message_id": "msg_456",
  "message": "Sure, I can help you with that!",
  "sender": {
    "sender_name": "Support Agent",
    "sender_avatar": "https://example.com/avatar.png"
  }
}

حقل sender اختياري ويكون موجوداً فقط عندما يكون وكيل بشري مشاركاً.

onFHFormDataSent

يُطلق عندما يرسل المستخدم بيانات نموذج عبر روبوت الدردشة.

  • بيانات الحدث (event.detail.metadata):
{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

يُطلق عندما يقدم المستخدم تقييماً إيجابياً أو سلبياً على رسالة روبوت الدردشة.

  • بيانات الحدث (event.detail.metadata):
{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

قيمة feedback هي "P" للإيجابي (إعجاب) أو "N" للسلبي (عدم إعجاب).

onFHToolCall

يُطلق عند تنفيذ أداة أو إجراء أثناء معالجة التدفق.

  • بيانات الحدث (event.detail.metadata):
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

ملاحظة: يُطلق فقط في أوضاع flowAssistant و flowAssistantV3، وليس في وضع روبوت الدردشة القياسي.

onFHError

يُطلق عند حدوث خطأ أثناء تشغيل روبوت الدردشة.

  • بيانات الحدث (event.detail.metadata):
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

الاشتراك في الأحداث

هناك طريقتان للاشتراك في أحداث روبوت الدردشة.

الطريقة الأولى: مستمعو أحداث النافذة

استخدم window.addEventListener في أي مكان في صفحتك. يعمل هذا حتى قبل تحميل روبوت الدردشة:

<script>
document.addEventListener('DOMContentLoaded', function() {
  // Chatbot lifecycle events
  window.addEventListener('onFHChatbotReady', function(event) {
    console.log('Chatbot is ready');
  });

  window.addEventListener('onFHChatbotSessionCreated', function(event) {
    console.log('Session created');
  });

  window.addEventListener('onFHChatbotWindowOpened', function(event) {
    console.log('Chat window opened');
  });

  window.addEventListener('onFHChatbotWindowClosed', function(event) {
    console.log('Chat window closed');
  });

  // Message events
  window.addEventListener('onFHMessageSent', function(event) {
    console.log('User sent:', event.detail.metadata.content);
  });

  window.addEventListener('onFHMessageReceived', function(event) {
    console.log('Bot replied:', event.detail.metadata.message);
  });

  window.addEventListener('onFHFormDataSent', function(event) {
    console.log('Form submitted:', event.detail.metadata.objectData);
  });

  // Feedback
  window.addEventListener('onFHFeedback', function(event) {
    var feedback = event.detail.metadata;
    console.log('Feedback on message', feedback.message_id, ':',
      feedback.feedback);
  });

  // Tool calls (flowAssistant modes only)
  window.addEventListener('onFHToolCall', function(event) {
    console.log('Tool called:', event.detail.metadata);
  });

  // Errors
  window.addEventListener('onFHError', function(event) {
    console.error('Chatbot error:', event.detail.metadata);
  });
});
</script>

لإيقاف الاستماع إلى حدث، استخدم removeEventListener مع نفس مرجع الدالة:

var handleMessage = function(event) {
  console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);

// Later, when you want to stop listening:
window.removeEventListener('onFHMessageReceived', handleMessage);

الطريقة الثانية: طرق الاستدعاء الراجع للمدير

داخل استدعاء init() الراجع، استخدم الطرق المدمجة لمدير روبوت الدردشة:

window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
  chatbotManager.onSessionCreated(function() {
    console.log('Session created');
  });

  chatbotManager.onWindowOpened(function() {
    console.log('Window opened');
  });

  chatbotManager.onWindowClosed(function() {
    console.log('Window closed');
  });

  chatbotManager.onMessageSent(function(event) {
    console.log('User sent:', event.metadata);
  });

  chatbotManager.onMessageReceived(function(event) {
    console.log('Bot replied:', event.metadata);
  });

  chatbotManager.onFormDataSent(function(event) {
    console.log('Form data:', event.metadata);
  });

  chatbotManager.onFeedback(function(event) {
    console.log('Feedback:', event.metadata);
  });

  chatbotManager.onToolCall(function(event) {
    console.log('Tool call:', event.metadata);
  });

  chatbotManager.onError(function(event) {
    console.error('Error:', event.metadata);
  });
});

مرجع طرق المدير

MethodParametersDescription
onSessionCreated(fn)fn: () => voidالاستماع لإنشاء الجلسة
onWindowOpened(fn)fn: () => voidالاستماع لفتح النافذة
onWindowClosed(fn)fn: () => voidالاستماع لإغلاق النافذة
onMessageSent(fn)fn: (event) => voidالاستماع لرسائل المستخدم
onMessageReceived(fn)fn: (event) => voidالاستماع لردود الروبوت
onFormDataSent(fn)fn: (event) => voidالاستماع لإرسال النماذج
onFeedback(fn)fn: (event) => voidالاستماع لتقييمات المستخدم
onToolCall(fn)fn: (event) => voidالاستماع لتنفيذ الأدوات
onError(fn)fn: (event) => voidالاستماع للأخطاء
openChat()—يفتح لوحة الدردشة
closeChat()—يغلق لوحة الدردشة

تفعيل الدردشة المخصص: إخفاء الزر والفتح عند النقر

للتحكم الكامل في وقت ظهور روبوت الدردشة، أخفِ الزر العائم الافتراضي وافتح الدردشة برمجياً — على سبيل المثال، من زر مخصص خاص بك.

مثال كامل

<!-- Your custom chat button -->
<button id="my-chat-button">Chat with us</button>

<!-- FlowHunt integration with hidden default button -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Open chat when your custom button is clicked
      document.getElementById('my-chat-button')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

إظهار زر مخصص فقط عندما يكون روبوت الدردشة جاهزاً

يمكنك الجمع بين التفعيل المخفي ومستمعي الأحداث لإنشاء تفاعلات متقدمة:

<button id="open-chat" style="display:none;">Need help?</button>

<script>
// Show a custom button only when the chatbot is ready
window.addEventListener('onFHChatbotReady', function() {
  document.getElementById('open-chat').style.display = 'block';
});
</script>

<!-- FlowHunt integration -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      document.getElementById('open-chat')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

مثال التكامل الكامل

مثال عملي كامل يوضح تجاوز التكوين وتتبع الأحداث وتفعيل الدردشة المخصص معاً:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>FlowHunt Chatbot Integration</title>
</head>
<body>
  <h1>My Website</h1>
  <button id="open-chat-btn">Talk to our AI assistant</button>
  <button id="close-chat-btn">Close chat</button>

  <!-- Subscribe to events before the chatbot loads -->
  <script>
  document.addEventListener('DOMContentLoaded', function() {
    window.addEventListener('onFHChatbotReady', function() {
      console.log('Chatbot widget is ready');
    });

    window.addEventListener('onFHChatbotSessionCreated', function() {
      console.log('New chat session started');
    });

    window.addEventListener('onFHMessageSent', function(event) {
      console.log('User message:', event.detail.metadata.content);
    });

    window.addEventListener('onFHMessageReceived', function(event) {
      console.log('Bot response:', event.detail.metadata.message);
    });

    window.addEventListener('onFHFeedback', function(event) {
      var fb = event.detail.metadata;
      if (fb.feedback === 'P') {
        console.log('Positive feedback on message', fb.message_id);
      } else {
        console.log('Negative feedback on message', fb.message_id);
      }
    });

    window.addEventListener('onFHError', function(event) {
      console.error('Chatbot error:', event.detail.metadata);
    });
  });
  </script>

  <!-- FlowHunt integration -->
  <script id="fh-chatbot-script-YOUR_CHATBOT_ID">
    var currentScript = document.currentScript
      || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
      + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

    script.onload = function() {
      window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
        showChatButton: false,
        headerTitle: 'AI Assistant',
        maxWindowWidth: '600px',
        flowVariables: {
          source: 'website',
          page: window.location.pathname
        },
        urlSuffix: '?utm_source=chatbot'
      });

      window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
        document.getElementById('open-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.openChat();
          });

        document.getElementById('close-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.closeChat();
          });
      });
    };

    if (currentScript && currentScript.parentNode) {
      currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
    } else {
      document.head.appendChild(script);
    }
  </script>
</body>
</html>

الأسئلة الشائعة

ما هي الأحداث التي يمكنني الاستماع إليها باستخدام FlowHunt JS API؟

يصدر FlowHunt JS API عشرة أحداث: onFHChatbotReady و onFHChatbotSessionCreated و onFHChatbotWindowOpened و onFHChatbotWindowClosed و onFHMessageSent و onFHMessageReceived و onFHFormDataSent و onFHFeedback و onFHToolCall و onFHError. يمكنك الاشتراك فيها باستخدام window.addEventListener أو من خلال طرق الاستدعاء الراجع لمدير روبوت الدردشة.

كيف أخفي زر الدردشة الافتراضي وأفتح روبوت الدردشة برمجياً؟

استخدم خيار التكوين showChatButton: false لإخفاء الزر الافتراضي، ثم استدعِ chatbotManager.openChat() لفتح روبوت الدردشة وفقاً لشروطك الخاصة — على سبيل المثال، عند النقر على زر مخصص.

ما الفرق بين طرق الاستدعاء الراجع للمدير و window.addEventListener؟

كلا النهجين يعملان. طرق الاستدعاء الراجع للمدير (مثل chatbotManager.onMessageSent(fn)) تُستدعى داخل استدعاء init الراجع وترتبط بنسخة المدير. نهج window.addEventListener (مثل window.addEventListener('onFHMessageSent', fn)) يمكن إعداده في أي مكان في صفحتك، حتى قبل تحميل روبوت الدردشة.

كيف أمرر بيانات مخصصة إلى روبوت الدردشة باستخدام متغيرات التدفق؟

استخدم خيار التكوين flowVariables في setConfig() لتمرير أزواج المفتاح والقيمة مثل معرف المستخدم أو البريد الإلكتروني أو عنوان URL للصفحة. تصبح هذه المتغيرات متاحة داخل تدفق روبوت الدردشة للردود المخصصة.

ما البيانات المتاحة في معالجات الأحداث؟

الأحداث التي تحمل بيانات تتضمنها في event.detail.metadata. على سبيل المثال، يتضمن onFHMessageSent محتوى الرسالة والطابع الزمني، ويتضمن onFHMessageReceived معرف التدفق ومعرف الرسالة ونص الرسالة، ويتضمن onFHFeedback معرف الرسالة وما إذا كانت التغذية الراجعة إيجابية أم سلبية.