ارسال پیام چت

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

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

مسیر سرویس

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

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

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

هدرها (Headers)

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

نحوه استفاده

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

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

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

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

ابتدا فایل را از طریق مسیر /api/v1/b2b/agent/{agent_pk}/file/upload/ آپلود کنید.(آپلود فایل)
سپس در 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/b2b/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": ""
}