القنوات المخصصة #

قم بتوصيل أي منصة مراسلة أو أداة تواصل بالمنصة باستخدام القنوات المخصصة. يتيح لك هذا جلب الرسائل من منصات مثل أدوات الدردشة المباشرة على المواقع الإلكترونية، أو أنظمة البريد الإلكتروني، أو أنظمة إدارة علاقات العملاء (CRMs)، أو أي خدمة أخرى إلى صندوق الوارد الخاص بك — والرد عليها باستخدام وكيل الذكاء الاصطناعي الخاص بك.

ما هي القنوات المخصصة؟ #

تعمل القنوات المخصصة على توسيع نطاق المنصة إلى ما هو أبعد من منصات المراسلة المدمجة فيها (WhatsApp، وSMS، وInstagram، وMessenger). باستخدام القنوات المخصصة، يمكنك:

• استقبال الرسائل من أي منصة خارجية إلى صندوق الوارد الموحد للمنصة.
• إرسال الردود من التطبيق إلى منصتك الخارجية تلقائياً.
• استخدام وكيل الذكاء الاصطناعي للرد على الرسائل من أي مصدر.
• تتبع جميع المحادثات جنباً إلى جنب مع قنواتك الأخرى في صندوق وارد واحد.

يُعد هذا مثالياً للشركات التي تستخدم أدوات تواصل متخصصة، أو لديها منصة مبنية خصيصاً، أو ترغب في تجميع جميع رسائل العملاء في مكان واحد.

كيف يعمل #

تعمل القنوات المخصصة عن طريق تبادل الرسائل ذهاباً وإياباً بين منصتك الخارجية والمنصة باستخدام خطافات الويب (webhooks) (رسائل آلية يتم إرسالها بين الأنظمة عبر الإنترنت). إليك آلية العمل:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. الرسائل الواردة: ترسل منصتك الخارجية الرسائل إلى عنوان ويب (URL). فكر في الأمر على أنه “نشر” منصتك لرسالة في صندوق بريد المنصة.
2. المعالجة: تقوم المنصة بإنشاء جهة الاتصال أو تحديثها، وتخزين الرسالة، وتكليف وكيل الذكاء الاصطناعي بإنشاء رد (إذا كان مفعلاً).
3. الرسائل الصادرة: عندما ترسل المنصة رداً (سواء من الذكاء الاصطناعي أو كتبته أنت)، فإنها ترسل الرسالة إلى عنوان URL على منصتك، حيث يمكن لنظامك توصيلها إلى المستخدم النهائي.

إعداد الرسائل الواردة (من منصتك إلى التطبيق) #

لإرسال رسائل من منصتك الخارجية إلى التطبيق، تحتاج منصتك إلى إرسال البيانات إلى عنوان URL التالي. سيتعرف مطورك على هذا كطلب POST قياسي (وهي طريقة شائعة لنظام ما لإرسال البيانات إلى نظام آخر عبر الإنترنت).

أين ترسل الرسائل #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

استبدل YOUR_API_KEY بمفتاح API الخاص بك (وهو رمز خاص يثبت للمنصة أن منصتك مخولة بإرسال الرسائل إليها). يمكنك العثور عليه أو إنشاؤه ضمن الإعدادات (Settings) ← عمليات التكامل (Integrations) ← مفتاح API.

تنسيق الرسالة #

أرسل بيانات الرسالة بالتنسيق التالي (JSON):

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

ماذا يعني كل جزء:

• messageSid - معرف فريد لهذه الرسالة المحددة (يقوم نظامك بإنشائه). يُستخدم لمنع معالجة نفس الرسالة مرتين.
• fromId - من أرسل الرسالة (يمكن أن يكون معرف مستخدم، أو بريداً إلكترونياً، أو رقم هاتف من نظامك).
• toId - معرف نشاطك التجاري (يمكن أن يكون أي تسمية تختارها).
• body - نص الرسالة الفعلي.
• channel - تسمية تختارها لتحديد مصدر الرسالة (على سبيل المثال: “website-chat”، “email”).

مرجع الحقول الكامل #

تفاعلات الرموز التعبيرية #

إذا كانت منصتك تدعم تفاعلات الرموز التعبيرية (مثل إبداء الإعجاب برسالة ما)، فأرسلها كتفاعل بدلاً من إرسالها كرسالة نصية: اضبط messageType على "reaction" وضع الرمز التعبيري فقط في customData.body.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

سيتعامل المساعد معها بعد ذلك بالطريقة التي تتوقعها:

• يُعامل التفاعل مع سؤال طرحه المساعد (على سبيل المثال “هل يوم الخميس مناسب؟”) كإجابة، وسيقوم المساعد بالرد.
• يُعامل التفاعل مع رسالة ختامية (على سبيل المثال “نتحدث قريباً!”) كإنهاء للمحادثة بهدوء. ولن يتم إرسال أي رد.

إذا كانت منصتك تحوّل التفاعلات إلى نص مثل “تم التفاعل بـ: 👍”، فسيراها المساعد كرسالة نصية عادية ويقرر بنفسه ما إذا كان سيرد أم لا. إرسال نوع التفاعل يتجنب حدوث ذلك.

ما الذي تحصل عليه في المقابل #

الطلب الناجح يعيد:

{
  "success": true,
  "messageId": "1234567890"
}

إذا حدث خطأ ما، فستتلقى رسالة خطأ توضح المشكلة:

{
  "error": "Message body cannot be empty"
}

رموز الحالة #

إذا قمت بتعيين customData.status، فإن القيمة الوحيدة المقبولة هي "received" — اتركها فارغة تماماً لاستخدام القيمة الافتراضية بدلاً من إرسال أي شيء آخر، وإلا ستحصل على 400.

إرسال مرفقات الوسائط (صور، فيديوهات، ملفات) #

يمكنك تضمين مرفقات ملفات (صور، فيديوهات، صوت، مستندات) مع رسائلك. هناك طريقتان للقيام بذلك:

الخيار 1: رابط لملف #

إذا كان الملف مستضافاً بالفعل عبر الإنترنت، فقم بتوفير الرابط (عنوان الويب) حيث يمكن للمنصة تنزيله:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

الخيار 2: تضمين الملف مباشرة (Base64) #

إذا لم يكن الملف مستضافاً عبر الإنترنت، يمكنك تضمينه مباشرة في الرسالة كنص مشفر (بتنسيق base64). هذا أمر شائع في عمليات التكامل التقنية حيث يقوم نظامك بإنشاء الملفات بشكل فوري. ستقوم المنصة بفك تشفير الملف وتخزينه تلقائياً:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

إعداد الرسائل الصادرة (من المنصة إلى منصتك) #

عندما ترسل المنصة رداً على قناة مخصصة (سواء من الذكاء الاصطناعي أو كتبته أنت)، فإنها ترسل هذا الرد تلقائياً إلى عنوان URL على منصتك حتى يتمكن نظامك من توصيله إلى المستخدم النهائي.

قم بتعيين عنوان URL الخاص بـ webhook أولاً. يجب عليك حفظ عنوان URL الخاص بـ webhook للقناة المخصصة قبل إمكانية تسليم أي ردود. إذا لم يتم حفظ أي عنوان URL، فسيتم إنشاء الردود وتخزينها، ولكن لن يتم إرسالها أبداً — ولن تظهر حالة “فشل” (Failed)، لذا لن يشير أي شيء في صندوق الوارد الخاص بك إلى وجود مشكلة. قم دائماً بتهيئة عنوان URL الخاص بـ webhook قبل البدء في العمل الفعلي.

إخبار التطبيق بمكان إرسال الردود #

