شروع سریع

در این صفحه یک‌بار کل مسیر را طی می‌کنیم: ساخت یک کلید، پیدا کردن یک دستیار، گفتگو با آن، و مدیریت هم مسیر موفق و هم یک خطا. ده دقیقه، کاملاً قابل کپی‌کردن.

ساخت یک کلید API

وارد کنسول پلکسیت شوید (یا ثبت‌نام کنید )، به تنظیمات ← API و اتصال بروید و کلیدی با نام «Quickstart» بسازید.

کلید خامی را که کنسول نمایش می‌دهد کپی کنید — فقط یک‌بار نمایش داده می‌شود. برای جزئیات کامل این مرحله به احراز هویت مراجعه کنید.


export PLEXIT_API_KEY="pk_live_..."

فهرست دستیارهای خود

curl


curl https://api.plexit.ir/v1/assistants \
  -H "Authorization: Bearer $PLEXIT_API_KEY"


{
  "data": {
    "list": [
      {
        "id": "3f9a2c1e5b7d4a6f8c0e2b4d6f8a1c3e",
        "name": "Support Bot",
        "instruction": "Answer questions about our product using the knowledge base.",
        "model": "sol",
        "reasoning": "low",
        "status": "active",
        "description": "Customer support assistant",
        "personality": "friendly",
        "language": "en",
        "avatarUrl": "https://api.plexit.ir/avatars/3f9a2c1e.png",
        "createdAt": "2026-05-01T09:00:00.000Z"
      }
    ],
    "count": 1
  },
  "response": { "status": "success", "message": "..." }
}

مقدار id دستیار را یادداشت کنید (در URLهای زیر به‌عنوان :assistantCode استفاده می‌شود — «assistant code» و id دستیار در اینجا یک مقدار یکسان‌اند).

ارسال اولین پیام گفتگو

curl


curl -X POST "https://api.plexit.ir/v1/assistants/3f9a2c1e5b7d4a6f8c0e2b4d6f8a1c3e/chat" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "user-42",
    "message": "What are your business hours?"
  }'

Node.js


const assistantCode = "3f9a2c1e5b7d4a6f8c0e2b4d6f8a1c3e";
 
const res = await fetch(
  `https://api.plexit.ir/v1/assistants/${assistantCode}/chat`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PLEXIT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      principal: "user-42",
      message: "What are your business hours?",
    }),
  },
);
 
const { data, response } = await res.json();
if (!res.ok) {
  throw new Error(`Plexit error: ${response.status} — ${response.message}`);
}
console.log(data.text);

Python


import os
import requests
 
assistant_code = "3f9a2c1e5b7d4a6f8c0e2b4d6f8a1c3e"
 
res = requests.post(
    f"https://api.plexit.ir/v1/assistants/{assistant_code}/chat",
    headers={"Authorization": f"Bearer {os.environ['PLEXIT_API_KEY']}"},
    json={"principal": "user-42", "message": "What are your business hours?"},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"Plexit error: {body['response']['status']} — {body['response']['message']}")
print(body["data"]["text"])

فیلد principal رشته‌ای است که شما انتخاب می‌کنید تا مشخص کند کدام‌یک از کاربران نهاییِ خودتان در حال گفتگو است. برای توضیح کامل اینکه چرا این فیلد وجود دارد و چگونه فضانام‌گذاری می‌شود به POST /v1/assistants/:assistantCode/chat مراجعه کنید.

پاسخ:


{
  "data": {
    "conversationId": "9c1e3f5a7b9d2c4e6f8a0b2d4f6a8c0e",
    "text": "We're open Monday–Friday, 9am–6pm.",
    "sources": [
      { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "path": "/faq/hours.md", "chunk": 2 }
    ],
    "model": "sol",
    "reasoning": "low",
    "degraded": false,
    "quota": { "...": "وضعیت مبهم دفتر هزینه، توضیح در ادامه" }
  },
  "response": { "status": "success", "message": "..." }
}

فیلد quota عیناً از دفتر هزینه‌ی سرویس retrieval عبور داده می‌شود — شکل آن عمداً بخشی از قرارداد این API نیست، پس فیلدهای خاصی از آن را تجزیه نکنید؛ فقط آن را به‌عنوان یک شیء مبهم لاگ کنید یا منتقل نمایید. مقدار degraded: true به این معناست که پاسخ از یک مسیر تنزل‌یافته (مثلاً یک مسیر جایگزین/Fallback) سرو شده است؛ ارزش لاگ‌کردن را دارد، اما مجموعه‌ای مستند و پایدار از دلایل آن وجود ندارد.

اگر می‌خواهید همین مکالمه را بعداً ادامه دهید، conversationId را ذخیره کنید — به ادامه‌ی یک مکالمه مراجعه کنید.

مدیریت خطاها

هر پاسخ — چه موفق چه ناموفق — از یک قالب یکسان استفاده می‌کند. در صورت شکست، data برابر null است و response.message یک رشته‌ی خوانا برای انسان و از پیش ترجمه‌شده است:


{
  "data": null,
  "response": { "status": "not_found", "message": "Assistant not found." }
}


const { data, response } = await res.json();
if (!res.ok) {
  // response.status یک مقدار enum قابل‌خواندن توسط ماشین است (رجوع کنید به /errors)
  // response.message برای انسان خواناست و نمایش/لاگ آن بی‌خطر است.
  console.error(response.status, response.message);
  return;
}

جزئیات کامل، شامل رفتار ۴۰۱ عمومی و قالب خطاهای اعتبارسنجی، در صفحه‌ی خطاها آمده است.

همین است، کل مسیر. هر چیز دیگری در این API — بارگذاری اسناد، پایش وضعیت Job، فهرست/حذف اسناد — روی همین دو مفهومِ پایه سوار است: یک assistantCode و کلید Bearer شما.

شروع سریع

ساخت یک کلید API

فهرست دستیارهای خود

ارسال اولین پیام گفتگو

curl

Node.js

Python

مدیریت خطاها

مراحل بعدی