Voice Agent

خيارات الجلسة

اضبط التعليمات والافتتاحية والصوت والمتغيرات وأدوات العميل لجلسة 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.gendermale أو 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.enabledtrueقل عبارة عندما لا تكون الأداة قد أجابت بعد.
initial.after_ms1200المللي ثواني التي تُنتظر قبل تلك العبارة، من 0 إلى 120000.
long_wait.enabledtrueقل عبارة ثانية عند الانتظار الطويل.
long_wait.after_ms10000المللي ثواني التي تُنتظر قبل العبارة الثانية، من 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المعرّف من الاستجابة.
statuspending: بدأت الجلسة ولم ينضم أحد. 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الدقائق المخصومة حتى الآن؛ راجع الحدود والفوترة.
limitsmax_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 في الصفحة الأخيرة.

المعاملالمعنى
statuspending أو 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.

في هذه الصفحة