https://wiki.hesabix.ir/index.php?action=history&feed=atom&title=%D9%85%D8%B3%D8%AA%D9%86%D8%AF%D8%A7%D8%AA_%D9%81%D9%86%DB%8C_%D8%B3%DB%8C%D8%B3%D8%AA%D9%85_%DA%86%D8%AA_%D8%A8%D8%A7_%D9%85%D8%B4%D8%AA%D8%B1%DB%8Cمستندات فنی سیستم چت با مشتری - تاریخچهٔ نسخهها2026-05-25T21:55:49Zتاریخچهٔ نسخهها برای این صفحه در ویکیMediaWiki 1.45.1https://wiki.hesabix.ir/index.php?title=%D9%85%D8%B3%D8%AA%D9%86%D8%AF%D8%A7%D8%AA_%D9%81%D9%86%DB%8C_%D8%B3%DB%8C%D8%B3%D8%AA%D9%85_%DA%86%D8%AA_%D8%A8%D8%A7_%D9%85%D8%B4%D8%AA%D8%B1%DB%8C&diff=30&oldid=prevAlizadeh.babak: صفحهای تازه حاوی « = مستند فنی چت وب CRM (Embed) برای توسعهدهندگان = این سند قرارداد '''REST API''' و '''WebSocket''' بستر چت وب را توصیف میکند. رابط کاربری ویجت روی سایت مشتری (مثلاً افزونهٔ وردپرس) جدا از این مخزن توسعه داده میشود؛ اینجا فقط بکاند Hesabix است. == پیشنیاز دیتاب...» ایجاد کرد2026-04-25T00:36:07Z<p>صفحهای تازه حاوی « = مستند فنی چت وب CRM (Embed) برای توسعهدهندگان = این سند قرارداد '''REST API''' و '''WebSocket''' بستر چت وب را توصیف میکند. رابط کاربری ویجت روی سایت مشتری (مثلاً افزونهٔ وردپرس) جدا از این مخزن توسعه داده میشود؛ اینجا فقط بکاند Hesabix است. == پیشنیاز دیتاب...» ایجاد کرد</p>
<p><b>صفحهٔ تازه</b></p><div><br />
= مستند فنی چت وب CRM (Embed) برای توسعهدهندگان =<br />
این سند قرارداد '''REST API''' و '''WebSocket''' بستر چت وب را توصیف میکند. رابط کاربری ویجت روی سایت مشتری (مثلاً افزونهٔ وردپرس) جدا از این مخزن توسعه داده میشود؛ اینجا فقط بکاند Hesabix است.<br />
<br />
== پیشنیاز دیتابیس ==<br />
پس از بهروزرسانی کد، مایگریشن زیر را اجرا کنید:<syntaxhighlight lang="bash">cd hesabixAPI<br />
alembic upgrade head</syntaxhighlight>فایل مایگریشن: <code>migrations/versions/20260505_000001_crm_chat_embed.py</code><br />
<br />
جداول: <code>crm_chat_widgets</code>, <code>crm_chat_conversations</code>, <code>crm_chat_messages</code>.<br />
<br />
برای ثبت مدلها در 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> را اضافه کنید.<br />
<br />
== اتصال روترها به اپلیکیشن ==<br />
<br />
* مسیرهای مدیریتی چت زیر همان روتر CRM سوار شدهاند: <code>router.include_router</code> در انتهای <code>adapters/api/v1/crm.py</code>.<br />
* مسیرهای عمومی در <code>adapters/api/v1/public_share_links.py</code> با <code>include_router</code> به روتر اشتراکلینکها اضافه شدهاند.<br />
* WebSocket در <code>adapters/api/v1/notifications_ws.py</code> با <code>include_router</code> کنار <code>/ws/notifications</code> ثبت شده است.<br />
<br />
نیازی به تغییر <code>main.py</code> برای این نسخه نیست.<br />
<br />
== جریان کاری (بازدیدکننده) ==<br />
<br />
# '''قبل از چت'''، فرم سمت سایت شما نام، نام خانوادگی، ایمیل و تلفن را میگیرد.<br />
# با <code>POST /api/v1/public/crm-chat/conversations/start</code> مکالمه ساخته میشود و '''<code>visitor_token</code>''' + '''<code>conversation_id</code>''' برمیگردد.<br />
# سپس بازدیدکننده میتواند با <code>POST /api/v1/public/crm-chat/messages</code> پیام بفرستد و با <code>GET .../messages</code> تاریخچه را بخواند.<br />
# اختیاری: برای رویداد لحظهای، WebSocket بازدیدکننده (پایین) با همان <code>visitor_token</code> و <code>conversation_id</code>.<br />
<br />
== CORS و مبدأ (Origin) ==<br />
<br />
* درخواستهای عمومی از دامنهٔ سایت مشتری به API Hesabix میآیند؛ باید دامنهٔ API در <code>allow_origins</code> تنظیمات CORS سرور Hesabix برای آن دامنهها مجاز باشد (مثل سایر کلاینتهای وب).<br />
* برای هر '''ویجت''' میتوان فهرست '''<code>allowed_origins</code>''' (لیست hostname، مثل <code>example.com</code>) ذخیره کرد. اگر خالی باشد، از نظر بکاند مبدأ بررسی نمیشود (پیشنهاد: در تولید حتماً محدود شود). سرور هدر <code>Origin</code> یا در نبود آن <code>Referer</code> را برای تشخیص host استفاده میکند.<br />
<br />
== REST — عمومی (بدون <code>Authorization</code>) ==<br />
پایهٔ مسیرها: همان host بکاند (مثلاً <code>https://api.example.com</code>).<br />
<br />
=== شروع مکالمه ===<br />
<code>POST /api/v1/public/crm-chat/conversations/start</code><br />
<br />
بدنهٔ JSON نمونه:<syntaxhighlight lang="json">{<br />
"public_key": "<از پنل CRM پس از ساخت ویجت>",<br />
"first_name": "علی",<br />
"last_name": "رضایی",<br />
"email": "ali@example.com",<br />
"phone": "09123456789",<br />
"page_url": "https://customer-site.com/contact"<br />
}</syntaxhighlight>پاسخ موفق (داخل <code>data</code>):<br />
<br />
* <code>conversation_id</code> (integer)<br />
* <code>visitor_token</code> (رشتهٔ محرمانه؛ فقط برای همان مرورگر/نشست نگه دارید)<br />
* <code>widget_id</code><br />
<br />
=== ارسال پیام بازدیدکننده ===<br />
<code>POST /api/v1/public/crm-chat/messages</code><syntaxhighlight lang="json">{<br />
"visitor_token": "...",<br />
"conversation_id": 1,<br />
"body": "سلام، سوال دارم"<br />
}</syntaxhighlight><br />
<br />
=== لیست پیامها (بازدیدکننده) ===<br />
<code>GET /api/v1/public/crm-chat/conversations/{conversation_id}/messages?visitor_token=...&#x26;limit=100</code><br />
<br />
خروجی: <code>{ &#x22;data&#x22;: { &#x22;items&#x22;: [ { &#x22;id&#x22;, &#x22;sender_role&#x22;, &#x22;body&#x22;, &#x22;created_at&#x22;, ... } ] } }</code><br />
<br />
<code>sender_role</code>: <code>visitor</code> | <code>agent</code> | <code>system</code> (در حال حاضر عمدتاً visitor/agent).<br />
<br />
== REST — پنل CRM (با API key کاربر Hesabix) ==<br />
همه با هدر:<br />
<br />
<code>Authorization: Bearer &#x3C;api_key&#x3E;</code><br />
<br />
و همان الگوی سایر APIها (مثلاً <code>X-Business-ID</code> اگر در کلاینت شما لازم است).<br />
<br />
پایه: <code>/api/v1/crm/businesses/{business_id}/chat/...</code><br />
{|<br />
! width="20%" |متد<br />
! width="25%" |مسیر<br />
! width="54%" |مجوز تقریبی<br />
|-<br />
|GET<br />
|<code>/widgets</code><br />
|<code>crm</code> + view<br />
|-<br />
|POST<br />
|<code>/widgets</code><br />
|<code>crm</code> + write<br />
|-<br />
|PATCH<br />
|<code>/widgets/{widget_id}</code><br />
|<code>crm</code> + write<br />
|-<br />
|GET<br />
|<code>/conversations</code><br />
|<code>crm</code> + view<br />
|-<br />
|GET<br />
|<code>/conversations/{id}/messages</code><br />
|<code>crm</code> + view<br />
|-<br />
|POST<br />
|<code>/conversations/{id}/messages</code><br />
|<code>crm</code> + write (پاسخ عامل)<br />
|-<br />
|PATCH<br />
|<code>/conversations/{id}</code><br />
|<code>crm</code> + write (وضعیت، assign، lead_id، person_id)<br />
|}<br />
فیلدهای ویجت مهم: <code>public_key</code>, <code>allowed_origins</code>, <code>is_active</code>, <code>settings</code> (JSON اختیاری برای آیندهٔ UI).<br />
<br />
== WebSocket ==<br />
مسیر: '''<code>/ws/crm-chat</code>''' (بدون پیشوند <code>/api/v1</code>؛ همان الگوی <code>/ws/notifications</code>).<br />
<br />
بلافاصله پس از اتصال TLS، '''اولین فریم''' باید JSON متنی باشد.<br />
<br />
=== احراز بازدیدکننده ===<br />
<syntaxhighlight lang="json">{<br />
"type": "auth",<br />
"role": "visitor",<br />
"visitor_token": "...",<br />
"conversation_id": 1<br />
}</syntaxhighlight>پاسخ موفق: <code>{ &#x22;type&#x22;: &#x22;auth_ok&#x22;, &#x22;role&#x22;: &#x22;visitor&#x22;, &#x22;conversation_id&#x22;: 1 }</code><br />
<br />
سپس سرور رویدادهای <code>crm_chat.event</code> را برای همان مکالمه push میکند (مثلاً <code>message.created</code>).<br />
<br />
=== احراز عامل CRM ===<br />
<syntaxhighlight lang="json">{<br />
"type": "auth",<br />
"role": "agent",<br />
"api_key": "<همان Bearer>",<br />
"business_id": 123<br />
}</syntaxhighlight>پاسخ: <code>{ &#x22;type&#x22;: &#x22;auth_ok&#x22;, &#x22;role&#x22;: &#x22;agent&#x22;, &#x22;business_id&#x22;: 123 }</code><br />
<br />
برای دریافت پیامهای یک ترد خاص، پس از <code>auth_ok</code> برای هر مکالمه یک بار بفرستید:<syntaxhighlight lang="json">{ "type": "subscribe", "conversation_id": 1 }</syntaxhighlight>قالب تقریبی رویداد:<syntaxhighlight lang="json">{<br />
"type": "crm_chat.event",<br />
"event": "message.created",<br />
"conversation_id": 1,<br />
"message": { "id", "conversation_id", "sender_role", "body", "user_id", "created_at" }<br />
}</syntaxhighlight>رویدادهای <code>conversation.started</code> و <code>conversation.updated</code> روی کانال کسبوکار نیز برای عاملهای متصل broadcast میشوند.<br />
<br />
== ورکفلو (اتوماسیون) ==<br />
تریگرهای ثبتشده (کلید برای نود Trigger در ویرایشگر ورکفلو):<br />
<br />
* <code>crm.chat.conversation.started</code><br />
* <code>crm.chat.message.received</code><br />
* <code>crm.chat.message.sent</code><br />
* <code>crm.chat.conversation.assigned</code><br />
* <code>crm.chat.conversation.resolved</code><br />
* <code>crm.chat.conversation.reopened</code><br />
<br />
بدنهٔ <code>trigger_data</code> معمولاً شامل <code>conversation_id</code>, <code>widget_id</code> و برای پیامها <code>message_id</code>, <code>body</code>, <code>sender_role</code> است.<br />
<br />
== نمونهٔ حداقلی برای افزونهٔ وردپرس ==<br />
<br />
# در تنظیمات افزونه: <code>API_BASE</code>, <code>public_key</code> (و در صورت نیاز <code>business_id</code> فقط برای ابزارهای داخلی، نه برای سایت عمومی).<br />
# در فرانت سایت: فرم نام/نامخانوادگی/ایمیل/تلفن → <code>conversations/start</code> → ذخیرهٔ <code>visitor_token</code> در <code>sessionStorage</code>.<br />
# ارسال پیامها با <code>POST .../messages</code> و نمایش تاریخچه با <code>GET</code>.<br />
# اختیاری: <code>new WebSocket(wsBase + '/ws/crm-chat')</code> و ارسال فریم <code>auth</code> بازدیدکننده.<br />
# '''<code>public_key</code> را هرگز در کد سرور وردپرس برای عملیات حساس بهتنهایی کافی نکنید'''؛ برای مدیریت ویجت فقط از توکنهای ادمین وردپرس و درخواست سمت سرور استفاده کنید. روی سایت عمومی فقط <code>public_key</code> (همان که در embed تعمداً عمومی است) کافی است.<br />
<br />
اگر اسکریپت ویجت را خودتان روی CDN بگذارید، آدرس آن میتواند بعداً فقط <code>public_key</code> را به این APIها وصل کند؛ بکاند Hesabix فایل JS ویجت سرو نمیکند.<br />
<br />
== امنیت ==<br />
<br />
* <code>visitor_token</code> مانند نشست کوتاه برای همان مکالمه است؛ طولانی نگه ندارید و در لاگهای عمومی ننویسید.<br />
* محدودیت نرخ (rate limit) در این نسخهٔ اولیه روی اندپوینتهای عمومی بهصورت سراسری به عهدهٔ فایروال/زیرساخت است؛ در صورت نیاز بعداً در اپلیکیشن اضافه میشود.<br />
<br />
----سؤالات یا تغییرات قرارداد API را میتوان در کنار این سند نسخهگذاری کرد (مثلاً prefix <code>v2</code> در آینده).</div>Alizadeh.babak