القناة المخصصة

تربط القناة المخصصة أي نظام مراسلة يستطيع إرسال واستقبال webhooks بصندوق الوارد المشترك في Resool: محادثة تطبيقك الخاص، أو بوابة رسائل نصية محلية، أو محادثة مباشرة داخلية، أو منصة مراسلة لا يدعمها Resool مباشرة. يرسل نظامك رسائل العملاء (POST) إلى عنوان استقبال يعطيك إياه Resool، ويرسل Resool كل رد من الموظفين إلى عنوان webhook تختاره. وكل طلب موقّع بسر مشترك، فيتأكد الطرفان من أن الرسالة أصلية.

#ما الذي يمكنك فعله مع القناة المخصصة

في صندوق الوارد

• استقبل الرسائل من نظامك كمحادثات، مع نص وحتى 5 مرفقات لكل رسالة.
• ردّ من صندوق الوارد كأي قناة، ويُرسل كل رد إلى webhook الردود بصيغة JSON موقّعة.
• اعرف إن كانت الردود قد سُلّمت أو قُرئت أو فشلت عندما يبلغ نظامك عن الحالة.

في القناة

• اختر نوع القناة (مراسلة أو رسائل نصية أو محادثة مباشرة) لتظهر المحادثات بالتصنيف الصحيح.
• ولّد سر توقيع جديدًا في أي وقت.

#قبل أن تبدأ

• مطوّر يستطيع جعل نظامك يرسل طلبات HTTPS موقّعة إلى Resool ويستقبل طلبات Resool.
• عنوان HTTPS عام في نظامك لاستقبال الردود (عنوان webhook للردود).
• في Resool، يستطيع المالكون والمسؤولون فقط إنشاء القنوات. وتُحتسب القناة المخصصة قناةً واحدة ضمن حد خطتك.

#كيفية إنشاء قناة مخصصة

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

مكان لقطة الشاشة

الإعدادات › القنوات › إضافة قناة، تبويب الكل

كتالوج القنوات وفيه بطاقة «قناة مخصصة» في المراسلة التجارية، و«قناة مخصصة (رسائل نصية)» في الرسائل النصية، و«قناة مخصصة (محادثة مباشرة)» في المحادثة المباشرة، ولكل منها أيقونة webhook وزر ربط.

الملف: screenshots/ar/custom-channel-catalog.png

1. في مربع ربط قناة مخصصة، املأ:
   • اسم القناة: كيف تظهر القناة في Resool (حتى 60 حرفًا).
   • نوع القناة: مراسلة أو رسائل نصية أو محادثة مباشرة.
   • عنوان webhook للردود (اختياري): العنوان الذي يرسل إليه Resool كل رد. إذا تركته فارغًا فلن تُسلَّم الردود وستظهر كفاشلة في صندوق الوارد. يمكنك إضافته لاحقًا.
2. اضغط إنشاء القناة.
3. تظهر خطوة احفظ سر التوقيع وفيها سر التوقيع وعنوان الاستقبال. انسخهما واحفظ السر في مكان آمن، فهو يظهر الآن فقط.

مكان لقطة الشاشة

الإعدادات › القنوات › إضافة قناة › قناة مخصصة › إنشاء القناة

خطوة «احفظ سر التوقيع» بشرحها، وحقلا سر التوقيع وعنوان الاستقبال مع زرّي النسخ، وزر «حفظته، متابعة».

الملف: screenshots/ar/custom-channel-signing-secret.png

1. اضغط حفظته، متابعة. تُفتح صفحة القناة.

#كيفية إرسال رسائل العملاء إلى Resool

أرسل كل رسالة عميل بصيغة JSON (POST) إلى عنوان الاستقبال، موقّعة بسرك.

نص الطلب

{
  "event": "message",
  "contact": { "id": "cust-1", "name": "Nora", "email": "nora@example.com", "phone": "+15551234567" },
  "message": { "id": "m-1", "text": "Hello", "attachments": [] }
}

• contact.id (مطلوب): معرّف العميل في نظامك. يجمع Resool كل الرسائل ذات المعرّف نفسه في جهة اتصال واحدة. الحقول name وemail وphone اختيارية.
• message.text (حتى 4,096 حرفًا) و/أو message.attachments (حتى 5، لكل منها url عام وname وmime اختياريان). يجب أن تحتوي الرسالة على نص أو مرفق واحد على الأقل.
• message.id: معرّف الرسالة في نظامك. مطلوب عندما لا ترسل طابعًا زمنيًا (انظر أدناه).

التوقيع

أضف الترويسة X-Resool-Signature: sha256=HEX، حيث HEX هو HMAC-SHA256 لنص الطلب كما هو، بمفتاح سر التوقيع.

لحماية إضافية، أرسل أيضًا X-Resool-Timestamp (ثوانٍ يونكس) ووقّع على TIMESTAMP.BODY بدلًا من نص الطلب وحده. تُرفض الطلبات التي يزيد عمر طابعها الزمني على 5 دقائق. وبدون طابع زمني يجب أن تحمل كل رسالة عميل message.id خاصًا بها، حتى لا ينشئ الطلب المعاد إرساله رسالة مكررة.

تعرض صفحة القناة مثال curl جاهزًا للتشغيل تحت طريقة العمل › أرسل لنا رسالة عميل.

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