1. في الشريط الجانبي الأيسر، انقر على Settings بالقرب من الأسفل.
2. في القائمة الجانبية للإعدادات، تحت Channels، انقر على Channels.
3. ابحث عن بطاقة Custom channel في أسفل الصفحة تماماً (بعد Android SMS Gateway، وiMessage، وعنصر واجهة دردشة الموقع، وحساب Twilio، والامتثال التنظيمي).
4. أدخل Webhook URL — وهو الرابط (URL) الموجود على منصتك حيث يجب أن يرسل الذكاء الاصطناعي الرسائل الصادرة (يقوم مطورك بإعداد هذا لاستلام الردود ومعالجتها). يجب أن يكون رابط HTTPS عاماً — سيتم رفض عناوين http:// والمضيفين غير العامين.
5. انقر على Save.

ما ترسله المنصة إلى منصتك #

عندما ترسل المنصة رداً، ستتلقى منصتك البيانات التالية:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}

ماذا يعني كل حقل #

تتلقى منصتك هذه البيانات وتستخدمها لتسليم الرد إلى المستخدم النهائي من خلال نظامك الخاص.

كيف تتعقب المنصة التسليم #

بعد إرسال الرد إلى منصتك، تقوم المنصة بتحديث حالة الرسالة:

• تم الإرسال (Sent) - استلمت منصتك الرسالة بنجاح.
• فشل (Failed) - أعادت منصتك خطأ أو تعذر الوصول إليها. تخزن المنصة تفاصيل الخطأ مع الرسالة حتى تتمكن من استكشاف الأخطاء وإصلاحها.

إرسال الرسائل من نظامك إلى التطبيق #

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

متطلبات الخطة. يتطلب إرسال ومزامنة الرسائل عبر واجهة برمجة التطبيقات (API) خطة تتضمن الوصول إلى API وقناة مراسلة واحدة على الأقل. إذا تلقيت خطأ 403 “تم رفض الإذن / الميزة غير مفعلة”، فهذا يعني أن خطتك الحالية لا تتضمن هذه الميزة — قم بترقية خطتك أو اتصل بالدعم.

أين ترسل #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

تنسيق الرسالة #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

الحقول المطلوبة #

تعمل الحقول الاختيارية (campaignId، firstName، lastName، email) بنفس الطريقة كما في الرسائل الواردة — فهي تساعد المنصة في إنشاء سجل جهة الاتصال أو تحديثه.

ما الذي تحصل عليه في المقابل #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

تسجيل الرسائل المرسلة من نظام آخر #

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

أين ترسل #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

قم بتضمين customData.fromId (معرف جهة الاتصال على منصتك) و customData.body (نص الرسالة التي تم إرسالها بالفعل).

كيف يعمل #

• يتم تسجيل الرسالة، وليس إعادة إرسالها. تخزنها المنصة في المحادثة للسياق فقط.
• يتم إيقاف الذكاء الاصطناعي مؤقتاً لجهة الاتصال هذه افتراضياً. هذا يمنع الروبوت من الرد فوق رسالة تعامل معها إنسان بالفعل. لإبقاء الروبوت نشطاً، مرر customData.pauseAi: false.
• يمكن إنشاء جهات اتصال جديدة تلقائياً. قم بتضمين customData.customChannel وسيتم إنشاء جهة الاتصال إذا لم تكن موجودة بالفعل.
• يتم تجاهل التكرارات. إذا أعدت استخدام نفس messageSid، تدرك المنصة أن الرسالة قد تم تسجيلها بالفعل ولا تجري أي تغييرات.

متطلبات الخطة. مثل الإرسال، يتطلب تسجيل الرسائل عبر واجهة برمجة التطبيقات (API) خطة تتضمن الوصول إلى واجهة برمجة التطبيقات وقناة مراسلة واحدة على الأقل. يعني ظهور خطأ 403 “تم رفض الإذن / الميزة غير ممكّنة” أن خطتك الحالية لا تتضمن ذلك.

أمثلة من العالم الحقيقي #

الدردشة المباشرة على الموقع الإلكتروني #

