فرم‌ها و وب‌هوک فرم

فرم‌های ایلاچت برای جمع‌آوری ساختاریافته اطلاعات در دل گفت‌وگو طراحی شده‌اند؛ از ثبت درخواست مشاوره و دریافت اطلاعات تماس تا استخدام، ارزیابی، پشتیبانی و فرایندهای چندمرحله‌ای. یک فرم را یک بار در پنل می‌سازید و می‌توانید آن را در ویجت سایت، iframe، تلگرام، پیام‌رسان بله و API استفاده کنید.

در ویجت سایت و iframe، فرم می‌تواند به دو شکل نمایش داده شود:

• فرم کلاسیک: فیلدها به‌صورت یک فرم یکپارچه نمایش داده می‌شوند و کاربر آن‌ها را در یک نما تکمیل می‌کند.
• فرم گفت‌گومحور: سؤال‌ها در جریان مکالمه و به‌صورت مرحله‌ای از کاربر پرسیده می‌شوند.

در تلگرام، بله و API فقط تجربه گفت‌گومحور در دسترس است. این مدل به‌جای نمایش یک فرم طولانی، اطلاعات را در گام‌های کوتاه می‌گیرد و برای هر سؤال می‌تواند راهنمای متناسب ارائه کند.

برای آشنایی با کاربردها و اصول طراحی این تجربه، صفحه فرم‌های هوشمند و گفت‌گومحور ایلاچت را ببینید.

ساخت فرم در پنل ایلاچت

1. وارد پنل ایلاچت شوید.
2. از منوی اصلی «فرم‌ها» را انتخاب کنید.
3. روی «ساخت فرم» بزنید.
4. نام داخلی فرم را وارد کنید تا بعداً بتوانید آن را در پنل پیدا کنید.
5. عنوان، توضیحات و متن دکمه ارسال را تنظیم کنید.
6. فیلدهای موردنیاز را اضافه و ترتیب آن‌ها را با کشیدن دستگیره هر فیلد مشخص کنید.
7. پیام موفقیت، دکمه اختیاری، کانال‌ها و نحوه نمایش را تنظیم کنید.
8. پیش‌نمایش فرم را بررسی و فرم را ذخیره کنید.

نام فرم برای مدیریت در پنل است؛ عنوان و توضیحات داخل فرم به کاربر نمایش داده می‌شوند. توضیح کوتاه و روشن بنویسید و مشخص کنید چرا اطلاعات خواسته می‌شوند و پس از ثبت چه اتفاقی می‌افتد.

فیلدهای فرم

از «افزودن فیلد» می‌توانید فیلد جدید بسازید. انواع فعلی عبارت‌اند از:

برای هر فیلد عنوان واضحی انتخاب کنید و فقط فیلدهایی را اجباری کنید که بدون آن‌ها ادامه فرایند ممکن نیست. تنظیمات پیشرفته بسته به نوع فیلد می‌توانند شامل متن راهنما، placeholder، عبارت پرسش گفت‌گومحور، اعتبارسنجی، حداقل و حداکثر عدد یا گزینه‌های انتخابی باشند.

ترتیب فیلدها روی تجربه کاربر اثر مستقیم دارد. ابتدا سؤال‌های ساده و کم‌حساسیت را بپرسید، سپس به اطلاعات تخصصی یا تماس برسید. در حالت گفت‌گومحور نیز همین ترتیب مبنای پرسش‌هاست.

افزودن مقدار به مخاطب

برای بعضی فیلدها گزینه «به مخاطبین افزوده شود؟» در دسترس است. با فعال‌کردن آن می‌توانید پاسخ را به یکی از فیلدهای مخاطب متصل کنید تا اطلاعاتی مانند نام، ایمیل یا شماره همراه در پرونده مخاطب به‌روز شوند.

