المكالمات والتسجيلات

طريقتان لإجراء مكالمة

	`POST /v1/callback`	`POST /v1/calls`
المنتج	Web Callback	الاتّصال البرمجيّ
الفكرة	«عاوِد الاتّصال بهذا العميل» — غالبًا عبر أداة أو طابور (`from_queue`)	«أجرِ هذه المكالمة الآن»
Sandbox	يدعم ترويسة `x-wave-simulate` وأرقام الاختبار	مكالمات حقيقيّة فقط

تنشأ كلتاهما من رقمك، وفي sandbox تكونان مقيّدتين برقم تسجيلك. ويزيل مفتاح production هذا القيد.

curl -X POST https://api.wave.sa/v1/calls \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966500000000", "caller_id_name": "Acme" }'

{
  "call_id": "27d6dd39-…",
  "status": "initiated",
  "direction": "outbound",
  "to": "+966 50 XXX 0000",
  "from": "+966115209300",
  "sandbox": false,
  "created_at": "2026-08-19T10:00:00.000Z"
}

اقرأ سجلّ المكالمات

يُعيد GET /v1/calls مكالماتك من الأحدث للأقدم مع تقسيم صفحات بالمؤشّر. يحتاج نطاق calls:read.

curl "https://api.wave.sa/v1/calls?limit=20" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

{
  "data": [
    {
      "id": "27d6dd39-…",
      "type": "outbound",
      "status": "ended",
      "from": "+966115209300",
      "to_masked": "+966 50 XXX 0000",
      "duration_seconds": 42,
      "created_at": "2026-08-19T10:00:00.000Z",
      "answered_at": "2026-08-19T10:00:05.000Z",
      "ended_at": "2026-08-19T10:00:47.000Z"
    }
  ],
  "next_cursor": "eyJ…",
  "limit": 20
}

مرّر next_cursor بصيغة ?cursor= للتنقّل. وأرقام الوجهة مُقنّعة.

اجلب تسجيلًا

يُعيد GET /v1/calls/{call_id}/recording رابط تنزيل محدود المدّة (صالح ~60 دقيقة). يحتاج نطاق recordings:read ومفتاح production.

curl https://api.wave.sa/v1/calls/27d6dd39-…/recording \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

{
  "call_id": "27d6dd39-…",
  "url": "https://oss.example.com/…?signature=…",
  "expires_at": "2026-08-19T11:00:00.000Z"
}

لا يوجد تسجيل إلّا إذا سُجّلت المكالمة (عبر <Dial record> أو <Record> في الخلفيّة) و كان التخزين مُهيّأً لحسابك. قبل ذلك يُعيد 404 RECORDING_NOT_FOUND أو 503 RECORDING_SERVICE_UNAVAILABLE. وتحصل مفاتيح sandbox على 400 SANDBOX_KEY_NOT_ALLOWED.

تحكّم في مكالمة جارية

غيّر المكالمة وهي جارية: POST /v1/calls/{call_id}/{action}، حيث action أحد hangup أو hold أو unhold أو mute أو unmute أو dtmf ({"digits"}) أو play ({"url"}، رابط https عامّ) أو recording/start أو recording/stop. يحتاج نطاق calls:write. ويعني الردّ 200 أنّ محرّك الصوت قَبِل الأمر.

يعمل على المكالمات التي أجرتها Wave (معاودة الاتّصال والمكالمات الصادرة) وعلى المكالمات الواردة إلى أرقامك. أمّا مكالمات الاتّصال عبر الويب فتُعيد 409 CALL_NOT_CONTROLLABLE (الـ SDK يتحكّم في طرف المتصفّح نفسه).
يعمل hangup منذ الحالة initiated، وتحتاج بقيّة الإجراءات مكالمة answered.
يحدّد الحقل الاختياريّ leg في جسم الطلب الطرفَ: "customer" (الافتراضيّ) أو "agent"، أي الوكيل المتّصل الآن عبر <Dial> أو طابور. وإن لم يكن وكيل متّصلًا تحصل على 409 AGENT_LEG_NOT_CONNECTED. ويذكر الردّ الطرفَ الذي نُفّذ عليه الإجراء.