قم بتوصيل أداة الدردشة المباشرة على موقعك الإلكتروني بالمنصة حتى يتمكن وكيل الذكاء الاصطناعي الخاص بك من الإجابة على أسئلة الزوار:

1. يكتب الزائر رسالة في أداة الدردشة على موقعك الإلكتروني.
2. ترسل أداة الدردشة الرسالة إلى المنصة.
3. يقوم وكيل الذكاء الاصطناعي بإنشاء رد.
4. يتم إرسال الرد مرة أخرى إلى أداة الدردشة الخاصة بك، والتي تعرضه للزائر.

لماذا هذا مفيد: يحصل زوار موقعك الإلكتروني على إجابات فورية مدعومة بالذكاء الاصطناعي لأسئلتهم دون الحاجة إلى تواجدك عبر الإنترنت.

البريد الإلكتروني #

قم بتوجيه محادثات البريد الإلكتروني عبر المنصة حتى يتمكن وكيل الذكاء الاصطناعي الخاص بك من الرد على رسائل البريد الإلكتروني:

1. قم بإعداد نظام يقوم بإعادة توجيه رسائل البريد الإلكتروني الواردة إلى المنصة (باستخدام عنوان مرسل البريد الإلكتروني كـ fromId، وموضوع البريد الإلكتروني ومحتواه كـ body، و "email" كـ channel).
2. يقرأ وكيل الذكاء الاصطناعي البريد الإلكتروني وينشئ رداً.
3. يتم إرسال الرد مرة أخرى إلى نظام البريد الإلكتروني الخاص بك، والذي يرسله كرسالة بريد إلكتروني عادية.

لماذا هذا مفيد: يتم الرد على أسئلة البريد الإلكتروني الشائعة (الأسعار، ساعات العمل، التوفر) فوراً بواسطة وكيل الذكاء الاصطناعي الخاص بك.

إذا كان نظام البريد الإلكتروني الخاص بك يدعم IMAP/SMTP أو OAuth، فقد تكون قناة البريد الإلكتروني المدمجة أبسط من التكامل المخصص.

تكامل نظام إدارة علاقات العملاء (CRM) #

قم بتوصيل نظام إدارة علاقات العملاء (CRM) الحالي الخاص بك بالمنصة:

1. عندما يرسل عميل محتمل رسالة عبر نظام إدارة علاقات العملاء (CRM) الخاص بك، قم بإعادة توجيهها إلى المنصة.
2. يستجيب وكيل الذكاء الاصطناعي ويتتبع المحادثة.
3. يتم إرسال رد الذكاء الاصطناعي مرة أخرى إلى نظام CRM الخاص بك للتسليم.
4. يتوفر سجل المحادثة الكامل في كل من المنصة ونظام CRM الخاص بك.

لماذا هذا مفيد: يحصل فريق المبيعات لديك على ردود مدعومة بالذكاء الاصطناعي للعملاء المحتملين دون مغادرة نظام CRM الخاص بهم.

نظام تذاكر الدعم الفني #

استخدم المنصة كخط دفاع أول مدعوم بالذكاء الاصطناعي لدعم العملاء:

1. يقوم نظام التذاكر الخاص بك بإعادة توجيه تذاكر الدعم الجديدة إلى المنصة.
2. يرسل وكيل الذكاء الاصطناعي رداً أولياً (على سبيل المثال، الإقرار باستلام التذكرة وطرح أسئلة توضيحية).
3. يتم إرفاق الرد بالتذكرة في نظام الدعم الخاص بك.
4. يمكن لفريق الدعم الخاص بك مراجعة ما قاله الذكاء الاصطناعي وتولي المهمة عند الحاجة.

لماذا هذا مفيد: يحصل العملاء على تأكيد فوري ومساعدة أولية، حتى خارج ساعات العمل.

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

الرسائل لا تصل إلى المنصة #