این قابلیت برای text، email، tel، number و select قابل استفاده است. فیلد مقصد را دقیق انتخاب کنید؛ داده‌ای که یک بار روی مخاطب ذخیره شده است با ریست فرم به‌صورت خودکار حذف یا به مقدار قبلی بازگردانده نمی‌شود.

انتخاب کانال و نحوه نمایش

در بخش «پلتفرم‌های نمایش فرم» مشخص کنید فرم در کدام کانال‌ها فعال باشد. تنظیمات هر کانال مستقل است و می‌توانید یک فرم را در چند کانال با رفتارهای متفاوت منتشر کنید.

تنظیمات قابل مشاهده در پنل، بسته به کانال، شامل این موارد هستند:

• پاسخ به فرم اجباری باشد؟ کاربر برای ادامه مسیر مکالمه باید فرم را پاسخ دهد.
• نوع نمایش: نمایش یکپارچه فرم یا پرسش در گفت‌وگو.
• تأیید نهایی: پس از تکمیل اطلاعات، پاسخ‌ها برای تأیید نهایی به کاربر نشان داده شوند.
• زمان نمایش: زمان مناسب نمایش فرم در جریان مکالمه؛ برای نمونه ابتدای شروع مکالمه یا حالت هوشمند.
• عبارت فعال‌سازی (Trigger): توضیحی برای اینکه فرم در چه موقعیتی نمایش داده شود؛ مانند زمانی که کاربر قصد ثبت بازخورد یا درخواست مشاوره دارد.
• حداکثر تعداد نمایش در یک مکالمه: برای جلوگیری از تکرار آزاردهنده؛ مقدار 0 به معنی بدون محدودیت است.

در حالت هوشمند، عبارت فعال‌سازی را به‌صورت یک هدف روشن بنویسید، نه یک کلمه مبهم. برای مثال: «این فرم فقط وقتی نمایش داده شود که کاربر درخواست تماس با واحد فروش یا مشاوره خرید دارد.»

طراحی یک فرم مؤثر

پیش از ساخت فیلدها، خروجی موردنیاز تیم را مشخص کنید. هر سؤال باید برای تصمیم بعدی یا پیگیری درخواست کاربرد داشته باشد.

1. اطلاعات «لازم برای اقدام» را از اطلاعات صرفاً جالب جدا کنید.
2. تعداد فیلدها را تا حد ممکن کم نگه دارید.
3. عنوان هر فیلد را با زبان کاربر بنویسید.
4. برای قالب‌های خاص مانند شماره موبایل یا کد ملی، نمونه و راهنما بدهید.
5. پیش از دریافت اطلاعات حساس، دلیل درخواست را توضیح دهید.
6. پیام موفقیت را طوری بنویسید که نتیجه ثبت و قدم بعدی مشخص باشد.
7. فرم را در موبایل و همه کانال‌های فعال آزمایش کنید.

پیام موفقیت و دکمه نهایی

در بخش «پیام موفقیت»، متنی را تعیین کنید که پس از تکمیل فرم نمایش داده شود. می‌توانید یک دکمه اختیاری نیز با عنوان و نشانی مقصد بسازید؛ برای مثال «مشاهده نتیجه»، «بازگشت به صفحه اصلی» یا «پیگیری درخواست».

اگر پاسخ وب‌هوک پردازش نشود، همین پیام و دکمه به‌عنوان نتیجه عادی فرم استفاده می‌شوند. نشانی دکمه باید URL معتبر باشد.

وب‌هوک فرم چیست؟

وب‌هوک فرم یک درخواست POST است که هنگام ارسال فرم به URL تعیین‌شده شما فرستاده می‌شود. سرویس مقصد می‌تواند داده‌ها را در CRM، سیستم تیکت، اتوماسیون داخلی یا پایگاه داده ثبت کند.

در حالت پیشرفته، سرویس شما می‌تواند در پاسخ وب‌هوک:

