یکپارچه‌سازی چت‌بات با API عمومی پلکسیت
با API عمومی پلکسیت، دستیار را از سرور خودتان صدا بزنید: پیام بفرستید و پاسخ را با منابع و شناسهٔ گفت‌وگو بگیرید، سند و متن به پایگاه دانش اضافه کنید و وضعیت پردازش را دنبال کنید. همهٔ مسیرها زیر /v1 و پاسخ‌ها JSON هستند.
API توسعه‌دهندگان، قدم‌به‌قدم
- ۱
کلید API بسازید
از بخش «کلیدهای API» پنل؛ کلید خام فقط یک بار نمایش داده می‌شود.
- ۲
شناسهٔ دستیار را بگیرید
GET /v1/assistants فهرست دستیارها را با id هر کدام برمی‌گرداند.
- ۳
پیام بفرستید
POST به مسیر chat با principal (شناسهٔ کاربر شما) و متن پیام.
- ۴
گفت‌وگو را ادامه دهید
conversationId پاسخ را در درخواست بعدی بفرستید تا زمینهٔ گفت‌وگو حفظ شود.
کد را کپی کنید، کلید خودتان را بگذارید
مقدار wk_… را با کلید سایتی که در تب «نصب» پنل می‌بینید جایگزین کنید؛ یا کد کامل را مستقیم از همان‌جا کپی کنید.
ارسال پیام (curl)
curl -X POST "https://api.plexit.ir/v1/assistants/<assistantCode>/chat" \
-H "Authorization: Bearer $PLEXIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"principal": "user_9f21",
"message": "هزینهٔ ارسال به تبریز چقدر است؟"
}'پاسخ شامل conversationId، text، sources (فایل‌های مرجع)، model و reasoning است.
افزودن سند متنی به پایگاه دانش (Node.js)
const res = await fetch(
`https://api.plexit.ir/v1/assistants/${assistantCode}/documents/text`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLEXIT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
filename: "return-policy.txt",
content: "کالا تا ۷ روز پس از تحویل قابل مرجوع است…",
}),
},
);
const { data } = await res.json();
// وضعیت پردازش: GET /v1/assistants/{assistantCode}/documents/jobs/{jobId}برای فایل، به مسیر documents با multipart/form-data و فیلد files بفرستید (تا ۱۰ فایل، هر کدام تا ۲۵ مگابایت).
پیش از انتشار بدانید
- هر کلید API در دقیقه تا ۶۰ درخواست مجاز است؛ پس از آن خطای 429 برمی‌گردد.
- principal را خودتان انتخاب می‌کنید و برای هر کاربر نهایی باید یکتا و پایدار باشد.
- کلید API مخصوص سرور است؛ آن را هرگز در کد سمت مرورگر یا اپلیکیشن موبایل قرار ندهید.
- هر پاسخ، موفق یا ناموفق، قالب یکسان data و response دارد.
پرسش‌های رایج: API توسعه‌دهندگان
API به کدام دستیار وصل می‌شود؟
به همان دستیاری که در پنل ساخته‌اید؛ با همان پایگاه دانش، دستورالعمل و شخصیت. شناسهٔ دستیار را از GET /v1/assistants بگیرید.
principal چیست و چرا لازم است؟
رشته‌ای است که مشخص می‌کند پیام از طرف کدام کاربر شماست، مثلاً شناسهٔ کاربر در سیستم خودتان. پلکسیت گفت‌وگوها و حافظهٔ هر principal را جدا نگه می‌دارد.
مستندات کامل کجاست؟
راهنمای شروع سریع، احراز هویت، مرجع مسیرها، خطاها و نمونه‌کد curl، Node.js و Python در doc.plexit.ir آمده است.
هزینهٔ استفاده از API جداست؟
خیر؛ پیام‌های API مثل پیام‌های ویجت از بودجهٔ هفتگی پلن و سپس کیف پول مصرف می‌کنند و در گزارش مصرف همان دستیار دیده می‌شوند.
بعد از نصب، دستیار چه کاری انجام دهد؟
کد نصب اختصاصی شما در پنل آماده است
ثبت‌نام رایگان است و به کارت بانکی نیاز ندارد. اسنادتان را بارگذاری کنید، در زمین تمرین امتحانش کنید و با یک خط کد روی سایت بگذارید.