مستندات API

مستندات API

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

ساختار URL

POST https://backend.yarabot.ir/agent/bot/{agent_id}/chat

پارامتر‌های مسیر

  • (string)agent_id: شناسه یکتای همیار

پارامتر‌های کوئری

  • (string)authorization: کلید API برای احراز هویت در هدر Authorization

پارامتر‌های فرم

  • (Literal[“voice”, “text”],ضرف‌شیپ: “text”)type: تعیین نوع ورودی (صوتی یا متنی).
    • اگر مقدار “voice” باشد، باید یک فایل صوتی ارسال شود.
    • اگر مقدار “text” باشد، یک پیام متنی ارسال می‌شود.
  • (string)text: پیام متنی (در صورت انتخاب type=“text” ضروری است).
  • (UploadFile)file: فایل صوتی (در صورت انتخاب type=“voice” ضروری است).
  • (string، یرایتخا)session_id: شناسه نشست موجود. اگر داده نشود، یک نشست جدید ایجاد خواهد شد.

مثال درخواست

  • ورودی متنی:
curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/chat \
  --header 'authorization: {YOUR_TOKEN}' \
  --data-urlencode 'type=text' \
  --data-urlencode 'text=؟تسیچ ظفاح بقل
'
  • ورودی صوتی:
curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/chat \
  --header 'authorization: {YOUR_TOKEN}' \
  --form 'type=voice' \
  --form 'file=@path/to/audiofile.wav'

پاسخ