• پیام و دکمه نهایی را تغییر دهد؛
• پیام وضعیت مرحله جاری را نمایش دهد؛
• عنوان، توضیحات و متن دکمه ارسال فرم را تغییر دهد؛
• فرم را کامل کند یا برای مرحله بعد باز نگه دارد؛
• یک فیلد قبلی را دوباره قابل‌ویرایش کند؛
• فیلدهای جدیدی برای مرحله بعد بسازد؛
• دکمه ریست فرم را پیکربندی کند.

فعال‌کردن وب‌هوک

1. در تنظیمات فرم، بخش «وب‌هوک (اختیاری)» را باز کنید.
2. URL عمومی و مبتنی بر HTTPS سرویس خود را وارد کنید.
3. اگر فقط می‌خواهید داده فرم به سرویس شما ارسال شود، پردازش پاسخ وب‌هوک را غیرفعال بگذارید.
4. اگر پاسخ سرویس باید فرم، پیام موفقیت یا مرحله بعد را کنترل کند، گزینه استفاده از پاسخ وب‌هوک را فعال کنید.
5. فرم را با داده آزمایشی ارسال و لاگ سرویس مقصد را بررسی کنید.

ارسال درخواست و پردازش پاسخ دو تنظیم جدا هستند:

• اگر URL معتبر باشد، درخواست وب‌هوک ارسال می‌شود.
• با use_response=true، پاسخ معتبر سرویس روی فرم اعمال می‌شود.
• با use_response=false، بدنه پاسخ اثری روی فرم ندارد و فرم با رفتار عادی تکمیل می‌شود؛ حتی اگر پاسخ شامل status: "success" باشد.

مشخصات درخواست وب‌هوک

سرویس شما باید در کمتر از ۱۰ ثانیه پاسخ دهد. عملیات سنگین را پس از اعتبارسنجی و ثبت اولیه به صف پردازش پس‌زمینه منتقل کنید.

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

{
  "bot_id": 123,
  "conversation_id": "conversation-id",
  "form_message_id": "form-message-id",
  "form_data": {
    "name": {
      "id": "name",
      "value": "علی محمدی",
      "type": "text",
      "title": "نام و نام خانوادگی"
    },
    "plan": {
      "id": "plan",
      "value": {
        "id": "pro",
        "name": "حرفه‌ای"
      },
      "type": "select",
      "title": "پلن موردنظر"
    }
  }
}

form_message_id شناسه تعریف فرم در پنل نیست. در فرم چندمرحله‌ای، این مقدار در ارسال‌های بعدی همان فرم ثابت می‌ماند و form_data در هر مرحله تمام فیلدهای فعلی، از جمله پاسخ مراحل قبلی، را دوباره می‌فرستد. مقدار فیلد اختیاری بدون پاسخ می‌تواند null باشد.

ساختار form_data

کلید هر عضو form_data همان ID فیلد است و مقدار آن ساختار زیر را دارد:

{
  "id": "field-id",
  "value": "submitted-value",
  "type": "text",
  "title": "عنوان فیلد"
}

مقدار فیلدهای متنی و عددی

در text، email، tel، textarea و number، مقدار معمولاً string، number یا null است.

{
  "id": "email",
  "value": "user@example.com",
  "type": "email",
  "title": "ایمیل"
}

مقدار فیلد انتخابی

{
  "id": "plan",
  "value": {
    "id": "pro",
    "name": "حرفه‌ای"
  },
  "type": "select",
  "title": "انتخاب پلن"
}

مقدار فیلد فایل

{
  "id": "attachment",
  "value": {
    "url": "https://example.com/files/document.pdf",
    "name": "document.pdf",
    "size_byte": 102400
  },
  "type": "file",
  "title": "فایل پیوست"
}

پردازش پاسخ وب‌هوک

برای اعمال پاسخ روی فرم، همه شرط‌های زیر باید برقرار باشند:

1. وضعیت HTTP دقیقاً 200 باشد.
2. گزینه استفاده از پاسخ وب‌هوک فعال باشد.
3. بدنه پاسخ JSON معتبر باشد.
4. مقدار status دقیقاً success باشد.

