REST API

ما الذي ستحققه

ستقرأ مساحة عملك وتغيّرها من الشيفرة، وتُجري مكالمة صادرة.

عنوان الأساس والمصادقة

عنوان الأساس: https://phynxa.com/api. كل النصوص بصيغة JSON. وتصادق بـ Authorization: Bearer nxa_live_... (راجع مفاتيح API).

ملاحظة. تستخدم الأمثلة أدناه قيمًا مختلقة للتوضيح. استبدل المفتاح والمعرّفات بما يخصك.

نقاط الاتصال التي يستطيع مفتاح استخدامها

سرد الوكلاء

curl https://phynxa.com/api/agents -H "Authorization: Bearer nxa_live_YOUR_KEY"

يعيد مصفوفة JSON. وهذا عنصر واحد منها (مختصر):

{
  "id": "c2997c6f-9d1c-41bb-9ba7-f2e3c6e2a648",
  "name": "Reception Marina",
  "description": "",
  "language": "en",
  "model": "openai:gpt-4o-mini",
  "stt_provider": "deepgram-nova-3",
  "tts_provider": "cartesia",
  "voice": "a0e99841-438c-4a64-b679-ae501e7d6091",
  "greeting": "Hello! How can I help you today?",
  "temperature": 0.6,
  "can_end_call": true,
  "can_transfer_call": false,
  "transfer_number": "",
  "call_direction": "inbound",
  "phone_number": "",
  "active": true,
  "webhook_id": "",
  "timezone": "UTC",
  "created_at": "2026-10-10T23:27:33.841629+00:00",
  "updated_at": "2026-10-10T23:27:33.841629+00:00"
}

تكون active مساوية لـ true للوكيل المنشور. وتعود بعض المؤشرات مثل capture_enabled بالقيمة 0 أو 1.

إنشاء وكيل وتغييره

curl -X POST https://phynxa.com/api/agents \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "API example agent", "language": "en"}'

يقبل الإنشاء name (مطلوب)، واختياريًا language (en وur وhi وar وfr وes وzh) وtimezone وtemplate_id وbusiness_name وtemplate_inputs. والردّ هو الوكيل الجديد. وفي خطة Free يكون للوكيل الجديد active: false.

غيّر الحقول بـ PATCH. فلا يتغير إلا ما ترسله، وتُرفَض الحقول المجهولة حتى لا يمرّ خطأ مطبعي دون أن يلاحظه أحد:

curl -X PATCH https://phynxa.com/api/agents/AGENT_ID \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"greeting": "Thanks for calling Acme. How can I help?", "temperature": 0.4}'

وتشمل الحقول التي يمكنك تغييرها name وdescription وmodel (بصيغة provider:model، مثل openai:gpt-4.1) وsystem_prompt وgreeting وstt_provider وtts_provider وvoice وlanguage وtemperature وmax_turn_seconds وidle_prompts وidle_message وcan_end_call وcan_transfer_call وtransfer_number وphone_number وcall_direction وwebhook_id وcapture_form_id وcapture_enabled وcall_summary_enabled وtimezone وactive (للنشر أو إلغائه). ويردّ DELETE /agents/{id} بـ 204.

إجراء مكالمة صادرة

curl -X POST https://phynxa.com/api/calls/outbound \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID", "to_number": "+14155552671"}'

عند النجاح تتلقى 202:

{ "call_sid": "CA0123456789abcdef0123456789abcdef", "to": "+14155552671" }

يجب أن يكون الوكيل منشورًا ومضبوطًا على Outbound أو Inbound / Outbound، وأن تكون مساحة عملك مربوطة بـ Twilio. والأخطاء:

قراءة المكالمات والنصوص المكتوبة

يعيد GET /calls المكالمات المنتهية، الأحدث أولًا، حتى 200. ولكل منها id وagent_id وagent_name وstarted_at وended_at وseconds وturns وdirection وfrom_number وto_number وoutcome وcost_usd وحقول المراجعة summary وintent وsentiment وoutcome_label وscore وaction_items وentities، إضافةً إلى تفصيل التكلفة (llm_cost_usd وstt_cost_usd وtts_cost_usd وغيرها).

ويعيد GET /calls/{id} مكالمة واحدة مع transcript وtool_calls. ويعيد GET /calls/{id}/transcript الأسطر فقط، ولكل منها role (user أو assistant) وtext وat.

ويعيد GET /stats الإجماليات:

{
  "agents": 4,
  "active_agents": 3,
  "calls": 29,
  "minutes": 64.28,
  "avg_call_seconds": 133.0,
  "total_cost": 1.59,
  "avg_cost_per_call": 0.0548,
  "p95_latency_ms": 0.0
}

جهات الاتصال

curl -X POST https://phynxa.com/api/contacts \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sara K.", "phone_number": "+971501234567", "country_code": "AE", "timezone": "Asia/Dubai", "status": "lead"}'

status هو lead أو customer أو engaged أو blocked. ويقبل POST /contacts/import القيمة {"contacts": [ ... ]} بحد أقصى 5000 صف فيها name وphone_number وcountry_code وtimezone.

Webhooks

POST /webhooks مع {"name": "CRM sync"} ينشئ واحدًا؛ واضبط تفاصيله بـ PATCH /webhooks/{id} الذي يقبل url وmethod وheaders وsecret وevents وpayload_fields وactive وtimeout_secs (حتى 60) وretries (من 1 إلى 5):

curl -X PATCH https://phynxa.com/api/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/hooks/calls", "secret": "whsec_your_secret", "payload_fields": ["call", "review", "transcript"]}'

يرسل POST /webhooks/{id}/test عينة ويعيد {"ok": true, "status_code": 200, "error": "", "duration_ms": 2}. ولا يُعاد السرّ أبدًا: فتعرض الاستجابات secret_configured.

الأخطاء

الأخطاء بصيغة JSON وفيها detail.

ويسرد خطأ التحقق كل مشكلة:

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "name"],
      "msg": "String should have at least 1 character",
      "input": "",
      "ctx": { "min_length": 1 }
    }
  ]
}

حدود المعدل

الاختبار

شغّل مثال سرد الوكلاء. ثم أنشئ وكيلًا واحذفه مجددًا.

النتيجة المتوقعة

استجابات JSON كما هو معروض، و204 عند الحذف.

استكشاف الأخطاء

• 401 في كل طلب. تحقق من البادئة Bearer ومن أن المفتاح لم يُسحَب.
• 422 "Extra inputs are not permitted". اسم حقل مكتوب بخطأ.
• 429. أبطئ وأعد المحاولة بعد وقفة.

أدلة ذات صلة

• مفاتيح API
• Webhooks