خيارات الجلسة
اضبط التعليمات والافتتاحية والصوت والمتغيرات وأدوات العميل لجلسة Voice Agent، واقرأ إعداداته وحدوده، وابحث في الجلسات السابقة.
تبدأ كل مكالمة بطلب واحد من خادمك الخلفي. يحدد الطلب ما يقوله الوكيل وما يستطيع فعله في تلك المكالمة؛ ولا يُخزَّن شيء بين المكالمات.
ابدأ جلسة
curl -sS -X POST "$API_URL/agent/sessions" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"participant": { "identity": "user-123", "name": "Sara" },
"agent": {
"prompt": "You help {{name}} track order {{order}}. Keep answers short.",
"intro": "Hi {{name}}, how can I help with your order?",
"voice_id": "42e38a63-849a-481a-b5bf-3c1b7a985de3"
},
"variables": { "name": "Sara", "order": "T-1182" }
}'احصل على معرّف صوت من قائمة الأصوات؛ تختلف المعرّفات بين البيئات. ترسل
حزم SDK الطلب نفسه: createSession() في JavaScript
وcreate_session() في Python.
| الترويسة | مطلوب | المعنى |
|---|---|---|
x-api-key | نعم | مفتاح API بالنطاق agent. فعّله على المفتاح من API keys في لوحة التحكم؛ وبدونه يعيد الطلب 403 AUTH_SCOPE_MISSING. |
Content-Type | نعم | application/json. |
Idempotency-Key | لا | من 1 إلى 255 حرف ASCII قابلًا للطباعة. خلال 24 ساعة، تعيد إعادة المحاولة بالمفتاح نفسه الاستجابة الأولى بدل بدء جلسة ثانية. |
حقول الطلب
تُرفض الحقول غير المعروفة والقيم غير الصالحة بـ400.
| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
participant.identity | سلسلة | نعم | معرّفك للمستخدم، مثل معرّف حسابه لديك، بحد أقصى 128 حرفًا. يظهر في الاستخدام وطلبات الدعم. |
participant.name | سلسلة | لا | اسم العرض للمستخدم في المكالمة. لا يراه الوكيل؛ استخدم متغيرًا لتحية المستخدم باسمه. |
participant.gender | male أو female | لا | يتيح للردود العربية مخاطبة المستخدم بالجنس النحوي الصحيح. |
agent.prompt | سلسلة | لا | التعليمات: من هو الوكيل، وفيمَ يساعد، وكيف يتحدث. لا يجوز أن تكون فارغة؛ احذفها لتحصل على مساعد عام. |
agent.intro | سلسلة | لا | الجملة الأولى للوكيل، وينطقها كما كُتبت تمامًا. تجعل "" الوكيل ينتظر حتى يتحدث المستخدم أولًا. الافتراضي تحية عربية قصيرة. |
agent.voice_id | سلسلة | لا | قيمة id لصوت من قائمة الأصوات، وهي القيمة نفسها التي يأخذها تحويل النص إلى كلام. الافتراضي الصوت mul_nourah. |
agent.client_tools | مصفوفة | لا | حتى 16 دالة في صفحتك يستطيع الوكيل استدعاءها؛ راجع أدوات العميل. |
agent.tool_acknowledgments | كائن | لا | متى يخبر الوكيل المستخدم أنه لا يزال يعمل على استدعاء أداة؛ راجع عبارات انتظار الأدوات. |
agent.web_search | قيمة منطقية | لا | يتيح للوكيل البحث في الويب أثناء المكالمة. الافتراضي false؛ راجع البحث في الويب. |
variables | كائن قيمه سلاسل أو أرقام أو قيم منطقية | لا | قيم العناصر النائبة {{name}} في agent.prompt وagent.intro؛ راجع المتغيرات. |
حدود حجم الطلب في الحدود.
المدة القصوى للمكالمة، ومهلة الخمول، وعدد الأشخاص في المكالمة، والغرفة، والوكيل الذي ينضم إليها،
كلها تحددها خطتك أو HUMAIN Voice. يعيد إرسال أي من هذه الحقول 400.
المتغيرات
اكتب {{name}} في agent.prompt أو agent.intro، وأرسل القيمة في variables. تملأ كل
جلسة قيمها الخاصة، فتخدم التعليمات نفسها كل المستخدمين.
| القاعدة | التفاصيل |
|---|---|
| الأسماء | حروف وأرقام و_، وتبدأ بحرف. حساسة لحالة الأحرف. الاسمان now وsession_id مدمجان، فلا يمكنك إرسالهما. |
| قيمة مفقودة | يعيد العنصر النائب بلا قيمة 400 مع اسم الحقل والمتغير. |
| قيم غير مستخدمة | مسموح بها. |
| القيم | تُدرج كنص. وتُكتب الأرقام والقيم المنطقية بصيغة JSON (3، true). |
{{now}} المدمج | وقت طلب الجلسة بتوقيت UTC، بصيغة ISO 8601. |
{{session_id}} المدمج | قيمة session_id للمكالمة. |
يقرأ الوكيل كل متغير، فلا ترسل أسرارًا أو بيانات لا ينبغي أن يسمعها المستخدم. ولإخبار
الوكيل بشيء جديد أثناء المكالمة، مثل الصفحة التي فتحها المستخدم للتو، استخدم
updateContext().
عبارات انتظار الأدوات
أثناء تشغيل أداة عميل، يملأ الوكيل الصمت بعبارة قصيرة يكتبها لذلك الطلب، مثل "دعني أتحقق من ذلك".
| الحقل | الافتراضي | المعنى |
|---|---|---|
initial.enabled | true | قل عبارة عندما لا تكون الأداة قد أجابت بعد. |
initial.after_ms | 1200 | المللي ثواني التي تُنتظر قبل تلك العبارة، من 0 إلى 120000. |
long_wait.enabled | true | قل عبارة ثانية عند الانتظار الطويل. |
long_wait.after_ms | 10000 | المللي ثواني التي تُنتظر قبل العبارة الثانية، من 0 إلى 120000. |
اضبط enabled على false ليبقى الوكيل صامتًا في تلك المرحلة. إذا لم تجهز العبارة في الوقت،
يبقى الوكيل صامتًا بدل استخدام عبارة ثابتة.
البحث في الويب
اضبط agent.web_search على true ليتمكن الوكيل من البحث عن معلومات حديثة في الويب، مثل الأخبار
أو أوقات العمل أو الأسعار. يقرر الوكيل متى يبحث، ويملأ وقت الانتظار كما يفعل مع استدعاء الأدوات.
البحث في الويب معطّل افتراضيًا. بدونه يجيب الوكيل فقط من تعليماتك ومتغيراتك وأدوات العميل وما يعرفه النموذج مسبقًا. يرسل الوكيل عبارات البحث إلى مزوّد بحث خارجي، لذا أبقِ البحث معطّلًا إذا كان يجب أن يبقى ما يقوله المستخدمون داخل HUMAIN Voice.
تحلّ أداة عميل باسم web_search محلّ البحث المدمج.
الاستجابة
201 Created:
{
"server_url": "<server_url>",
"participant_token": "eyJhbGciOiJIUzI1NiJ9…",
"session_id": "as_01j9z3k7q4m8xv6t2n5r8b1c0d",
"expires_at": "2026-10-05T12:01:00Z",
"effective": {
"prompt": "You help Sara track order T-1182. Keep answers short.",
"intro": "Hi Sara, how can I help with your order?",
"voice_id": "42e38a63-849a-481a-b5bf-3c1b7a985de3",
"client_tools": [],
"tool_acknowledgments": {
"initial": { "enabled": true, "after_ms": 1200 },
"long_wait": { "enabled": true, "after_ms": 10000 }
},
"web_search": false
},
"limits": { "max_duration_s": 900, "idle_timeout_s": 120 }
}| الحقل | المعنى |
|---|---|
server_url | المكان الذي يتصل به المتصفح. لا تثبّته في الشيفرة. |
participant_token | يُدخل هذا المستخدم إلى هذه المكالمة فقط. أرسله إلى المتصفح مع server_url. |
session_id | معرّف المكالمة: as_ يليها 26 حرفًا صغيرًا. يظهر في الاستخدام وطلبات الدعم. |
expires_at | يجب استخدام رمز الدخول قبل هذا الوقت، أي بعد نحو 60 ثانية من الطلب. |
effective | إعدادات الوكيل بعد تطبيق القيم الافتراضية والمتغيرات. |
limits | حدود هذه المكالمة من خطتك، بالثواني. وتعني null أن خطتك لا تضع حدًا. راجع الحدود والفوترة. |
يتبع server_url وparticipant_token استجابة نقطة نهاية رموز الدخول في LiveKit،
فيستطيع عملاء LiveKit الانضمام بهما.
ابدأ الجلسة عندما يكون المستخدم مستعدًا للحديث، مثل النقر على زر، واتصل فورًا. يُرفض رمز الدخول
المستخدم بعد expires_at، وتنتهي الجلسة بـuser_never_joined دون خصم.
أخطاء التحقق
يعيد 400 استجابة الخطأ القياسية بالرمز
VALIDATION_INVALID_PARAM. يسرد data.errors كل مشكلة مع مسارها، مرتبة حسب المسار:
"data": {
"errors": [
{ "path": "agent.prompt", "reason": "missing variable: order" },
{ "path": "agent.voice_id", "reason": "unknown voice" }
]
}أخطاء الجلسة الأخرى، مثل نفاد الرصيد أو كثرة المكالمات، في رموز Voice Agent.
قراءة الجلسات
يعيد المساران جلسات حسابك فقط، ويكفي لهما أي مفتاح API نشط (دون النطاق agent)، ولا يعيدان
أبدًا التعليمات أو الافتتاحية أو الأدوات أو المتغيرات أو اسم المستخدم.
احصل على جلسة
curl -sS "$API_URL/agent/sessions/as_01j9z3k7q4m8xv6t2n5r8b1c0d" \
-H "x-api-key: $API_KEY"{
"session_id": "as_01j9z3k7q4m8xv6t2n5r8b1c0d",
"status": "ended",
"api_key_id": "5f0c1e2a-7b4d-4c1e-9a3f-2d8b6e0a1c44",
"participant_identity": "user-123",
"created_at": "2026-10-14T09:00:00Z",
"expires_at": "2026-10-14T09:01:00Z",
"started_at": "2026-10-14T09:00:04Z",
"ended_at": "2026-10-14T09:02:19Z",
"end_reason": "user_left",
"duration_s": 135,
"billed_minutes": 3,
"limits": { "max_duration_s": 900, "idle_timeout_s": 120 }
}| الحقل | المعنى |
|---|---|
session_id | المعرّف من الاستجابة. |
status | pending: بدأت الجلسة ولم ينضم أحد. live: انضم الوكيل. ended: انتهت. |
api_key_id | المفتاح الذي بدأ الجلسة. |
participant_identity | قيمة participant.identity التي أرسلتها. |
created_at، expires_at | وقت طلب الجلسة، وآخر موعد للانضمام. |
started_at | وقت انضمام الوكيل. null أثناء pending. |
ended_at | وقت انتهاء المكالمة. null حتى ذلك الحين. |
end_reason | أحد أسباب الإنهاء. null حتى تنتهي المكالمة. |
duration_s | الثواني من started_at إلى ended_at، أو إلى الآن أثناء live. null حتى ينضم الوكيل. |
billed_minutes | الدقائق المخصومة حتى الآن؛ راجع الحدود والفوترة. |
limits | max_duration_s وidle_timeout_s المثبتان عند بدء الجلسة؛ وتعني null عدم وجود حد. |
يعيد معرّف غير معروف أو بصيغة خاطئة، أو جلسة تخص حسابًا آخر، 404 AGENT_SESSION_NOT_FOUND.
اسرد الجلسات
curl -sS "$API_URL/agent/sessions?status=ended&limit=20" \
-H "x-api-key: $API_KEY"يعيد { "sessions": [ … ], "next_cursor": "…" }: الجلسات من الأحدث إلى الأقدم، وكل منها بالشكل أعلاه.
مرّر next_cursor في cursor لجلب الصفحة التالية؛ وتكون قيمته null في الصفحة الأخيرة.
| المعامل | المعنى |
|---|---|
status | pending أو live أو ended. |
end_reason | الجلسات التي انتهت بهذا سبب الإنهاء فقط. |
api_key_id | الجلسات التي بدأها هذا المفتاح فقط. |
from، to | تصفية على created_at بطوابع زمنية RFC 3339. from شامل وto غير شامل. |
limit | من 1 إلى 100. الافتراضي 50. |
cursor | قيمة next_cursor من الصفحة السابقة. |
يعيد معامل غير معروف أو مكرر 400 VALIDATION_INVALID_PARAM، وكل مشكلة في data.errors.