• تحقق من أن مفتاح API الخاص بك صحيح ونشط (تحقق من الإعدادات ← عمليات التكامل ← مفتاح API).
• تأكد من أنك ترسل طلب POST (وليس GET). سيعرف مطورك الفرق بينهما.
• تحقق من أن الحقل customData.body ليس فارغاً أو يحتوي على مسافات فقط.
• تحقق من تضمين الحقل customData.fromId.
• اقرأ رسالة الرد للحصول على تفاصيل خطأ محددة.

الردود لا تصل إلى منصتك #

• تأكد من إدخال عنوان URL الخاص بمنصتك في بطاقة القناة المخصصة في صفحة القنوات. إذا لم يتم حفظ أي عنوان URL، فسيتم إنشاء الردود وتخزينها ولكن لن يتم إرسالها أبداً — ولن يتم تمييزها على أنها “فاشلة”، لذا تحقق من هذا أولاً.
• تحقق من أن عنوان URL متاح للجمهور (ليس خلف تسجيل دخول أو جدار حماية) ويعيد استجابة ناجحة.
• يتم إرسال الردود فقط (الرسائل الصادرة) إلى عنوان URL الخاص بك — الرسائل الواردة لا تؤدي إلى تشغيل هذا.
• تحقق من تفاصيل الخطأ في الرسالة الموجودة في صندوق الوارد الخاص بك.

جهة الاتصال لا يتم إنشاؤها #

• تأكد من أن قيمة fromId متسقة لنفس المستخدم عبر جميع رسائله. تستخدم المنصة هذه القيمة لتحديد جهات الاتصال — إذا تغيرت بين الرسائل، فستنشئ المنصة جهة اتصال جديدة في كل مرة.
• قم بتضمين firstName و lastName و email في الرسالة الأولى من جهة اتصال جديدة لإنشاء سجل اتصال كامل.

مرفقات الوسائط لا تعمل #

• بالنسبة لروابط الملفات (URLs)، تأكد من أن الملف متاح للجمهور (لا يلزم تسجيل دخول للوصول إليه).
• قم دائماً بتضمين mediaContentType عند تضمين mediaUrl.
• بالنسبة للملفات المضمنة (base64)، تحقق من أن التنسيق هو data:MIME_TYPE;base64,ENCODED_DATA.
• تأكد من أن نوع الملف الذي تحدده يطابق محتوى الملف الفعلي.

أفضل الممارسات #

• استخدم قيم fromId متسقة. يجب أن يكون لكل مستخدم على منصتك دائماً نفس fromId. يضمن هذا أن تقوم المنصة بتجميع جميع رسائلهم في محادثة واحدة بدلاً من إنشاء جهات اتصال مكررة.
• اختر اسماً واضحاً لـ channel. اختر شيئاً وصفياً مثل "website-chat" أو "email" أو "zendesk" حتى تتمكن من معرفة مصدر الرسائل بسهولة عند عرض صندوق الوارد الخاص بك.
• قم بتضمين تفاصيل الاتصال (firstName، lastName، email) في الرسالة الأولى من جهة اتصال جديدة. هذا ينشئ سجل اتصال كاملاً ومفيداً على الفور.
• قم ببناء منطق إعادة المحاولة. اجعل منصتك تعيد محاولة إرسال الرسائل إذا لم تستجب المنصة في المحاولة الأولى (تحدث مشاكل في الشبكة).
• استخدم قيم messageSid فريدة لكل رسالة. هذا يمنع معالجة نفس الرسالة مرتين إذا أرسلها نظامك أكثر من مرة.
• استخدم campaignId لتوجيه الرسائل إلى وكلاء ذكاء اصطناعي مختلفين عندما يكون لديك حالات استخدام متعددة (على سبيل المثال، استفسارات المبيعات مقابل أسئلة الدعم).
• اختبر قبل الإطلاق. أرسل رسائل اختبار في كلا الاتجاهين وتحقق من أن جهات الاتصال والمحادثات وردود الذكاء الاصطناعي تعمل جميعها بشكل صحيح قبل الإطلاق للمستخدمين الحقيقيين.