نمونه کامل پاسخ

{
  "status": "success",
  "message": "اطلاعات با موفقیت ثبت شد",
  "button_title": "مشاهده نتیجه",
  "button_url": "https://example.com/result",
  "status_message": "اطلاعات بیشتری موردنیاز است",
  "form_submit_button_text": "ارسال اطلاعات تکمیلی",
  "form_title": "اطلاعات تکمیلی",
  "form_description": "لطفاً اطلاعات زیر را تکمیل کنید",
  "form_reset": {
    "enabled": true,
    "button_text": "شروع مجدد فرم",
    "description": "پاک‌کردن اطلاعات واردشده و شروع فرم از ابتدا"
  },
  "form_completed": false,
  "fields": [
    {
      "id": "national_code",
      "type": "text",
      "title": "کد ملی",
      "required": true,
      "edit": true
    }
  ]
}

اگر status وجود نداشته باشد یا مقدار دیگری مانند error داشته باشد، هیچ‌یک از تغییرات پاسخ روی فرم اعمال نمی‌شوند.

پیام‌ها و دکمه‌ها در پاسخ

message و دکمه نهایی فقط پس از کامل‌شدن فرم نمایش داده می‌شوند. برای نمایش دکمه، عنوان و URL معتبر لازم‌اند.

{
  "status": "success",
  "message": "ثبت اطلاعات با موفقیت انجام شد",
  "button_title": "مشاهده سفارش",
  "button_url": "https://example.com/orders/123"
}

status_message برای خطا، هشدار یا توضیح مرحله بعد است. اگر در پاسخ بعدی ارسال نشود، پیام وضعیت قبلی پاک می‌شود.

{
  "status": "success",
  "status_message": "شماره موبایل واردشده معتبر نیست",
  "form_submit_button_text": "اصلاح و ارسال مجدد"
}

کلید صحیح متن دکمه ارسال form_submit_button_text است؛ کلید submit_button_text معتبر نیست.

کنترل کامل‌شدن فرم

برای تکمیل فرم:

{
  "status": "success",
  "form_completed": true
}

برای باز نگه‌داشتن فرم و دریافت مرحله بعد:

{
  "status": "success",
  "form_completed": false
}

form_completed باید Boolean واقعی باشد؛ رشته "false" معتبر نیست. اگر این کلید ارسال نشود، مقدار پیش‌فرض true است. بااین‌حال، افزودن فیلد جدید یا برگرداندن فیلد قبلی با edit: true در همان پاسخ نیز فرم را باز نگه می‌دارد.

فرم فقط زمانی کامل می‌شود که:

1. form_completed برابر true باشد یا ارسال نشده باشد؛
2. فیلد جدیدی در پاسخ ایجاد نشده باشد؛
3. فیلد قبلی با edit: true برگردانده نشده باشد.

برای مرحله‌های بعدی همیشه form_completed: false را صریح ارسال کنید و فقط به وجود فیلد جدید تکیه نکنید.

ویرایش فیلد قبلی

برای قابل‌ویرایش‌کردن یک فیلد موجود، ID آن را با edit: true برگردانید:

{
  "status": "success",
  "form_completed": false,
  "fields": [
    {
      "id": "email",
      "edit": true
    }
  ]
}

فیلد مشخص‌شده قابل‌ویرایش و سایر فیلدهای قبلی غیرقابل‌ویرایش می‌شوند؛ مقدارهای ثبت‌شده حفظ خواهند شد. برای فیلد موجود فقط id و edit پردازش می‌شوند و مشخصاتی مانند type، title، value، required و placeholder تغییر نمی‌کنند.

افزودن فیلد جدید

اگر ID در فیلدهای فعلی وجود نداشته باشد، فیلد جدید ساخته می‌شود. id، type و title الزامی‌اند. مقدار پیش‌فرض edit برای فیلد جدید true است و value برگشتی نادیده گرفته می‌شود.

