REST API

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

آدرس پایه همه درخواست‌ها:

https://app.hichat.ir/api/v1

احراز هویت

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

Authorization: Bearer cf_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

برای هر کلید فقط دسترسی‌هایی را بدهید که لازم است. هر کلید تازه باید دست‌کم یک IP یا محدوده IP مجاز داشته باشد (مثل 203.0.113.10 یا 203.0.113.0/24) و فقط از همان‌ها کار می‌کند. می‌توانید تاریخ انقضا هم بگذارید.

دسترسی	کار
`conversations:read`	خواندن گفتگوها
`conversations:write`	بستن، سپردن و برچسب زدن
`messages:read` / `messages:write`	خواندن و فرستادن پیام
`visitors:read` / `visitors:write`	خواندن، ویرایش و مسدود کردن کاربران
`team:read`	دیدن اپراتورها و بخش‌ها
`canned:read` / `canned:write`	پاسخ‌های آماده
`stats:read`	آمار
`webhooks:write`	مدیریت وب‌هوک‌ها
`widget:write`	فرمان به ویجت

قالب پاسخ و خطا

همه پاسخ‌ها JSON هستند. شناسه‌ها رشته‌اند (عدد ۶۴ بیتی). خطاها این شکل را دارند:

{ "error": "not_found", "message": "..." }

کد	معنی
`400`	ورودی نامعتبر
`401`	کلید نامعتبر یا منقضی
`402`	بسته فعلی این امکان را ندارد
`403`	کلید این دسترسی را ندارد یا IP مجاز نیست
`404`	پیدا نشد (یا مال سایت دیگری است)
`429`	درخواست زیاد؛ کمی صبر کنید
`503`	API به‌طور موقت از طرف های چت متوقف شده است؛ کمی بعد دوباره امتحان کنید

گفتگوها

فهرست گفتگوها

GET /conversations?status=active&limit=50

پارامترها: status یکی از open، queued، closed، bot یا active (همه بازها)، from و to (تاریخ ISO)، visitorId، limit (تا ۱۰۰) و before برای صفحه بعد. مقدار next در پاسخ را به عنوان before بفرستید.

یک گفتگو

GET /conversations/{id}

پیام‌های گفتگو

GET /conversations/{id}/messages?before={messageId}

یادداشت‌های داخلی فقط با internal=1 برگردانده می‌شوند.

فرستادن پیام

POST /conversations/{id}/messages
Content-Type: application/json

{ "text": "سفارش شما ارسال شد.", "clientId": "6f1c..." }

به جای text می‌توانید rich بفرستید (متن قالب‌دار). با "internal": true پیام به صورت یادداشت داخلی ثبت می‌شود. clientId اختیاری است و جلوی ثبت تکراری را می‌گیرد.

فرستادن فایل

POST /conversations/{id}/files?name=invoice.pdf
Content-Type: application/pdf

<بدنه فایل>

بستن، سپردن و برچسب

POST /conversations/{id}/close
POST /conversations/{id}/assign      { "memberId": "..." }  یا  { "departmentId": "..." }
PUT  /conversations/{id}/tags        { "tags": ["پیگیری", "مالی"] }

کاربران

GET   /visitors/{id}
PATCH /visitors/{id}          { "name": "...", "phone": "...", "email": "...", "note": "...", "tags": [], "data": {} }
POST  /visitors/{id}/block    { "reason": "مزاحمت", "block": true }

با "block": false کاربر از مسدودی خارج می‌شود.

تیم و پاسخ‌های آماده

GET    /operators
GET    /departments
GET    /canned
POST   /canned          { "title": "زمان ارسال", "body": [[{ "t": "دو روز کاری" }]], "shortcut": "ارسال" }
DELETE /canned/{id}

آمار

GET /stats?from=2026-09-22T00:00:00Z&to=2026-10-22T00:00:00Z

تعداد گفتگو، پیام‌های ورودی و خروجی، میانگین زمان اولین پاسخ (ثانیه) و میانگین امتیاز.

فرمان به ویجت

برای کاربری که الان در سایت است، ویجت را باز یا بسته کنید یا یک رویداد سفارشی به صفحه بفرستید:

POST /visitors/{id}/widget
{ "action": "event", "name": "coupon", "data": { "code": "AFTAB20" } }

در صفحه سایت با HiChat('on', 'custom', fn) دریافت می‌شود. این فرمان فقط داده می‌فرستد و هیچ کدی در صفحه اجرا نمی‌کند.

وب‌هوک‌ها

GET    /webhooks
POST   /webhooks       { "url": "https://example.com/hichat", "events": ["message.created"] }
DELETE /webhooks/{id}

در پاسخ ساخت، secret فقط همین یک بار برمی‌گردد. جزئیات در وب‌هوک.