واجهة الرسائل وتجاربها

هذا الدليل مخصص للشركاء الذين ينشئون تجارب للمستخدم النهائي: ما يراه المستخدمون في تطبيق MorisBox، وأي واجهات API / حمولات يجب استخدامها للرسائل الثرية والقوائم والتدفقات متعددة المراحل.

هذا ليس نظام تصميم لموقع الوثائق.

ما يراه المستخدمون

في مساحة الشريك ضمن تطبيق الهاتف / Application Client:

المنطقة	الهدف
الرسائل	قائمة المركز الخاصة بك: الإشعارات والوسائط والنشرات وبطاقات التدفق (الأحدث أولًا)
النماذج	التدفقات التفاعلية المتاحة
المحادثات	محادثات الدعم التي يفتحها المستخدم
الروبوتات	روبوتاتك المتاحة في in-app

تظهر عمليات الإرسال الآلية للشركاء في الرسائل. لا تضع محتوى الحملات في محادثات الدعم.

المكونات الأساسية (أنواع المحتوى)

استخدم POST /api/v1/messages مع content_type (وحقول الوسائط / الرابط / HTML). المرجع الكامل: الوسائط وأنواع المحتوى، الرسائل.

نص

إشعار بسيط أو تسمية توضيحية.

{
  "phone": "+228XXXXXXXX",
  "content_type": "text",
  "body": "Votre dossier a été mis à jour.",
  "priority": "notification"
}

واجهة المستخدم: صف في القائمة / فقاعة بسيطة.

صورة

{
  "phone": "+228XXXXXXXX",
  "content_type": "image",
  "body": "Photo de l’agence",
  "media_url": "https://cdn.example.com/agence.jpg",
  "media_filename": "agence.jpg"
}

واجهة المستخدم: معاينة للصورة؛ اضغط لفتحها بالحجم الكامل.

مستند / صوت / فيديو

{
  "content_type": "document",
  "body": "Guide d’affiliation",
  "media_url": "https://cdn.example.com/guide.pdf",
  "media_filename": "guide.pdf"
}

النوع	واجهة المستخدم
`document`	صف ملف (الاسم والنوع والفتح)
`audio`	صف صوتي؛ فتح / تشغيل
`video`	بطاقة فيديو؛ فتح

رابط CTA

بطاقة ثرية تضم عنوانًا ووصفًا وزرًا وصورة اختيارية.

{
  "content_type": "link",
  "body": "Consultez votre espace assuré.",
  "link_url": "https://morisbox.com",
  "link_title": "Espace assuré SEED",
  "link_description": "Cotisations, demandes et documents.",
  "link_label": "Ouvrir le portail",
  "link_image_url": "https://cdn.example.com/cover.jpg"
}

واجهة المستخدم: بطاقة + زر أساسي؛ يفتح عنوان URL.

نشرة HTML إخبارية

تخطيط ثري (صورة وفيديو وHTML). يفتح في ملء الشاشة عندما يضغط المستخدم صف المركز (من دون عرض معاينة صغيرة أولًا).

{
  "content_type": "html",
  "subject": "SEED Actu · Juillet",
  "html": "<div><h1>Bonjour</h1><img src=\"https://…/photo.jpg\" style=\"max-width:100%\"/><p>…</p></div>"
}

واجهة المستخدم: عنوان القائمة = subject؛ الضغط ← قارئ HTML كامل.
التفاصيل: نشرات HTML الإخبارية.

دعوة إلى تدفق

نموذج تفاعلي متعدد الشاشات (التسجيل وقائمة الانتظار وما إلى ذلك).

POST /api/v1/bots/{bot_code}/flows/{flow_code}/invite

{ "phone": "+228XXXXXXXX" }

واجهة المستخدم: بطاقة تدفق؛ فتح مشغّل النموذج؛ وعند النهاية تتحول البطاقة نفسها إلى ملخص للقراءة فقط.
التفاصيل: التدفقات التفاعلية.

