وب‌سرویس API

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

این API برای ارتباط سروربه‌سرور طراحی شده است. توکن را داخل JavaScript مرورگر، اپلیکیشن قابل مهندسی معکوس، HTML یا مخزن عمومی قرار ندهید. برای آشنایی با کاربردها و راهنمای تصویری، صفحه وب‌سرویس API ایلاچت را ببینید.

فعال‌سازی و دریافت کلید API

1. وارد پنل ایلاچت شوید و چت‌بات موردنظر را انتخاب کنید.
2. وارد «تنظیمات» شوید.
3. بخش «استفاده و انتشار» را باز کنید.
4. گزینه «وب سرویس API» را انتخاب کنید.
5. API را فعال کنید، توکن API را کپی کنید و در صورت نیاز IPهای مجاز را ثبت کنید.

توکن شناسه محرمانه چت‌بات شماست و تمام درخواست‌های دارای آن با دسترسی همان چت‌بات اجرا می‌شوند. آن را فقط در Secret Manager یا متغیر محیطی Backend نگه دارید:

ILACHAT_API_TOKEN=YOUR_BOT_API_TOKEN

آدرس پایه و احراز هویت

https://api.ila.chat/api/bot

درخواست‌ها و پاسخ‌های معمول با JSON مبادله می‌شوند. فقط هنگام آپلود فایل از multipart/form-data استفاده کنید.

api-token: YOUR_BOT_API_TOKEN
Accept: application/json
Content-Type: application/json

احراز هویت از نوع Bearer نیست؛ توکن باید دقیقاً در هدر api-token ارسال شود. پاسخ موفق معمولاً با HTTP 200 و status: "success" برمی‌گردد. در خطا، مقدار status برابر error است؛ همیشه علاوه بر HTTP Status، فیلد status بدنه را هم بررسی کنید.

{
  "status": "error",
  "message": "Error text",
  "code": 400
}

endpointهای فهرستی آبجکت pagination شامل total، current_page و last_page دارند. در پنل می‌توانید IPهای مجاز را نیز ثبت کنید؛ فهرست خالی یعنی درخواست از همه IPها پذیرفته می‌شود و حداکثر ۵ IP یکتا قابل ثبت است.

محدودیت عمومی فعلی API برابر ۷۰ درخواست در هر ۳ دقیقه است. برای 429 و خطاهای موقت 5xx از retry با backoff و jitter استفاده کنید؛ خطاهای اعتبارسنجی را بدون اصلاح درخواست تکرار نکنید.

شروع سریع

۱. بررسی اتصال

curl "https://api.ila.chat/api/bot/settings" \
  -H "api-token: YOUR_BOT_API_TOKEN" \
  -H "Accept: application/json"

{
  "status": "success",
  "bot": {
    "name": "دستیار فروش",
    "avatar": "https://app.ila.chat/storage/example/avatar.png",
    "allow_ips": ["203.0.113.10"]
  }
}

۲. ایجاد گفتگو و ثبت لید

curl -X POST "https://api.ila.chat/api/bot/conversation/new" \
  -H "api-token: YOUR_BOT_API_TOKEN" \
  -H "Accept: application/json"

{
  "status": "success",
  "conversation": { "id": "68af12035d54f40612000001" }
}

مقدار conversation.id را کنار شناسه کاربر یا Session خود ذخیره کنید. سپس در صورت وجود اطلاعات مخاطب، آن‌ها را ثبت کنید:

curl -X PATCH "https://api.ila.chat/api/bot/conversation/68af12035d54f40612000001/leads" \
  -H "api-token: YOUR_BOT_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"key":"name","value":"علی رضایی"},{"key":"user_id","value":"customer-1024"}]}'

{ "status": "success" }

۳. ارسال پیام و نمایش پاسخ

curl -X POST "https://api.ila.chat/api/bot/conversation/68af12035d54f40612000001/message/send" \
  -H "api-token: YOUR_BOT_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"message":"سلام، وضعیت سفارش من چیست؟","temp_id":1001}'

{
  "status": "success",
  "message": {
    "id": "68af12035d54f40612000021",
    "bot": false,
    "message": "سلام، وضعیت سفارش من چیست؟",
    "images": [], "videos": [], "files": [], "voices": [], "links": [],
    "temp_id": "1001", "created_at": "2026-08-27T10:31:00.000000Z", "type": "message"
  },
  "answers": [{
    "id": "68af12035d54f40612000022", "bot": true,
    "message": "برای پیگیری، شماره سفارش را بفرستید.",
    "images": [], "videos": [], "files": [], "voices": [], "links": [],
    "created_at": "2026-08-27T10:31:01.000000Z", "type": "message"
  }],
  "conversation": { "id": "68af12035d54f40612000001", "service": "api", "bot_answers_status": true }
}

