نمایش مبدأ برای مستندات فنی سیستم چت با مشتری


= مستند فنی چت وب CRM (Embed) برای توسعه‌دهندگان =
این سند قرارداد '''REST API''' و '''WebSocket''' بستر چت وب را توصیف می‌کند. رابط کاربری ویجت روی سایت مشتری (مثلاً افزونهٔ وردپرس) جدا از این مخزن توسعه داده می‌شود؛ اینجا فقط بک‌اند Hesabix است.

== پیش‌نیاز دیتابیس ==
پس از به‌روزرسانی کد، مایگریشن زیر را اجرا کنید:<syntaxhighlight lang="bash">cd hesabixAPI
alembic upgrade head</syntaxhighlight>فایل مایگریشن: <code>migrations/versions/20260505_000001_crm_chat_embed.py</code>

جداول: <code>crm_chat_widgets</code>, <code>crm_chat_conversations</code>, <code>crm_chat_messages</code>.

برای ثبت مدل‌ها در metadata آل embیک، <code>import adapters.db.models.crm_chat</code> در <code>migrations/env.py</code> اضافه شده است. اگر در محیط شما جایی غیر از این، metadata بدون این مدل‌ها لود می‌شود، می‌توانید در <code>adapters/db/models/__init__.py</code> نیز ایمپورت مدل‌های <code>crm_chat</code> را اضافه کنید.

== اتصال روترها به اپلیکیشن ==

* مسیرهای مدیریتی چت زیر همان روتر CRM سوار شده‌اند: <code>router.include_router</code> در انتهای <code>adapters/api/v1/crm.py</code>.
* مسیرهای عمومی در <code>adapters/api/v1/public_share_links.py</code> با <code>include_router</code> به روتر اشتراک‌لینک‌ها اضافه شده‌اند.
* WebSocket در <code>adapters/api/v1/notifications_ws.py</code> با <code>include_router</code> کنار <code>/ws/notifications</code> ثبت شده است.

نیازی به تغییر <code>main.py</code> برای این نسخه نیست.

== جریان کاری (بازدیدکننده) ==

# '''قبل از چت'''، فرم سمت سایت شما نام، نام خانوادگی، ایمیل و تلفن را می‌گیرد.
# با <code>POST /api/v1/public/crm-chat/conversations/start</code> مکالمه ساخته می‌شود و '''<code>visitor_token</code>''' + '''<code>conversation_id</code>''' برمی‌گردد.
# سپس بازدیدکننده می‌تواند با <code>POST /api/v1/public/crm-chat/messages</code> پیام بفرستد و با <code>GET .../messages</code> تاریخچه را بخواند.
# اختیاری: برای رویداد لحظه‌ای، WebSocket بازدیدکننده (پایین) با همان <code>visitor_token</code> و <code>conversation_id</code>.

== CORS و مبدأ (Origin) ==

* درخواست‌های عمومی از دامنهٔ سایت مشتری به API Hesabix می‌آیند؛ باید دامنهٔ API در <code>allow_origins</code> تنظیمات CORS سرور Hesabix برای آن دامنه‌ها مجاز باشد (مثل سایر کلاینت‌های وب).
* برای هر '''ویجت''' می‌توان فهرست '''<code>allowed_origins</code>''' (لیست hostname، مثل <code>example.com</code>) ذخیره کرد. اگر خالی باشد، از نظر بک‌اند مبدأ بررسی نمی‌شود (پیشنهاد: در تولید حتماً محدود شود). سرور هدر <code>Origin</code> یا در نبود آن <code>Referer</code> را برای تشخیص host استفاده می‌کند.