{
  "status": "success",
  "status_message": "برای ادامه کد ملی خود را وارد کنید",
  "form_submit_button_text": "ثبت کد ملی",
  "form_title": "احراز هویت",
  "form_description": "کد ملی باید ۱۰ رقم باشد",
  "form_completed": false,
  "fields": [
    {
      "id": "national_code",
      "type": "text",
      "title": "کد ملی",
      "required": true,
      "placeholder": "کد ملی ۱۰ رقمی",
      "validation_regex": "^[0-9]{10}$"
    }
  ]
}

ID همه فیلدها باید یکتا باشد.

ساختار فیلدهای جدید

نوع‌های مجاز عبارت‌اند از text، email، number، textarea، select، file و tel.

{
  "id": "field-id",
  "type": "text",
  "title": "عنوان فیلد",
  "required": false,
  "edit": true
}

نمونه فیلد متنی

{
  "id": "name",
  "type": "text",
  "title": "نام",
  "required": true,
  "placeholder": "نام خود را وارد کنید",
  "engagement_text": "نام شما چیست؟",
  "engagement_help": "نام و نام خانوادگی را وارد کنید",
  "validation_regex": "^[A-Za-zآ-ی ]+$",
  "set_contact": true,
  "contact_field_id": "name"
}

نمونه شماره موبایل

{
  "id": "phone",
  "type": "tel",
  "title": "شماره موبایل",
  "required": true,
  "placeholder": "09123456789",
  "validation_regex": "^09[0-9]{9}$",
  "set_contact": true,
  "contact_field_id": "phone"
}

نمونه فیلد انتخابی

{
  "id": "plan",
  "type": "select",
  "title": "انتخاب پلن",
  "required": true,
  "engagement_text": "یکی از پلن‌ها را انتخاب کنید",
  "select_options": [
    {
      "id": "free",
      "name": "رایگان"
    },
    {
      "id": "pro",
      "name": "حرفه‌ای"
    }
  ]
}

select_options باید آرایه‌ای با حداقل یک گزینه باشد. هر گزینه به id و name رشته‌ای نیاز دارد و طول نام حداکثر ۲۵۵ کاراکتر است.

نمونه فیلد فایل

{
  "id": "document",
  "type": "file",
  "title": "مدرک",
  "required": true
}

اعتبارسنجی منظم و گروهی فیلدها

برای validation_regex فقط خود الگو را بفرستید و delimiterهایی مانند / اضافه نکنید:

{
  "validation_regex": "^[0-9]{10}$"
}

همه تغییرات fields یکجا اعتبارسنجی می‌شوند. اگر حتی یک فیلد نامعتبر باشد، هیچ‌یک از تغییرات فیلدها اعمال نمی‌شوند و فیلدهای قبلی بدون تغییر می‌مانند؛ اما سایر بخش‌های معتبر پاسخ مانند status_message یا تنظیمات فرم همچنان می‌توانند اعمال شوند.

دکمه ریست فرم

برای تنظیم دکمه ریست از form_reset استفاده کنید:

{
  "status": "success",
  "form_reset": {
    "enabled": true,
    "button_text": "شروع مجدد فرم",
    "description": "پاک‌کردن اطلاعات واردشده و شروع فرم از ابتدا"
  }
}

حتی با enabled: false نیز button_text باید ارسال شود. این تنظیم فقط دکمه را پیکربندی می‌کند؛ عملیات ریست زمانی اجرا می‌شود که کاربر دکمه را بزند.

در پیاده‌سازی فعلی، اجرای ریست برای فرم‌های سرویس iframe پشتیبانی می‌شود. وقتی کاربر دکمه را می‌زند، درخواست فرم با reset_form=1 ارسال می‌شود. سیستم فرم را با form_id در نسخه فعلی چت‌بات پیدا و تعریف فعلی فیلدها، عنوان و تنظیمات سرویس را دوباره بارگذاری می‌کند. وضعیت تکمیل، داده‌های ارسال‌شده، پاسخ وب‌هوک، پیام وضعیت و اطلاعات بررسی قبلی همان پیام پاک می‌شوند و وب‌هوک در جریان ریست دوباره فراخوانی نمی‌شود.

