ارسال پیام چت

ارسال پیام چت

این سرویس (endpoint) برای ارسال پیام به چت‌بات استفاده می‌شود و پاسخ‌ها به صورت استریم (streaming) با استفاده از رویدادهای SSE ارسال می‌شوند. پاسخ‌ها می‌توانند شامل پیام‌های جزئی، پیام نهایی، و رویدادهای تبدیل متن به گفتار (TTS) باشند.

برای استفاده از این سرویس، ارسال پارامتر user به‌صورت فیلدی در بدنه درخواست (Request Body) الزامی است.

مسیر سرویس

POST /api/v1/core/agent/{agent_pk}/chat-messages

پارامترهای مسیر (Path Parameters)

نام	نوع	توضیحات
agent_pk	عدد صحیح	شناسه دستیار (Agent)

هدرها (Headers)

هدر	مقدار	توضیح
Authorization	Token api-token	توکن احراز هویت
Content-Type	application/json	نوع داده ارسالی (در این مثال JSON)

---

نحوه استفاده

شروع یک مکالمه جدید

• فیلد conversation_id را خالی بگذارید تا مکالمه جدید آغاز شود.
• برای ادامه همان مکالمه در دفعات بعدی، از conversation_id که در پاسخ پیام اول دریافت میکنید، استفاده کنید.

ارسال فایل در پیام

در صورت نیاز به ارسال فایل یا عکس در پیام، مراحل زیر را انجام دهید.

1. ابتدا فایل را از طریق مسیر /api/v1/core/agent/{agent_pk}/file/upload/ آپلود کنید.(آپلود فایل)
2. سپس در payload پیام، فایل را با فرمت زیر اضافه کنید:

"files": [
  {
    "type": "file",  // یا "image"
    "transfer_method": "local_file",
    "upload_file_id": "<شناسه فایل بازگشتی از آپلود>"
  }
]

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

ورودی‌ها (inputs)

این پارامتر امکان وارد کردن مقادیر مختلفی از متغیرهایی را که توسط اپلیکیشن تعریف شده‌اند فراهم می‌کند. inputs شامل چندین جفت کلید/مقدار است که در آن:

• هر کلید (key) نمایانگر یک متغیر خاص است.
• هر مقدار (value)، مقدار مشخص شده برای آن متغیر می‌باشد.

فرمت پیش‌فرض: {} (یک شیء خالی)

مثال:

{
  "inputs": {
    "color": "red",
    "length": 300
  }
}

---

ساختار بدنه درخواست (Request Body)

{
  "query": "متن پرسش",
  "conversation_id": "uuid یا خالی برای مکالمه جدید",
  "user": "نام کاربر",
  "files": [ // اختیاری
    {
      "type": "file" یا "image",
      "transfer_method": "local_file",
      "upload_file_id": "uuid فایل آپلود شده"
    }
  ],
  "inputs": {  // اختیاری، پارامترهای سفارشی
    "color": "red",
    "length": 300
  }
}

نام فیلد	نوع	توضیحات
query	رشته (string)	متن پرسش ارسال‌شده توسط کاربر
user	رشته (string)	الزامی. شناسه کاربری که پیام را ارسال می‌کند
conversation_id	UUID یا خالی	شناسه مکالمه برای ادامه مکالمه قبلی یا ایجاد جدید
files	آرایه‌ای از اشیاء	(اختیاری) لیست فایل‌ها یا تصاویر مرتبط
type	file یا image	نوع فایل (در هر شیء داخل files)
transfer_method	رشته (string)	روش انتقال، "local_file"
upload_file_id	UUID	شناسه فایل آپلود شده
inputs	شیء (object)	(اختیاری) پارامترهای سفارشی برای پردازش هوش مصنوعی

---

---

مثال با CURL

curl --location 'https://app.houshyar24.ir/api/v1/core/agent/1/chat-messages' \
--header 'Authorization: Token <your-token>' \
--header 'Content-Type: application/json' \
--data '{
    "query": "Hello!",
    "conversation_id": "",
    "user":"ali",
    "files": [
      {
        "type": "file",
        "transfer_method": "local_file",
        "upload_file_id": "769de53c-6558-40ef-b10e-38d12daac91e"
      }
    ]
}'

---

پاسخ موفق (200)

پاسخ‌ها به صورت جریانی (SSE) ارسال می‌شوند و می‌توانند شامل انواع مختلفی از رویدادها باشند:

پیام جزئی (Partial Message Chunk)

{
  "event": "message",
  "message_id": "uuid",
  "conversation_id": "uuid",
  "answer": " I'm",
  "created_at": 1679586595
}

پیام نهایی به همراه منابع بازیابی‌شده (Final Message)

{
  "event": "message_end",
  "id": "uuid",
  "conversation_id": "uuid",
  "retriever_resources": [
    {
      "position": 1,
      "dataset_id": "uuid",
      "dataset_name": "iPhone",
      "document_id": "uuid",
      "document_name": "my_doc",
      "segment_id": "uuid",
      "score": 0.98457545,
      "content": "\"This\",\"is\",\"test\", ..."
    }
  ]
}

پیام صوتی TTS (قطعه‌ای)

{
  "event": "tts_message",
  "conversation_id": "uuid",
  "message_id": "uuid",
  "created_at": 1721205487,
  "task_id": "uuid",
  "audio": "base64 audio chunk"
}

پایان پیام صوتی TTS

{
  "event": "tts_message_end",
  "conversation_id": "uuid",
  "message_id": "uuid",
  "created_at": 1721205487,
  "task_id": "uuid",
  "audio": ""
}