== REST — عمومی (بدون <code>Authorization</code>) ==
پایهٔ مسیرها: همان host بک‌اند (مثلاً <code>https://api.example.com</code>).

=== شروع مکالمه ===
<code>POST /api/v1/public/crm-chat/conversations/start</code>

بدنهٔ JSON نمونه:<syntaxhighlight lang="json">{
  "public_key": "<از پنل CRM پس از ساخت ویجت>",
  "first_name": "علی",
  "last_name": "رضایی",
  "email": "ali@example.com",
  "phone": "09123456789",
  "page_url": "https://customer-site.com/contact"
}</syntaxhighlight>پاسخ موفق (داخل <code>data</code>):

* <code>conversation_id</code> (integer)
* <code>visitor_token</code> (رشتهٔ محرمانه؛ فقط برای همان مرورگر/نشست نگه دارید)
* <code>widget_id</code>

=== ارسال پیام بازدیدکننده ===
<code>POST /api/v1/public/crm-chat/messages</code><syntaxhighlight lang="json">{
  "visitor_token": "...",
  "conversation_id": 1,
  "body": "سلام، سوال دارم"
}</syntaxhighlight>

=== لیست پیام‌ها (بازدیدکننده) ===
<code>GET /api/v1/public/crm-chat/conversations/{conversation_id}/messages?visitor_token=...&#x26;limit=100</code>

خروجی: <code>{ &#x22;data&#x22;: { &#x22;items&#x22;: [ { &#x22;id&#x22;, &#x22;sender_role&#x22;, &#x22;body&#x22;, &#x22;created_at&#x22;, ... } ] } }</code>

<code>sender_role</code>: <code>visitor</code> | <code>agent</code> | <code>system</code> (در حال حاضر عمدتاً visitor/agent).

== REST — پنل CRM (با API key کاربر Hesabix) ==
همه با هدر:

<code>Authorization: Bearer &#x3C;api_key&#x3E;</code>

و همان الگوی سایر APIها (مثلاً <code>X-Business-ID</code> اگر در کلاینت شما لازم است).

پایه: <code>/api/v1/crm/businesses/{business_id}/chat/...</code>
{|
! width="20%" |متد
! width="25%" |مسیر
! width="54%" |مجوز تقریبی
|-
|GET
|<code>/widgets</code>
|<code>crm</code> + view
|-
|POST
|<code>/widgets</code>
|<code>crm</code> + write
|-
|PATCH
|<code>/widgets/{widget_id}</code>
|<code>crm</code> + write
|-
|GET
|<code>/conversations</code>
|<code>crm</code> + view
|-
|GET
|<code>/conversations/{id}/messages</code>
|<code>crm</code> + view
|-
|POST
|<code>/conversations/{id}/messages</code>
|<code>crm</code> + write (پاسخ عامل)
|-
|PATCH
|<code>/conversations/{id}</code>
|<code>crm</code> + write (وضعیت، assign، lead_id، person_id)
|}
فیلدهای ویجت مهم: <code>public_key</code>, <code>allowed_origins</code>, <code>is_active</code>, <code>settings</code> (JSON اختیاری برای آیندهٔ UI).

== WebSocket ==
مسیر: '''<code>/ws/crm-chat</code>''' (بدون پیشوند <code>/api/v1</code>؛ همان الگوی <code>/ws/notifications</code>).

بلافاصله پس از اتصال TLS، '''اولین فریم''' باید JSON متنی باشد.

=== احراز بازدیدکننده ===
<syntaxhighlight lang="json">{
  "type": "auth",
  "role": "visitor",
  "visitor_token": "...",
  "conversation_id": 1
}</syntaxhighlight>پاسخ موفق: <code>{ &#x22;type&#x22;: &#x22;auth_ok&#x22;, &#x22;role&#x22;: &#x22;visitor&#x22;, &#x22;conversation_id&#x22;: 1 }</code>

سپس سرور رویدادهای <code>crm_chat.event</code> را برای همان مکالمه push می‌کند (مثلاً <code>message.created</code>).

=== احراز عامل CRM ===
<syntaxhighlight lang="json">{
  "type": "auth",
  "role": "agent",
  "api_key": "<همان Bearer>",
  "business_id": 123
}</syntaxhighlight>پاسخ: <code>{ &#x22;type&#x22;: &#x22;auth_ok&#x22;, &#x22;role&#x22;: &#x22;agent&#x22;, &#x22;business_id&#x22;: 123 }</code>

برای دریافت پیام‌های یک ترد خاص، پس از <code>auth_ok</code> برای هر مکالمه یک بار بفرستید:<syntaxhighlight lang="json">{ "type": "subscribe", "conversation_id": 1 }</syntaxhighlight>قالب تقریبی رویداد:<syntaxhighlight lang="json">{
  "type": "crm_chat.event",
  "event": "message.created",
  "conversation_id": 1,
  "message": { "id", "conversation_id", "sender_role", "body", "user_id", "created_at" }
}</syntaxhighlight>رویدادهای <code>conversation.started</code> و <code>conversation.updated</code> روی کانال کسب‌وکار نیز برای عامل‌های متصل broadcast می‌شوند.

== ورک‌فلو (اتوماسیون) ==
تریگرهای ثبت‌شده (کلید برای نود Trigger در ویرایشگر ورک‌فلو):

* <code>crm.chat.conversation.started</code>
* <code>crm.chat.message.received</code>
* <code>crm.chat.message.sent</code>
* <code>crm.chat.conversation.assigned</code>
* <code>crm.chat.conversation.resolved</code>
* <code>crm.chat.conversation.reopened</code>

بدنهٔ <code>trigger_data</code> معمولاً شامل <code>conversation_id</code>, <code>widget_id</code> و برای پیام‌ها <code>message_id</code>, <code>body</code>, <code>sender_role</code> است.

== نمونهٔ حداقلی برای افزونهٔ وردپرس ==

# در تنظیمات افزونه: <code>API_BASE</code>, <code>public_key</code> (و در صورت نیاز <code>business_id</code> فقط برای ابزارهای داخلی، نه برای سایت عمومی).
# در فرانت سایت: فرم نام/نام‌خانوادگی/ایمیل/تلفن → <code>conversations/start</code> → ذخیرهٔ <code>visitor_token</code> در <code>sessionStorage</code>.
# ارسال پیام‌ها با <code>POST .../messages</code> و نمایش تاریخچه با <code>GET</code>.
# اختیاری: <code>new WebSocket(wsBase + '/ws/crm-chat')</code> و ارسال فریم <code>auth</code> بازدیدکننده.
# '''<code>public_key</code> را هرگز در کد سرور وردپرس برای عملیات حساس به‌تنهایی کافی نکنید'''؛ برای مدیریت ویجت فقط از توکن‌های ادمین وردپرس و درخواست سمت سرور استفاده کنید. روی سایت عمومی فقط <code>public_key</code> (همان که در embed تعمداً عمومی است) کافی است.

اگر اسکریپت ویجت را خودتان روی CDN بگذارید، آدرس آن می‌تواند بعداً فقط <code>public_key</code> را به این APIها وصل کند؛ بک‌اند Hesabix فایل JS ویجت سرو نمی‌کند.

== امنیت ==

* <code>visitor_token</code> مانند نشست کوتاه برای همان مکالمه است؛ طولانی نگه ندارید و در لاگ‌های عمومی ننویسید.
* محدودیت نرخ (rate limit) در این نسخهٔ اولیه روی اندپوینت‌های عمومی به‌صورت سراسری به عهدهٔ فایروال/زیرساخت است؛ در صورت نیاز بعداً در اپلیکیشن اضافه می‌شود.

----سؤالات یا تغییرات قرارداد API را می‌توان در کنار این سند نسخه‌گذاری کرد (مثلاً prefix <code>v2</code> در آینده).