المطورون / الوكلاء

بدء جلسة مباشرة مع وكيل

POST https://api.echonova.ai/v1/agents/{agentId}/sessions

تبدأ جلسة صوتية أو نصية، كما يفعل زر الاختبار في البوابة، وتعيد رمز الغرفة وعنوانها. يُرسل الرمز في هذه الإجابة فقط: انضم به إلى الغرفة من عميلك، وأنهِ الجلسة عبر `POST /v1/agents/{agentId}/sessions/{sessionId}/end`. تستهلك الجلسة أرصدة مساحة العمل، ولا تُحتسب على حد الرصيد لهذا المفتاح، وتنطبق حدود المحادثات والمكالمات الخاصة بالوكيل. إعادة محاولة البدء تفتح جلسة ثانية. يحتاج المفتاح إلى النطاق `agents:talk`.

Headers

Authorization string مطلوب

كلمة ⁦Bearer⁩ ثم مسافة ثم مفتاح ⁦API⁩ الذي يبدأ بـ ⁦ek_⁩. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.

معاملات المسار

agentId string مطلوب

معرّف الوكيل كما أعادته `GET /v1/agents`.

متن الطلب

application/json

channel string اختياري

`voice` يفتح غرفة تنضم إليها بالرمز المُعاد، و`chat` يفتح جلسة نصية. الافتراضي `voice`.

voice أو chatالافتراضي voice

الاستجابة

200 application/json كل استجابة تستخدم هذا الغلاف.

data object

النتيجة.

success boolean

قيمته ⁦true⁩ عند نجاح الطلب.

statusCode integer

يكرر رمز حالة ⁦HTTP⁩.

errorMessage string or null

قيمته ⁦null⁩ عند النجاح.

الأخطاء

الغلاف نفسه، مع ⁦success⁩ بقيمة ⁦false⁩ و ⁦data⁩ بقيمة ⁦null⁩. كل الأخطاء

POST /v1/agents/{agentId}/sessions

curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "id": "6651a1b2c3d4e5f6a7b8c9d0",
    "agentId": "6650a1b2c3d4e5f6a7b8c9d0",
    "channel": "voice",
    "status": "active",
    "startedAt": "2026-11-07T10:00:00.000Z",
    "endedAt": null,
    "token": "eyJhbGciOi...",
    "wsUrl": "wss://rooms.echonova.ai",
    "greeting": "Hello! How can I help?"
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}