curl -X POST https://api.wave.sa/v1/calls/27d6dd39-…/mute \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"leg": "agent"}'

{
  "call_id": "27d6dd39-…",
  "action": "mute",
  "leg": "agent",
  "status": "answered",
  "request_id": "req-…"
}

يُفعَّل التحكّم أثناء المكالمة لكلّ بيئة على حدة، ولطرف الوكيل ولمسارَي التسجيل مفتاح خاصّ بكلٍّ منهما. وما دام المفتاح مُعطّلًا يُعيد المسار 503 CALL_CONTROL_DISABLED.

حوّل مكالمة جارية

أرسل المتّصل إلى وجهة أخرى: POST /v1/calls/{call_id}/transfer مع target. هذا تحويل مباشر (blind transfer): ينتقل طرف المتّصل إلى الوجهة مباشرة، دون إعلام الوجهة مسبقًا. لا تعتمد على بقاء طرف الوكيل الحاليّ متّصلًا بعد التحويل. يحتاج نطاق calls:write.

`target.type`	`target.value`
`number`	رقم هاتف سعوديّ. ومعرّف المتّصل هو رقم Wave الخاصّ بك في هذه المكالمة (الرقم الذي اتّصل به المتّصل، أو الرقم الذي اتّصلت منه Wave).
`user`	هويّة اتّصال عبر الويب تابعة لمؤسّستك.
`queue`	طابور تابع لمؤسّستك (أحرف وأرقام و`-` و`_`).

الوجهة ذات الصيغة غير الصحيحة أو غير التابعة لمؤسّستك تُعيد 422 TRANSFER_TARGET_INVALID. ويجب أن تكون المكالمة answered، ولا يمكن تنفيذ أكثر من تحويل واحد في الوقت نفسه على المكالمة (409 TRANSFER_IN_PROGRESS). وتقبل المكالمة 3 تحويلات كحدٍّ أقصى، ويُعيد التحويل التالي 409 TRANSFER_LIMIT_REACHED. ولا يُحتسب التحويل المنتهي الصلاحية (الذي لم ينفّذه المحرّك).

curl -X POST https://api.wave.sa/v1/calls/27d6dd39-…/transfer \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"target": {"type": "queue", "value": "sales"}}'

{
  "call_id": "27d6dd39-…",
  "transfer_id": "8f1c…",
  "action": "transfer",
  "status": "requested",
  "request_id": "req-…"
}

تردّ Wave بـ 202 فورًا. وعندما تظهر نتيجة التحويل، ترسل Wave حدث webhook واحدًا call.transferred يحمل outcome: answered أو no_answer أو busy أو failed أو cancelled أو enqueued (وجهة طابور) أو expired (لم يُنفّذه محرّك الصوت). إذا لم تردّ الوجهة، تنتهي المكالمة. اقرأ تحويلات المكالمة ونتائجها عبر GET /v1/calls/{call_id}/transfers (نطاق calls:read). وفي مكالمة sandbox محاكاة، يكتمل التحويل فورًا بالنتيجة answered، ويحمل الـ webhook العلامة simulated.

لتحويل المكالمات مفتاح خاصّ لكلّ بيئة، وهو غير متاح في بيئة الإنتاج بعد. وما دام مُعطّلًا يُعيد المسار 503 CALL_CONTROL_DISABLED.

ضع المكالمات في غرفة مؤتمر

اجمع عدّة مكالمات جارية ليسمع كلّ طرف الآخرين: POST /v1/calls/{call_id}/conference مع تسمية room. أوّل مكالمة تنضمّ إلى تسمية تبدأ غرفة جديدة، وتنضمّ المكالمات الأخرى إلى الغرفة نفسها بالتسمية نفسها. يحتاج نطاق conferences:write ومفتاح إنتاج (يُعيد المفتاح التجريبيّ 400 SANDBOX_KEY_NOT_ALLOWED).