این endpoint یک پاسخ استریم (streaming) شامل پیام‌های تولید شده توسط همیار (assistant) برمی‌گرداند. پاسخ در قالب JSON خواهد بود و هر بخش از پاسخ همیار به صورت قطعه به قطعه به کاربر ارسال می‌شود.

  • فرمت استریم پاسخ:
{
  "data": "<assistant_message_chunk>"
}
  • ایجاد جلسه جدید:
{
  "session_id": "<new_session_id>"
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: درخواست موفق.
  • ۴۰۰ Bad Request: خطا در داده‌های ورودی.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: شناسه همیار یافت نشد.
  • ۴۱۳ Payload Too Large: فایل صوتی بزرگ‌تر از حد مجاز.
  • ۴۲۲ Unprocessable Entity: فرمت داده نادرست.

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

ساختار URL

POST https://backend.yarabot.ir/agent/bot/{agent_id}/yarachat

پارامتر‌های مسیر

  • (string)agent_id: شناسه یکتای همیار

پارامتر‌های کوئری

  • (string)authorization: کلید API برای احراز هویت در هدر Authorization

پارامتر‌های فرم

  • type (Literal[“voice”, “text”], پیش‌فرض: “text”): تعیین نوع ورودی (صوتی یا متنی).
    • اگر مقدار “voice” باشد، باید یک فایل صوتی ارسال شود.
    • اگر مقدار “text” باشد، یک پیام متنی ارسال می‌شود.
  • (string)text: پیام متنی (در صورت انتخاب type=“text” ضروری است).
  • (UploadFile)file: فایل صوتی (در صورت انتخاب type=“voice” ضروری است).
  • (string، یرایتخا)session_id: شناسه نشست موجود. اگر داده نشود، یک نشست جدید ایجاد خواهد شد.

مثال درخواست

  • ورودی متنی:
curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/yarachat \
  --header 'authorization: {YOUR_TOKEN}' \
  --data-urlencode 'type=text' \
  --data-urlencode 'text=؟دوش‌یم هتخاس شارخ‌نامسآ کی هنوگچ
'
  • ورودی صوتی:
curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/yarachat \
  --header 'authorization: {YOUR_TOKEN}' \
  --form 'type=voice' \
  --form 'file=@path/to/audiofile.wav'

پاسخ

پاسخ استریم (streaming) شامل پیام‌های تولید شده توسط همیار یارا است. قالب پاسخ به شکل JSON است.
در صورتی که نشست جدید ایجاد شود، شناسه نشست جدید در پاسخ ارسال خواهد شد.

  • فرمت استریم پاسخ:
{
  "data": "<assistant_message_chunk>"
}
  • ایجاد نشست جدید:
{
  "session_id": "<new_session_id>"
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: درخواست موفق.
  • ۴۰۰ Bad Request: خطا در داده‌های ورودی.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: شناسه همیار یافت نشد.
  • ۴۱۳ Payload Too Large: فایل صوتی بزرگ‌تر از حد مجاز.
  • ۴۲۲ Unprocessable Entity: فرمت داده نادرست.

این endpoint برای ثبت واکنش (like یا dislike) به یک پیام خاص در یک نشست استفاده می‌شود.

ساختار URL

POST https://backend.yarabot.ir/agent/bot/{agent_id}/{session_id}/{message_id}

پارامتر‌های مسیر

  • (string)agent_id: شناسه یکتای همیار
  • (string)session_id: شناسه یکتای نشست
  • (string)message_id : شناسه یکتای پیام

پارامتر‌های هدر

  • (string)authorization : کلید API برای احراز هویت

پارامتر‌های فرم

  • react (boolean، اختیاری): مقدار true برای لایک و false برای حذف لایک از پیام.

مثال درخواست

curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/{session_id}/{message_id} \
  --header 'authorization: {YOUR_TOKEN}' \
  --data-urlencode 'react=true'

پاسخ

  • موفقیت:
{
  "status": "success",
  "message": "Message reacted successfully"
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: درخواست موفق.
  • ۴۰۰ Bad Request: خطا در داده‌های ورودی.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: شناسه نشست یا پیام یافت نشد.
  • ۵۰۰ Internal Server Error: خطای داخلی سرور.

این endpoint اطلاعات تنظیمات همیار را بازمی‌گرداند.

ساختار URL

GET https://backend.yarabot.ir/agent/bot/{agent_id}/preferences

پارامتر‌های مسیر

  • (string)agent_id: شناسه یکتای همیار

پارامتر‌های کوئری

  • (string)authorization : کلید API برای احراز هویت در هدر Authorization

پاسخ

  • موفقیت:
{
  "name": "Yara Assistant",
  "description": "<رایمه تاحیضوت>",
  "preferences": {
    "header_color": "#۰۰۰۰۰۰",
    "agent_response_color": "#ffffff",
    "user_chat_color": "#cccccc",
    "background_color": "#eeeeee",
    "text_color": "#۳۳۳۳۳۳",
    "input_color": "#dddddd",
    "logo_url": "https://example.com/logo.png"
  }
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: درخواست موفق.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: تنظیمات یافت نشد یا شناسه همیار نامعتبر.

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

ساختار URL

PUT https://backend.yarabot.ir/agent/bot/{agent_id}/{session_id}/{message_id}

پارامترهای مسیر

  • agent_id (string): شناسه یکتای همیار
  • session_id (string): شناسه یکتای نشست
  • message_id (string): شناسه یکتای پیام همیار که باید بازتولید شود

پارامترهای هدر

  • authorization (string): کلید API برای احراز هویت

عملکرد

  • اگر پیام مربوطه توسط همیار تولید شده باشد و هنوز اعتبار اشتراک کاربر باقی‌مانده باشد، یک پاسخ جدید از سمت همیار تولید شده و جایگزین پاسخ قبلی می‌شود.
  • پیام قبلی در لیست old_response ذخیره خواهد شد.
  • مقدار اعتبار باقی‌مانده کاربر (برحسب تعداد کلمات) کاهش پیدا می‌کند.

مثال درخواست

curl --request PUT \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/{session_id}/{message_id} \
  --header 'authorization: {YOUR_TOKEN}'

پاسخ

پاسخ به صورت استریم ارسال می‌شود و شامل پیام‌های تولید شده توسط همیار است.

فرمت استریم پاسخ:
{
  "data": "<assistant_message_chunk>"
}
پایان پاسخ (به‌همراه شناسه پیام):
{
  "message_id": "<regenerated_message_id>"
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: بازتولید موفقیت‌آمیز.
  • ۴۰۰ Bad Request: اعتبار اشتراک تمام شده یا درخواست نامعتبر.
  • ۴۰۱ Unauthorized: کلید API نامعتبر یا یافت نشد.
  • ۴۰۴ Not Found: همیار یا پیام مورد نظر پیدا نشد.
  • ۴۲۲ Unprocessable Entity: داده نامعتبر.

این endpoint برای تبدیل یک فایل صوتی به متن استفاده می‌شود. متن فایل صوتی پس از بررسی اعتبار برگردانده می‌شود.

ساختار URL

POST https://backend.yarabot.ir/agent/bot/{agent_id}/transcribe

پارامتر‌های مسیر

  • agent_id (string): شناسه یکتای همیار

پارامتر‌های هدر

  • authorization (string): کلید API برای احراز هویت

پارامترهای فرم

  • audio_file (UploadFile): فایل صوتی که باید تبدیل به متن شود. تنها فرمت‌های زیر مجاز هستند:
    • audio/ogg
    • audio/mpeg (مانند .mp3)
    • audio/wav
    • audio/webm
    • video/webm

مثال درخواست

curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/transcribe \
  --header 'authorization: {YOUR_TOKEN}' \
  --form 'audio_file=@path/to/audiofile.wav'

پاسخ

در صورت موفقیت، متن استخراج‌شده از فایل صوتی به همراه اطلاعات فایل بازگردانده می‌شود.

نمونه پاسخ:
{
  "text": "؟تسا روطچ امش لاح ،مالس",
  "file_name": "audiofile.wav",
  "file_size": 182394,
  "status": "success"
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: فایل با موفقیت پردازش و متن استخراج شد.
  • ۴۰۰ Bad Request:
    • فایل ارسال نشده است.
    • نوع فایل ارسال‌شده مجاز نیست.
    • اشتراک کاربر منقضی شده یا فعال نیست.
  • ۴۰۱ Unauthorized: کلید API نامعتبر یا اطلاعات احراز هویت ناقص است.
  • ۴۰۴ Not Found: همیار یا اطلاعات کاربری یافت نشد.
  • ۴۱۳ Payload Too Large: حجم فایل از حد مجاز بیشتر است.
  • ۵۰۰ Internal Server Error:
    • خطا در خواندن نوع فایل یا MIME type.
    • خطا در پردازش فایل صوتی برای استخراج متن.

این endpoint برای دریافت لیست فایل‌های بارگذاری‌شده مرتبط با یک همیار استفاده می‌شود.

ساختار URL

GET https://backend.yarabot.ir/agent/bot/{agent_id}/files/

پارامتر‌های مسیر

  • agent_id (string): شناسه یکتای همیار

پارامتر‌های هدر

  • authorization (string): کلید API برای احراز هویت

مثال درخواست

curl --request GET \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/files/ \
  --header 'authorization: {YOUR_TOKEN}'

پاسخ

در صورت موفقیت، لیست فایل‌های بارگذاری‌شده برگردانده می‌شود.

نمونه پاسخ:
{
  "status": "success",
  "files": [
    {
      "id": "abc12345",
      "file_name": "document.pdf",
      "size": 34567,
      "words_count": 1520,
      "created_at": "2025-08-30T10:00:00Z"
    }
  ]
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: لیست فایل‌ها با موفقیت دریافت شد.
  • ۴۰۱ Unauthorized: کلید API نامعتبر یا اطلاعات احراز هویت ناقص است.
  • ۴۰۴ Not Found: فایل یا همیار یافت نشد.

نکته: مقدار created_at در پاسخ به‌صورت تاریخ/زمان UTC

این endpoint برای بارگذاری فایل‌های جدید به همیار استفاده می‌شود.

ساختار URL

POST https://backend.yarabot.ir/agent/bot/{agent_id}/files/add

پارامتر‌های مسیر

  • agent_id (string): شناسه یکتای همیار

پارامتر‌های هدر

  • authorization (string): کلید API برای احراز هویت

پارامترهای فرم

  • files (List[UploadFile]): لیست فایل‌های متنی جهت بارگذاری

    فرمت‌های پشتیبانی‌شده: pdf, txt و …

مثال درخواست

curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/files/add \
  --header 'authorization: {YOUR_TOKEN}' \
  --form 'files=@path/to/document.pdf' \
  --form 'files=@path/to/another.txt'

پاسخ

در صورت موفقیت، پیام تایید بازگردانده می‌شود.

نمونه پاسخ:
{
  "status": "success",
  "message": "Files added to the agent successfully."
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: فایل‌ها با موفقیت بارگذاری شدند.
  • ۴۰۰ Bad Request: اشتراک منقضی، حجم فایل زیاد یا محدودیت ظرفیت.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: همیار یافت نشد.
  • ۵۰۰ Internal Server Error: خطا در ذخیره‌سازی فایل‌ها.

این endpoint محتوای کامل یک فایل خاص را برمی‌گرداند.

ساختار URL

GET https://backend.yarabot.ir/agent/bot/{agent_id}/files/{file_id}

پارامتر‌های مسیر

  • agent_id (string): شناسه یکتای همیار
  • file_id (string): شناسه یکتای فایل

پارامتر‌های هدر

  • authorization (string): کلید API برای احراز هویت

مثال درخواست

curl --request GET \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/files/{file_id} \
  --header 'authorization: {YOUR_TOKEN}'

پاسخ

در صورت موفقیت، اطلاعات کامل فایل به همراه محتوای استخراج‌شده برگردانده می‌شود.

نمونه پاسخ:
{
  "status": "success",
  "id": "abc12345",
  "file_name": "document.pdf",
  "created_at": "2025-08-30T10:00:00Z",
  "size": 34567,
  "content": "محتوای استخراج‌شده از فایل..."
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: محتوای فایل با موفقیت دریافت شد.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: فایل یا همیار یافت نشد.
این endpoint برای حذف یک فایل خاص از همیار استفاده می‌شود.

ساختار URL

DELETE https://backend.yarabot.ir/agent/bot/{agent_id}/files/{file_id}

پارامتر‌های مسیر

  • agent_id (string): شناسه یکتای همیار
  • file_id (string): شناسه یکتای فایل

پارامتر‌های هدر

  • authorization (string): کلید API برای احراز هویت

مثال درخواست

curl --request DELETE \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/files/{file_id} \
  --header 'authorization: {YOUR_TOKEN}'

پاسخ

در صورت موفقیت، پیام تایید حذف فایل برگردانده می‌شود.

نمونه پاسخ:
{
  "status": "success",
  "message": "File deleted successfully."
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: فایل با موفقیت حذف شد.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: فایل یا همیار یافت نشد.
این endpoint برای راه‌اندازی (setup) یک همیار استفاده می‌شود. این عملیات شامل تنظیم منابع و آماده‌سازی هوش مصنوعی برای استفاده است.

ساختار URL

POST https://backend.yarabot.ir/agent/bot/{agent_id}/setup

پارامتر‌های مسیر

  • agent_id (string): شناسه یکتای همیار

پارامتر‌های هدر

  • authorization (string): کلید API برای احراز هویت

مثال درخواست

curl --request POST \
  --url https://backend.yarabot.ir/agent/bot/{agent_id}/setup \
  --header 'authorization: {YOUR_TOKEN}'

پاسخ

در صورت موفقیت، پیام تایید راه‌اندازی همیار بازگردانده می‌شود.
نمونه پاسخ:
{
  "status": "success",
  "message": "Agent set up successfully."
}

کدهای وضعیت HTTP

  • ۲۰۰ OK: همیار با موفقیت راه‌اندازی شد.
  • ۴۰۰ Bad Request: اشتراک کاربر فعال نیست یا منقضی شده.
  • ۴۰۱ Unauthorized: کلید API نامعتبر.
  • ۴۰۴ Not Found: همیار یافت نشد.
  • ۵۰۰ Internal Server Error: خطا در راه‌اندازی همیار.