answers ممکن است خالی باشد؛ برای نمونه وقتی پاسخ خودکار خاموش است، پردازش بعداً انجام می‌شود یا تعامل بیشتری لازم است. بنابراین دریافت پیام‌های جدید را حتی پس از پاسخ ارسال پیام ادامه دهید.

چرخه گفتگو

1. برای اولین تعامل، یک گفتگو ایجاد کنید.
2. conversation_id را کنار شناسه کاربر یا Session ذخیره کنید.
3. لیدهای شناخته‌شده را ثبت یا به‌روزرسانی کنید.
4. پیام کاربر را بفرستید و پاسخ‌های answers را نمایش دهید.
5. برای پیام‌های بعدی بات یا اپراتور، فهرست پیام‌ها را با after_id یا since بخوانید.
6. در Session بعدی همان کاربر، در صورت مناسب‌بودن سیاست کسب‌وکار، همان گفتگو را ادامه دهید.

مرجع تعاملی API

در این بخش همه درخواست‌های عمومی API، پارامترها، بدنه درخواست و نمونه پاسخ‌های موفق و خطا را می‌بینید. می‌توانید هر درخواست را با توکن خودتان آزمایش کنید.

گفتگوها و لیدها

curl -X GET "https://example.com/settings"

{
  "status": "success",
  "bot": {
    "name": "ربات هوش مصنوعی ایلاچت",
    "avatar": "https://app.ila.chat/storage/bots/1/63970.png",
    "allow_ips": []
  }
}

curl -X GET "https://example.com/conversation/list"

{
  "status": "success",
  "conversations": [
    {
      "id": "674b93a5572af1d61807cb62",
      "service": "api",
      "title": "پیگیری سفارش",
      "bot_start_at": null,
      "bot_answers_status": true,
      "messages_count": 5
    }
  ],
  "pagination": {
    "total": 1,
    "current_page": 1,
    "last_page": 1
  }
}

curl -X POST "https://example.com/conversation/new"

{
  "status": "success",
  "conversation": {
    "id": "6787ca5ced135f1ca50e57e2"
  }
}

curl -X GET "https://example.com/conversation/string/details"

{
  "status": "success",
  "conversation": {
    "id": "67866b145c76ea516202fce3",
    "service": "api",
    "name": "علی رضایی",
    "email": "ali@example.com",
    "phone": "+989121234567",
    "leads": [
      {
        "key": "name",
        "name": "نام و نام خانوادگی",
        "value": "علی رضایی"
      }
    ],
    "title": "پیگیری سفارش",
    "IPs": [
      "203.0.113.10"
    ],
    "bot_start_at": null,
    "bot_answers_status": true
  }
}

curl -X PATCH "https://example.com/conversation/string/leads" \  -H "Content-Type: application/json" \  -d '{    "leads": [      {        "key": "name",        "value": "علی رضایی"      },      {        "key": "mobile",        "value": "+989121234567"      }    ]  }'

{
  "status": "success"
}

پیام‌ها و فایل‌ها

فهرست پیام‌ها در حالت عادی از جدید به قدیم مرتب می‌شود. با after_id یا since، پیام‌ها از قدیم به جدید برمی‌گردند تا مستقیم به انتهای رابط اضافه شوند. این دو پارامتر را هم‌زمان نفرستید. برای polling پایدار، after_id پیشنهاد می‌شود.

curl -X GET "https://example.com/conversation/string/message/list"

{
  "status": "success",
  "messages": [
    {
      "id": "6787cb392b018cb64c0f2075",
      "bot": true,
      "message": "سلام علیکم! چطور می‌توانم به شما کمک کنم؟",
      "images": [],
      "videos": [],
      "files": [],
      "voices": [],
      "links": [],
      "user_id": null,
      "user": [],
      "reply_to_message_id": null,
      "temp_id": null,
      "created_at": "2026-08-27T10:31:01.000000Z",
      "type": "message"
    }
  ],
  "pagination": {
    "total": 1,
    "current_page": 1,
    "last_page": 1
  }
}

curl -X POST "https://example.com/conversation/string/message/send" \  -H "Content-Type: application/json" \  -d '{    "message": "سلام علیکم",    "temp_id": 1001  }'

{
  "status": "success",
  "message": {
    "id": "6787cb382b018cb64c0f2074",
    "bot": false,
    "message": "سلام علیکم",
    "images": [],
    "videos": [],
    "files": [],
    "voices": [],
    "links": [],
    "temp_id": "1001",
    "created_at": "2026-08-27T10:31:00.000000Z",
    "type": "message"
  },
  "answers": [
    {
      "id": "6787cb392b018cb64c0f2075",
      "bot": true,
      "message": "سلام علیکم! چطور می‌توانم به شما کمک کنم؟",
      "images": [],
      "videos": [],
      "files": [],
      "voices": [],
      "links": [],
      "created_at": "2026-08-27T10:31:01.000000Z",
      "type": "message"
    }
  ],
  "conversation": {
    "id": "6787ca5ced135f1ca50e57e2",
    "service": "api",
    "bot_answers_status": true
  }
}

message حداکثر ۱۰٬۰۰۰ نویسه است و اگر فایل نمی‌فرستید اجباری است. در multipart/form-data می‌توانید حداکثر ۵ فایل با اندازه هر فایل تا ۵۰ مگابایت در files[] بفرستید. برای Reply از reply_to_message_id استفاده کنید.

تصویر و ویدیوی کمتر از ۱۰ مگابایت در images یا videos و فایل صوتی کمتر از ۵ مگابایت در voices برمی‌گردد؛ رسانه‌های بزرگ‌تر یا سایر انواع در files قرار می‌گیرند.

همگام‌سازی محصول

با ارسال unique_id پایدار، محصول موجود به‌روزرسانی می‌شود؛ بدون آن ممکن است هر درخواست یک رکورد جدید بسازد. حذف محصول نیز فقط با همین شناسه انجام می‌شود.

curl -X POST "https://example.com/data/sync/product" \  -F name="string"

{
  "status": "success",
  "data": {
    "id": "68af12035d54f40612000100",
    "unique_id": "SKU-1001"
  },
  "update": false
}

نمونه پاسخ ایجاد یا به‌روزرسانی:

{
  "status": "success",
  "data": { "id": "68af12035d54f40612000100", "unique_id": "SKU-1001" },
  "update": false
}

نمونه پاسخ حذف:

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

برای هر محصول موجود حداکثر ۵ به‌روزرسانی در بازه ۲۴ ساعته پذیرفته می‌شود. از ارسال داده بدون تغییر خودداری کنید و فقط اطلاعاتی را بفرستید که برای پاسخ‌گویی چت‌بات لازم‌اند.

نمونه JavaScript سمت سرور

const baseUrl = 'https://api.ila.chat/api/bot';
const token = process.env.ILACHAT_API_TOKEN;

async function ilachat(path, options = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...options,
    headers: {
      'api-token': token,
      Accept: 'application/json',
      ...(options.body instanceof FormData ? {} : { 'Content-Type': 'application/json' }),
      ...options.headers
    }
  });
  const body = await response.json();
  if (!response.ok || body.status !== 'success') {
    throw new Error(body.message || `ILACHAT API error: ${response.status}`);
  }
  return body;
}

const created = await ilachat('/conversation/new', { method: 'POST' });
const sent = await ilachat(`/conversation/${created.conversation.id}/message/send`, {
  method: 'POST', body: JSON.stringify({ message: 'سلام' })
});
console.log(sent.answers);

عیب‌یابی

Api token is required

هدر باید دقیقاً api-token باشد. توکن را در Authorization یا Query String نفرستید.

You are restricted to access the site.

IP خروجی درخواست در فهرست IPهای مجاز نیست. IP عمومی Backend را بررسی کنید؛ اگر زیرساخت چند IP خروجی دارد، همه IPهای لازم را در پنل ثبت کنید.

گفتگو یا after_id پیدا نمی‌شود

مطمئن شوید شناسه با همین توکن و در همین گفتگو ایجاد شده و بدون فاصله یا تغییر ارسال می‌شود. after_id باید شناسه یک پیام معمولی از همان گفتگو باشد، نه شناسه گفتگو یا پیام گفتگوی دیگر.

پاسخ answers خالی است

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

نکات نهایی

• API را از Backend فراخوانی کنید، نه مستقیماً از مرورگر.
• conversation_id را به کاربر و Tenant درست متصل کنید تا گفتگوها بین کاربران جابه‌جا نشوند.
• پاسخ خطا را ثبت کنید، اما هدر api-token و محتوای حساس پیام را در Log عمومی ننویسید.
• فرم‌هایی که باید در API اجرا شوند را در پنل با پلتفرم «API» جداگانه فعال کنید.
• پیش از انتشار، ایجاد گفتگو، ارسال پیام، polling، فایل و محدودیت IP را با داده غیرحساس آزمایش کنید.