واجهة محادثة الروبوت (القوائم والمراحل)

عندما يشغّل المستخدم جلسة روبوت، يمكن لبيئة التشغيل عرض:

نوع الحدث / المرحلة	تجربة المستخدم
`message` / `flow_message`	نص في واجهة التدفق/الروبوت
`menu` (button)	قائمة خيارات عمودية
`menu` (list)	قائمة مقسمة إلى أقسام (على نمط قوائم WhatsApp)
`flow_screen` + `form`	نموذج متعدد الحقول (inputs وselect وphone وemail وغيرها)
`flow_screen` + `input` / `select`	حقل واحد أو خيارات
`payment`	تأكيد دفع (stub / مستقبلي)
`flow_completed`	النهاية + ملخص اختياري

أنواع حقول النموذج (شاشات التدفق)

عرّفها في fields_json ضمن مرحلة form:

`type`	عنصر التحكم
`text`	إدخال نص
`phone`	هاتف (يُتحقق منه وفق E.164)
`email`	بريد إلكتروني (يُتحقق منه)
`number`	رقمي
`date`	تاريخ `YYYY-MM-DD`
`boolean`	نعم / لا
`select`	قائمة خيارات (`options: [{id, label}]`)

تحقق على جانب الخادم: التحقق من الحقول.

مثال على تعريف مرحلة نموذج

[
  {
    "key": "full_name",
    "type": "text",
    "label": "Nom complet",
    "required": true,
    "placeholder": "Ex. Ama Koffi"
  },
  {
    "key": "email",
    "type": "email",
    "label": "E-mail",
    "required": false
  },
  {
    "key": "service",
    "type": "select",
    "label": "Service",
    "required": true,
    "options": [
      { "id": "affiliation", "label": "Affiliation" },
      { "id": "pension", "label": "Pension" }
    ]
  }
]

اختيار المكوّن المناسب

الهدف	الاستخدام
تنبيه لمرة واحدة	`text` أو قالب
عرض صورة / PDF	`image` / `document`
توجيه المستخدم إلى بوابتك	CTA من نوع `link`
محتوى شهري ثري شبيه بالبريد الإلكتروني	نشرة `html`
تسجيل / قائمة انتظار متعددة المراحل	دعوة إلى تدفق + مراحل form
قائمة خدمات موجهة	قوائم الروبوت (`local` أو`service`)
دردشة دعم مستمرة	محادثة يبدأها المستخدم (ردود الوكلاء)

الفواصل والبنية في المحتوى الثري

في نشرات HTML الإخبارية، نظّم المحتوى باستخدام:

عناوين (h1-h3) للأقسام
خطوط أفقية (<hr>) أو كتل متباعدة للفصل المرئي
بطاقات (divs ذات حدود) لعناصر CTA
قوائم (ul / ol) للنقاط سهلة التصفح

في التدفقات، استخدم مراحل (شاشات) منفصلة بدلًا من نموذج واحد طويل متى أمكن، لتحسين تجربة الهاتف.

أنماط من البداية إلى النهاية

1. حملة: صورة + رابط

إرسال image مع تسمية توضيحية
إرسال CTA من نوع link إلى «إكمال طلبي»

2. قائمة انتظار الانضمام

POST …/flows/waitlist/invite
يملأ المستخدم نماذج الهوية + التفضيلات
تتحول حالة البطاقة إلى completed مع ملخص

3. نشرة إخبارية مع وسائط

إنشاء HTML باستخدام <img> و<video>
content_type=html + subject
يفتح المستخدم القارئ الكامل من المركز

وثائق API المرتبطة

الموضوع	الصفحة
إرسال الرسائل	الرسائل
أنواع الوسائط	الوسائط وأنواع المحتوى
النشرات الإخبارية	نشرات HTML الإخبارية
التدفقات	التدفقات التفاعلية
الروبوتات	360Bots
مصادقة الروبوت	بيانات اعتماد الروبوتات وخطافات الويب
التحقق	التحقق من الحقول