مع كل رد يرسله موظف (أو وكيل ذكاء اصطناعي أو سير عمل)، يرسل Resool طلب JSON إلى عنوان webhook للردود:

{
  "event": "message.created",
  "channel": { "id": "…", "name": "…", "flavor": "messaging" },
  "conversationId": "…",
  "contact": { "id": "cust-1" },
  "message": { "id": "<uuid>", "text": "Hi Nora", "attachments": [{ "name": "…", "mime": "…", "url": "…" }] }
}

• الترويسات: X-Resool-Event وX-Resool-Timestamp وX-Resool-Signature. تحقق من التوقيع بالطريقة نفسها، على TIMESTAMP.BODY.
• contact.id هو المعرّف الذي أرسلته، فتعرف لمن تُسلّم الرد.
• إذا فشل التسليم، يعيد Resool المحاولة بالقيمة نفسها لـ message.id. استخدمها لتجاهل التكرار.

#الإبلاغ عن التسليم (اختياري)

لإظهار حالة التسليم في صندوق الوارد، أرسل حالة إلى عنوان الاستقبال موقّعة بالطريقة نفسها:

{ "event": "status", "messageId": "<message.id we sent>", "status": "delivered" }

قيمة status هي delivered أو read أو failed. ومع failed يمكنك إضافة error (حتى 300 حرف).

#كيفية إعداد القناة المخصصة

افتح الإعدادات › القنوات واضغط إدارة على القناة. يعرض تبويب الإعدادات:

• اسم القناة.
• عنوان الاستقبال: حيث يرسل نظامك رسائل العملاء والحالات.
• سر التوقيع: مخفي لأمانك. اضغط توليد سر جديد إن فقدته.
• عنوان webhook للردود ونوع القناة: غيّرهما واحفظ من شريط الحفظ.
• طريقة العمل: قواعد التوقيع وأمثلة قابلة للنسخ لـ أرسل لنا رسالة عميل وما نرسله إليك مع كل رد وأبلغ عن التسليم (اختياري).

مكان لقطة الشاشة

الإعدادات › القنوات › (القناة المخصصة) › الإعدادات

تبويب الإعدادات وفيه عنوان الاستقبال مع زر النسخ، وسر التوقيع مع زر «توليد سر جديد»، وحقلا عنوان webhook للردود ونوع القناة، وقسم «طريقة العمل» بالأمثلة البرمجية الثلاثة.

الملف: screenshots/ar/custom-channel-configuration.png

#توليد سر توقيع جديد

1. اضغط توليد سر جديد.
2. أكّد في مربع توليد سر توقيع جديد؟.
3. انسخ السر الجديد. يتوقف السر القديم فورًا، لذلك حدّث نظامك أولًا وإلا ستُرفض رسائله.

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

#ملاحظات وقيود

• حتى 5 مرفقات لكل رسالة واردة، يُرسل كل منها كعنوان http(s) عام.
• نص الرسالة حتى 4,096 حرفًا.
• تُرفض الطلبات ذات الطابع الزمني الأقدم من 5 دقائق.
• يقبل عنوان الاستقبال حتى 600 طلب في الدقيقة لكل قناة.
• بدون عنوان webhook للردود، تُعلَّم الردود كفاشلة.

#الأسئلة الشائعة وحل المشكلات

#يرد Resool على طلبي بالرمز 403

التوقيع غير مطابق، أو الطابع الزمني يختلف بأكثر من 5 دقائق.

ما يمكنك فعله:

• وقّع على البايتات نفسها التي ترسلها، فإعادة تحويل JSON إلى نص بعد التوقيع تغيّر نص الطلب.
• إذا أرسلت X-Resool-Timestamp، فوقّع على TIMESTAMP.BODY (مع النقطة) وأبقِ ساعة خادمك متزامنة.
• تأكد أنك تستخدم السر الحالي، وليس سرًا استُبدل عبر توليد سر جديد.

#يرد Resool على طلبي بالرمز 400

نص الطلب لا يطابق الصيغة. تأكد أن event قيمته message أو status، وأن contact.id موجود، وأن الرسالة فيها نص أو مرفق، وأن message.id موجود عندما لا ترسل طابعًا زمنيًا.

#يرد Resool على طلبي بالرمز 404

عنوان الاستقبال غير صحيح، أو القناة محذوفة أو متوقفة. انسخ عنوان الاستقبال مرة أخرى من صفحة القناة.

#تظهر الردود كفاشلة في صندوق الوارد

ما يمكنك فعله:

• أضف عنوان webhook للردود في تبويب الإعدادات للقناة.
• تأكد أن عنوانك عام ويستخدم HTTPS ويرد بحالة نجاح.
• إذا كان نظامك يبلغ عن حالات failed، فراجع قيمة error التي ترسلها.

#هل يمكنني استخدام القناة المخصصة مع مزود رسائل نصية؟

نعم. اختر نوع القناة رسائل نصية، واجعل webhooks مزود الرسائل تحوّل الرسائل الواردة إلى عنوان الاستقبال، وأرسل الردود عبر واجهة المزود البرمجية من webhook الردود. وإذا كنت تستخدم Twilio، فقناة Twilio SMS المدمجة أسهل.

#ما التالي؟

• واجهة المطورين البرمجية
• Webhooks
• إعدادات القناة: التوجيه والإسناد التلقائي واستبيانات الرضا
• البدء السريع مع Twilio SMS