این endpoint برای شروع مکالمه با یک همیار استفاده می‌شود، از انواع ورودی متنی و صوتی پشتیبانی و ورودی‌ها را بر اساس نوع داده دریافتی اعتبارسنجی و پردازش می‌کند.
POST https://backend.yarabot.ir/agent/bot/{agent_id}/chat
(string)agent_id: شناسه یکتای همیار (string)authorization: کلید API برای احراز هویت در هدر Authorization (Literal[“voice”, “text”], پیش‌فرض: “text”)type: تعیین نوع ورودی (صوتی یا متنی). (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>"
}
این endpoint برای شروع مکالمه با همیار یارا استفاده می‌شود و از انواع ورودی متنی و صوتی پشتیبانی می‌کند. ورودی‌ها بر اساس نوع داده دریافتی اعتبارسنجی و پردازش می‌شوند.
POST https://backend.yarabot.ir/agent/bot/{agent_id}/yarachat
(string)agent_id: شناسه یکتای همیار (string)authorization: کلید API برای احراز هویت در هدر Authorizationtype (Literal[“voice”, “text”], پیش‌فرض: “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>"
}
این endpoint برای ثبت واکنش (لایک یا دیسلایک) به یک پیام خاص در یک نشست استفاده می‌شود.
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"
}
این endpoint اطلاعات تنظیمات همیار را بازمی‌گرداند.
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"
}
}
این endpoint برای بازتولید (regenerate) آخرین پاسخ همیار در یک نشست استفاده می‌شود. این عملیات فقط زمانی قابل انجام است که آخرین پیام ارسال‌شده توسط همیار قابل بازتولید باشد.
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>"
}
۲۰۰ OK: بازتولید موفقیت‌آمیز.۴۰۰ Bad Request: اعتبار اشتراک تمام شده یا درخواست نامعتبر.۴۰۱ Unauthorized: کلید API نامعتبر یا یافت نشد.۴۰۴ Not Found: همیار یا پیام مورد نظر پیدا نشد.۴۲۲ Unprocessable Entity: داده نامعتبر.این endpoint برای تبدیل یک فایل صوتی به متن استفاده می‌شود. متن فایل صوتی پس از بررسی اعتبار برگردانده می‌شود.
POST https://backend.yarabot.ir/agent/bot/{agent_id}/transcribe
agent_id (string): شناسه یکتای همیارauthorization (string): کلید API برای احراز هویتaudio_file (UploadFile): فایل صوتی که باید تبدیل به متن شود. تنها فرمت‌های زیر مجاز هستند: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"
}
۲۰۰ OK: فایل با موفقیت پردازش و متن استخراج شد.۴۰۰ Bad Request:۴۰۱ Unauthorized: کلید API نامعتبر یا اطلاعات احراز هویت ناقص است.۴۰۴ Not Found: همیار یا اطلاعات کاربری یافت نشد.۴۱۳ Payload Too Large: حجم فایل از حد مجاز بیشتر است.۵۰۰ Internal Server Error: