الاتّصال عبر الويب (WebRTC)

تتيح لك Calling SDK إجراء مكالمات صوتيّة حقيقيّة واستقبالها في المتصفّح عبر WebRTC — دون إضافات. تُضمّن سكربتًا واحدًا، وتمنحه مفتاح API، ثمّ تستدعي connect() ثمّ initCall(). يتولّى Wave تسجيل SIP والوسائط وبيانات الجلسة قصيرة العمر نيابةً عنك.

يستخدم الاتّصال عبر الويب نطاق webrtc:write. في sandbox تكون المكالمات مقيّدة بالأصل (origin) وبوجهة رقم تسجيلك؛ ويزيل مفتاح production (sk_live_) قيد الوجهة.

التثبيت

npm install @wave-sa/calling-sdk

<script src="https://unpkg.com/@wave-sa/calling-sdk"></script>
<!-- يوفّر المتغيّر العامّ `Wave.SDK` -->

قبل البدء

اسمح بأصلك. في لوحة تحكّم Wave، أضِف الأصل الذي يعمل عليه تطبيقك (مثل https://app.example.com) إلى الأصول المسموح بها لمشروعك. تجلب الـ SDK جلستها من /v1/webrtc/config التي ترفض أيّ أصل ليس على القائمة.
استخدم مفتاح webrtc:write. يُرسَل المفتاح من المتصفّح، لذا فهو مقيّد بالأصل بحكم التصميم.

المفتاح المُضمَّن في المتصفّح مرئيّ لأيّ شخص يحمّل صفحتك. يقيّده Wave بالأصل (وبالوجهة في sandbox) لاحتواء الأثر — لكن في production عامِل المفتاح المُضمَّن كأنّه عامّ واقصره على webrtc:write فقط.

بداية سريعة

import { WaveSDK } from "@wave-sa/calling-sdk";

const sdk = new WaveSDK(
  { apiKey: "sk_live_xxxxxxxxxxxx", apiUrl: "https://api.wave.sa/v1" },
  {
    onConnected: () => console.log("مُسجَّل — جاهز للاتّصال"),
    onCallProgress: () => console.log("يرنّ…"),
    onCallConnected: () => console.log("في مكالمة"),
    onCallEnded: () => console.log("انتهت المكالمة"),
    onFailed: (err) => console.error(err.code, err.message),
  },
);

await sdk.connect();              // جلب الجلسة، فتح WebSocket، تسجيل SIP
await sdk.initCall("+966500000000"); // اتّصال
// … لاحقًا
await sdk.endCall();
sdk.disconnect();

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

كلّ جلسة متصفّح من أحد نوعين. يحدّد الخيار identity النوع.

النوع	كيف تفتحه	ما يمكنه
جلسة وكيل	اضبط `identity` (مثل `"1001"`).	يجري المكالمات ويستقبلها. يسجّل المتصفّح بهذه الهويّة، فيرنّ عند تسجيل دخول وكيل طابور أو `<Dial>` في مسار مكالمة بالاسم نفسه.
جلسة متّصل	لا تضبط `identity`.	يجري المكالمات فقط. استخدمها لزائر موقع يتّصل بنشاطك التجاريّ. يمنح Wave الجلسة مستخدم SIP مؤقّتًا ويحذفه عند انتهاء الجلسة.

قواعد الهويّة

من 1 إلى 64 حرفًا من A–Z a–z 0–9 . _ -.
استخدم الهويّة نفسها في كلّ مكان: في الـ SDK، وفي POST /v1/queues/agents/login، وفي <Dial> داخل مسار المكالمة.
البادئتان p_ (أعضاء البوّابة) وc_ (جلسات المتّصل) محجوزتان. الهويّة التي تبدأ بإحداهما تُعيد 400 INVALID_IDENTITY.
إذا كان لدى المستأجر مستخدم SIP بهذا الاسم لم ينشئه Wave (مثل هاتف مكتبيّ)، فلا يغيّره Wave ويُعيد 409 IDENTITY_CONFLICT. استخدم هويّة أخرى.
ينشئ Wave مستخدم SIP عند أوّل استخدام، ويضبط كلمة مرور جديدة لكلّ جلسة. لا تدير أنت مستخدمي SIP.
جلسة واحدة لكلّ هويّة. إذا فتحت الهويّة نفسها جلسة ثانية (مثل تبويب ثانٍ)، تفوز الجلسة الأحدث. تتلقّى الجلسة الأقدم onSessionEnded("revoked") عند تحديث بياناتها التالي، وتتوقّف عن الرنين.
تحتاج جلسات الوكيل إلى مفتاح production (sk_live_). يتجاهل مفتاح sandbox الخيار identity ويفتح جلسة متّصل.

استقبال المكالمات

اضبط identity وأضِف مُعالِج onIncomingCall. يتلقّى المُعالِج كائن مكالمة:

الحقل	المعنى
`from`	المتّصل (رقم هاتف مثل `+9665…`، أو هويّة أخرى).
`callSid`	معرّف مكالمة Wave.
`accept()`	يحصل على الميكروفون، ثمّ يردّ. تتبعها أحداث المكالمة المعتادة (`onCallConnected`، `onCallEnded`، …).
`reject()`	يرفض المكالمة (SIP `486 Busy Here`).

const sdk = new WaveSDK(
  { apiKey: "sk_live_xxxxxxxxxxxx", identity: "1001" },
  {
    onIncomingCall: (call) => {
      showRinging(call.from);
      acceptButton.onclick = () => call.accept();
      rejectButton.onclick = () => call.reject();
    },
    onIncomingCallCancelled: () => hideRinging(), // أنهى المتّصل المكالمة أوّلًا
    onCallConnected: () => console.log("في مكالمة"),
  },
);
await sdk.connect();

مكالمة واحدة في كلّ مرّة. أثناء مكالمة نشطة أو رنين، تتلقّى أيّ مكالمة واردة جديدة 486 Busy Here، ولا تصل إلى onIncomingCall.
إذا أنهى المتّصل المكالمة قبل القبول أو الرفض، يُطلَق onIncomingCallCancelled(). بعد ذلك يرمي accept() وreject() على كائن المكالمة هذا الخطأ NO_ACTIVE_CALL.
إذا رُفض الميكروفون، يرمي accept() الخطأ MICROPHONE_UNAVAILABLE ويستمرّ رنين المكالمة. يمكنك عندها استدعاء reject().
إذا ضبطت onIncomingCall دون identity، يرمي الـ constructor الخطأ INCOMING_REQUIRES_IDENTITY.

جودة المكالمة

أثناء اتّصال المكالمة وعدم تعليقها، ترسل الـ SDK الحدث onQualityReport(metrics) كلّ 5 ثوانٍ. يغطّي كلّ تقرير آخر 5 ثوانٍ:

الحقل	المعنى
`mos`	متوسّط درجة الرأي المقدَّر، من 1 إلى 4.5. يُحسَب في المتصفّح بنموذج E في ITU-T G.107 من القيم أدناه. هو تقدير، وليس درجة مَقيسة.
`jitter`	تذبذب الصوت المستلَم، بالميلّي ثانية.
`packetLoss`	نسبة حزم الصوت المستلَمة المفقودة في الفترة، بالمئة.
`roundTripTime`	زمن الذهاب والإياب في الشبكة، بالميلّي ثانية.
`timestamp`	وقت التقرير (ميلّي ثانية منذ epoch).

تتوقّف التقارير عند انتهاء المكالمة أو تعليقها، وتبدأ من جديد عند استئنافها. للاسترشاد: قيمة mos من 4.0 فأكثر جيّدة، ومن 3.6 إلى 4.0 متوسّطة، وأقلّ من 3.6 ضعيفة. تبقى قيم الجودة في المتصفّح؛ لا يستلمها Wave.

الإعدادات

new WaveSDK(config, events)

الخيار	النوع	ملاحظات
`apiKey`	نصّ	مطلوب. مفتاحك `sk_sandbox_` / `sk_live_`.
`destination`	نصّ	رقم افتراضيّ اختياريّ لـ `initCall()`.
`locale`	`"en"` \| `"ar"`	لغة الواجهة. الافتراضيّ `"en"`.
`apiUrl`	نصّ	أساس الـ API. الافتراضيّ `https://api.wave.sa/v1`.
`identity`	نصّ	اختياريّ. يفتح جلسة وكيل تستقبل المكالمات. راجِع قواعد الهويّة أعلاه.

الدوالّ

الدالّة	ما تفعله
`connect()`	تجلب الجلسة، تفتح قناة الإشارة، وتسجّل. تُطلق `onConnected` عند الجاهزيّة.
`initCall(destination?)`	تحصل على الميكروفون وتتّصل. تُعيد `{ callSid, status: "initiated" }`.
`endCall()`	تنهي المكالمة النشطة.
`muteCall()` / `unmuteCall()`	كتم الميكروفون أو استعادته.
`holdCall()` / `resumeCall()`	تعليق المكالمة أو استئنافها.
`sendDTMF(tones, transportType?)`	إرسال نغمات لوحة المفاتيح (`0–9 * # A–D`). الافتراضيّ RFC 2833؛ مرّر `"INFO"` لـ SIP INFO.
`disconnect()`	تفكيك كلّ شيء وتحرير الميكروفون.
`isMuted`	حالة الكتم الحاليّة.

الأحداث

مرّر المُعالِجات في الوسيط الثاني للـ constructor.

الحدث	يُطلَق عند
`onConnecting()`	فتح قناة الإشارة.
`onConnected()`	التسجيل — جاهز للاتّصال.
`onCallProgress()`	رنين الطرف الآخر.
`onCallConnected()`	الردّ على المكالمة وتدفّق الوسائط.
`onCallEnded()`	إنهاؤك المكالمة عبر `endCall()`.
`onCallDisconnected(reason)`	انقطاع المكالمة — `reason` هو `NETWORK_ERROR` أو `TIMEOUT` أو `SERVER_ERROR` أو `REMOTE_HANGUP`.
`onMuteStateChange(isMuted)`	بعد `muteCall()` / `unmuteCall()`.
`onHold()` / `onResumed()`	تعليق المكالمة / استئنافها.
`onFailed(error)`	فشل الإعداد أو التسجيل — راجِع رموز الأخطاء أدناه.
`onTokenWillExpire()`	قبل ~60 ثانية من انتهاء بيانات الجلسة (للعلم).
`onSessionRefreshed()`	تدوير بيانات الجلسة بنجاح.
`onSessionEnded(reason)`	انتهاء الجلسة عند Wave (`auth_failure` أو `revoked`). تشمل `revoked` جلسة أحدث للهويّة نفسها.
`onIncomingCall(call)`	رنين مكالمة في جلسة الوكيل هذه. يحتاج `identity`.
`onIncomingCallCancelled()`	أنهى المتّصل المكالمة قبل القبول أو الرفض.
`onQualityReport(metrics)`	كلّ 5 ثوانٍ أثناء مكالمة متّصلة: MOS المقدَّر، والتذبذب، وفقد الحزم، وزمن الذهاب والإياب.

لا تتعامل أنت مع كلمة مرور SIP أو رمز الجلسة. تجلبها الـ SDK، وتُبقي المكالمة حيّة، وتدوّرها تلقائيًّا قبل انتهائها بنحو دقيقة.

رموز الأخطاء

يمنحك onFailed(error) قيمة error.code:

الرمز	المعنى
`INVALID_API_KEY_FORMAT`	`apiKey` ليس مفتاح Wave معروفًا.
`UNSUPPORTED_BROWSER`	لا دعم لـ WebRTC.
`MICROPHONE_UNAVAILABLE`	رُفض إذن الميكروفون أو لا جهاز إدخال.
`CONFIG_FAILED`	تعذّر جلب الجلسة — غالبًا الأصل غير مسموح به.
`AUTH_FAILURE`	رُفض المفتاح.
`REGISTRATION_FAILED`	فشل تسجيل SIP.
`TURN_UNAVAILABLE`	لا مُرحِّل وسائط على شبكة مقيّدة.
`CALL_ALREADY_ACTIVE` / `NO_ACTIVE_CALL`	سوء استخدام لحالة المكالمة.
`NOT_CONNECTED`	استدعاء `initCall()` قبل اكتمال `connect()`.
`CALL_FAILED`	تعذّر إعداد المكالمة.
`INCOMING_REQUIRES_IDENTITY`	يرميه الـ constructor: ضُبط `onIncomingCall` دون `identity`.

قد يفشل طلب الجلسة (POST /v1/webrtc/config) أيضًا بأخطاء الـ API هذه. تُبلغ عنها الـ SDK بالرمز CONFIG_FAILED، مع حالة HTTP في الرسالة:

خطأ الـ API	الحالة	المعنى
`INVALID_IDENTITY`	400	الهويّة تخالف القواعد أعلاه (الأحرف، أو الطول، أو بادئة محجوزة).
`IDENTITY_CONFLICT`	409	لدى المستأجر مستخدم SIP بهذا الاسم لم ينشئه Wave. لم يغيّره Wave.
`WEBRTC_PROVISIONING_FAILED`	502	تعذّر على Wave تجهيز مستخدم SIP. أعِد المحاولة.

الـ Webhooks

عند انتهاء مكالمة من المتصفّح، يرسل Wave الـ webhook المعتاد call.ended لها (راجِع الـ Webhooks).

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

كيف يعمل الصوت

أين تقع مكالمة المتصفّح في دورة حياة المكالمة.

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

اقرأ السجلّ واجلب تسجيلًا.

البدء

الصوت

Web Callback

واتساب

المرجع

الاتّصال عبر الويب (WebRTC)

التثبيت

قبل البدء

بداية سريعة

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

استقبال المكالمات

جودة المكالمة

الإعدادات

الدوالّ

الأحداث

رموز الأخطاء

الـ Webhooks

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

كيف يعمل الصوت

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

​التثبيت

​قبل البدء

​بداية سريعة

​جلسات الوكيل وجلسات المتّصل

​استقبال المكالمات

​جودة المكالمة

​الإعدادات

​الدوالّ

​الأحداث

​رموز الأخطاء

​الـ Webhooks

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

كيف يعمل الصوت

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

التثبيت

قبل البدء

بداية سريعة

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

استقبال المكالمات

جودة المكالمة

الإعدادات

الدوالّ

الأحداث

رموز الأخطاء

الـ Webhooks

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