room هي تسميتك: من 1 إلى 64 حرفًا أو رقمًا أو . أو _ أو -. التسميات خاصّة بكلّ مشروع، فلا يستطيع مشروع آخر الانضمام إلى غرفتك.
يجب أن تكون المكالمة answered. تنضمّ المكالمات التي أجرتها Wave والمكالمات الواردة، أمّا مكالمات الاتّصال عبر الويب فتُعيد 409 CALL_NOT_CONTROLLABLE.
leg هو "customer" (الافتراضيّ) أو "agent" (الوكيل المتّصل الآن، بقواعد التحكّم أثناء المكالمة نفسها).
تكون المكالمة في غرفة واحدة في كلّ مرّة: المكالمة الموجودة في غرفة مفتوحة أخرى تُعيد 409 CALL_ALREADY_IN_CONFERENCE. والانضمام إلى الغرفة نفسها مرّة أخرى يُعيد 200 دون تغيير، فإعادة المحاولة آمنة.
تتّسع الغرفة لـ 10 مكالمات كحدٍّ أقصى، وتُعيد المكالمة التالية 409 CONFERENCE_FULL.
المكالمة الوحيدة في الغرفة تسمع صمتًا (دون موسيقى).

curl -X POST https://api.wave.sa/v1/calls/27d6dd39-…/conference \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"room": "support-escalation"}'

{
  "conference": {
    "conference_id": "5b1f0c9e-…",
    "room": "support-escalation",
    "status": "active",
    "member_count": 1
  },
  "member": { "call_id": "27d6dd39-…", "leg": "customer" },
  "request_id": "req-…"
}

اقرأ الغرفة عبر GET /v1/conferences/{conference_id} (نطاق conferences:read): حالتها وكلّ مكالمة كانت فيها مع وقتَي الانضمام والمغادرة. أنهِ الغرفة عبر POST /v1/conferences/{conference_id}/end: يغادر كلّ الأعضاء وتصبح حالة الغرفة ended (ويُعاد 409 CONFERENCE_ENDED إذا كانت قد انتهت). لا يُعاد استخدام الغرفة المنتهية، فالانضمام التالي بالتسمية نفسها يبدأ غرفة جديدة. لإخراج عضو واحد، أنهِ مكالمته (POST /v1/calls/{call_id}/hangup) — وهذا يُنهي تلك المكالمة. وعندما يغادر آخر عضو، تنتهي الغرفة. أحداث الـ webhook: conference.created (أوّل انضمام) وconference.member_joined وconference.member_left (حدث واحد لكلّ عضو، مع reason: engine_event أو call_ended أو room_ended) وconference.ended (حدث واحد لكلّ غرفة). يحمل كلّ حدث conference_id وroom وstatus وmember_count، وتحمل أحداث الأعضاء أيضًا call_id وleg.

للمكالمات الجماعيّة مفتاح خاصّ لكلّ بيئة، وهي غير متاحة في بيئة الإنتاج بعد. وما دامت مُعطّلة تُعيد المسارات 503 CALL_CONTROL_DISABLED.

الخطوات التالية

الاتّصال عبر الويب

أجرِ مكالمات من المتصفّح عبر الـ SDK.

Webhooks

استقبِل أحداث المكالمات بدل الاستعلام المتكرّر.

البدء

الصوت

Web Callback

واتساب

المرجع

المكالمات والتسجيلات

طريقتان لإجراء مكالمة

اقرأ سجلّ المكالمات

اجلب تسجيلًا

تحكّم في مكالمة جارية

حوّل مكالمة جارية

ضع المكالمات في غرفة مؤتمر

الخطوات التالية

الاتّصال عبر الويب

Webhooks

​طريقتان لإجراء مكالمة

​اقرأ سجلّ المكالمات

​اجلب تسجيلًا

​تحكّم في مكالمة جارية

​حوّل مكالمة جارية

​ضع المكالمات في غرفة مؤتمر

​الخطوات التالية

الاتّصال عبر الويب

Webhooks

طريقتان لإجراء مكالمة

اقرأ سجلّ المكالمات

اجلب تسجيلًا

تحكّم في مكالمة جارية

حوّل مكالمة جارية

ضع المكالمات في غرفة مؤتمر

الخطوات التالية