تخصيص النموذج

خصّص مظهر النموذج والتسميات والألوان باستخدام واجهة الوكيل البرمجية.

الحصول على تفاصيل النموذج

النقطة الطرفية: GET /api/agent/form

الرؤوس:

Authorization: Bearer sr_live_your_api_key

الاستجابة:

{
  "form": {
    "id": "uuid",
    "title": "Get Support",
    "description": "Fill in the following details...",
    "background_color": "f9f9fb",
    "button_color": "3f3ea2",
    "text_color": "000000",
    "logo_url": "https://...",
    "button_text": "إرسال",
    "field_name_label": "الاسم",
    "field_email_label": "البريد الإلكتروني",
    "field_message_label": "الرسالة",
    "field_name_placeholder": "أنتr name",
    "field_email_placeholder": "your@email.com",
    "field_message_placeholder": "Write something nice"
  },
  "embed": {
    "direct_url": "https://supportretriever.com/form/uuid",
    "iframe": "<iframe src=\"...\"></iframe>",
    "html_link": {
      "default": "<a href=\"...\">Contact Support</a>",
      "with_styles": "<a href=\"...\" style=\"...\">Contact Support</a>"
    }
  }
}

تحديث النموذج

النقطة الطرفية: PUT /api/agent/form

الرؤوس:

Authorization: Bearer sr_live_your_api_key
Content-Type: application/json

جسم الطلب (كل الحقول اختيارية):

{
  "title": "تواصل معنا",
  "description": "We'd love to hear from you!",
  "background_color": "ffffff",
  "button_color": "007bff",
  "text_color": "333333",
  "logo_url": "https://example.com/logo.png",
  "button_text": "إرسال الرسالة",
  "field_name_label": "أنتr الاسم",
  "field_email_label": "أنتr البريد الإلكتروني",
  "field_message_label": "أنتr الرسالة",
  "field_name_placeholder": "John Doe",
  "field_email_placeholder": "john@example.com",
  "field_message_placeholder": "How can we help?"
}

الاستجابة:

{
  "success": true,
  "form": {
    // Updated form object
  }
}

الحقول القابلة للتخصيص

إعدادات المرئيات

Field	Type	الوصف	Example
`title`	string	عنوان النموذج (حد أقصى 100 حرف)	"تواصل معنا"
`description`	string	نص وصف النموذج	"We'd love to hear from you!"
`background_color`	string	لون hex (6 أحرف، بدون #)	"ffffff"
`button_color`	string	لون hex لزر الإرسال	"007bff"
`text_color`	string	لون hex للنص	"333333"
`logo_url`	string	رابط صورة الشعار	"https://example.com/logo.png"
`button_text`	string	نص زر الإرسال	"إرسال الرسالة"

تسميات الحقول

Field	الوصف	Example
`field_name_label`	تسمية حقل الاسم	"أنتr الاسم"
`field_email_label`	تسمية حقل البريد	"أنتr البريد الإلكتروني"
`field_message_label`	تسمية حقل الرسالة	"أنتr الرسالة"

النصوص التوضيحية للحقول

Field	الوصف	Example
`field_name_placeholder`	النص التوضيحي لحقل الاسم	"John Doe"
`field_email_placeholder`	النص التوضيحي لحقل البريد	"john@example.com"
`field_message_placeholder`	النص التوضيحي لحقل الرسالة	"How can we help?"

الحقول المحمية

هذه الحقول لا يمكن تغييرها عبر واجهة الوكيل (تُتجاهل بصمت):

recipient_email - البريد الذي تُرسل إليه الإرسالات
custom_email_domain - إعدادات النطاق المخصص
custom_email_username - اسم المستخدم للبريد المخصص
userID - مالك النموذج
id - معرّف النموذج
created_at - الطابع الزمني للإنشاء

لماذا محمية؟

recipient_email يمنع اختطاف رسائل العملاء
الحقول الأخرى managed من النظام

تنسيق الألوان

الألوان بصيغة hex بدون رمز #:

✅ صحيح: "ffffff", "3f3ea2", "000000"
❌ خطأ: "#ffffff", "rgb(255,255,255)", "white"

التحديثات الجزئية

يمكنك تحديث الحقول التي تريد تغييرها فقط:

{
  "title": "New العنوان",
  "button_color": "ff0000"
}

سيُحدَّث فقط title و button_color؛ بقية الحقول تبقى دون تغيير.

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

تباين الألوان

استخدم خلفيات فاتحة (ffffff, f9f9fb) مع نص غامق (000000, 333333)
تأكد من تباين لون الزر جيداً مع الخلفية
اختبر القراءة على أجهزة مختلفة

طول العنوان

أبقِ العناوين قصيرة (أقل من 50 حرفاً)
استخدم لغة موجهة للإجراء ("تواصل معنا", "Get Support")

الوصف

أبقِ الوصف موجزاً (جملة أو جملتين)
اشرح ما يحدث بعد الإرسال

نص الزر

استخدم أفعالاً واضحة ("إرسال", "Submit", "تواصل معنا")
أبقِه قصيراً (1–3 كلمات)

أمثلة

تحديث بسيط (ألوان فقط)

{
  "background_color": "ffffff",
  "button_color": "007bff",
  "text_color": "333333"
}

تحديث علامة تجارية كاملة

{
  "title": "Contact Our Team",
  "description": "Have a question? We're here to help!",
  "background_color": "f8f9fa",
  "button_color": "28a745",
  "text_color": "212529",
  "logo_url": "https://example.com/logo.png",
  "button_text": "إرسال الرسالة",
  "field_name_label": "Full الاسم",
  "field_email_label": "عنوان البريد الإلكتروني",
  "field_message_label": "أنتr الرسالة",
  "field_name_placeholder": "Enter your name",
  "field_email_placeholder": "you@example.com",
  "field_message_placeholder": "Tell us how we can help..."
}