اگر فرم دیگر در چت‌بات وجود نداشته باشد، پیام فرم از مکالمه حذف می‌شود. اطلاعاتی که قبلاً با set_contact روی مخاطب ثبت شده‌اند و فایل فیزیکی آپلودشده نیز به‌صورت خودکار حذف یا به مقدار قبلی بازگردانده نمی‌شوند.

نمونه فرم چندمرحله‌ای

این پاسخ یک مرحله جدید برای دریافت کد ملی می‌سازد:

{
  "status": "success",
  "status_message": "اطلاعات تکمیلی موردنیاز است",
  "form_submit_button_text": "ارسال مرحله بعد",
  "form_title": "مرحله دوم",
  "form_description": "لطفاً کد ملی خود را وارد کنید",
  "form_reset": {
    "enabled": true,
    "button_text": "شروع مجدد فرم"
  },
  "form_completed": false,
  "fields": [
    {
      "id": "national_code",
      "type": "text",
      "title": "کد ملی",
      "required": true,
      "validation_regex": "^[0-9]{10}$"
    }
  ]
}

در ارسال مرحله دوم، form_data هم کد ملی و هم همه پاسخ‌های مرحله اول را در بر خواهد داشت.

رفتار خطاها

در خطای ارتباطی یا پاسخ نامعتبر، ارسال مجدد خودکار انجام نمی‌شود. حداکثر ۵۰۰ کاراکتر ابتدایی پاسخ وب‌هوک برای عیب‌یابی ذخیره می‌شود؛ ذخیره‌شدن پاسخ به معنی اعمال‌شدن آن نیست.

امنیت وب‌هوک

در درخواست فعلی هدر امضا، secret یا timestamp اختصاصی ارسال نمی‌شود. بنابراین:

• فقط از URL مبتنی بر HTTPS استفاده کنید.
• بهتر است مسیر وب‌هوک شامل یک توکن تصادفی و غیرقابل‌حدس باشد.
• داده ورودی را در سرویس مقصد اعتبارسنجی کنید و صرفاً به bot_id یا conversation_id اعتماد نکنید.
• URL وب‌هوک و توکن مسیر را در مخزن عمومی یا کد سمت مرورگر قرار ندهید.
• اطلاعات محرمانه را در message، status_message یا متن‌های قابل نمایش برنگردانید.
• پردازش را idempotent طراحی کنید تا timeout یا ارسال دستی دوباره، عملیات مالی یا ثبت داده را تکرار نکند.
• دسترسی سرویس مقصد به CRM یا پایگاه داده را به حداقل مجوز لازم محدود کنید.

چک‌لیست پیاده‌سازی

1. URL وب‌هوک عمومی، HTTPS و غیرقابل‌حدس باشد.
2. درخواست POST با JSON را بپذیرید.
3. همه داده‌های form_data را اعتبارسنجی کنید.
4. در کمتر از ۱۰ ثانیه پاسخ دهید.
5. برای اعمال پاسخ، HTTP 200، JSON معتبر، use_response=true و status: "success" لازم‌اند.
6. form_completed، edit و form_reset.enabled باید Boolean واقعی باشند.
7. برای مرحله بعد form_completed: false را صریح ارسال کنید.
8. برای فیلد قبلی فقط id و edit بفرستید.
9. برای فیلد جدید حداقل id، type و title را بفرستید.
10. ID فیلدها یکتا باشد.
11. برای متن دکمه ارسال فقط form_submit_button_text را استفاده کنید.
12. خطاها را در سرویس مقصد ثبت و پایش کنید؛ ارسال مجدد خودکار وجود ندارد.
13. فرم را در تمام کانال‌های فعال با داده واقعی‌نما ولی غیرحساس آزمایش کنید.