​

إعداد هاتف الويب (WebRTC) البرمجي

1. الهاتف البرمجي المدمج في لوحة التحكم — توفر Orbit هاتفًا برمجيًا جاهزًا داخل لوحة التحكم. هذا هو المسار الخالي من الكود ونقطة البداية المناسبة لمعظم الفرق.
2. هاتف برمجي مضمّن قائم على LiveKit (Softphone في @devotel-orbit/web) — تركّب الهاتف البرمجي داخل مساحة عمل الموظف الخاصة بك (نظام CRM، أو حائط مركز الاتصال، أو أداة داخلية) بواجهة استخدام خاصة بك.
3. هاتف برمجي مضمّن عبر SIP-over-WSS (مسار تسجيل SIP) — عميل SIP تقليدي (مثل JsSIP) يسجّل مباشرة لدى بوابة Orbit التي تحول WebRTC إلى SIP، للفرق التي تريد دلالات SIP القياسية ومنطق تحكم مكالمات خاصًا بها.

​

1. تسجيل الأجهزة ورموز VoIP push (الجوال)

curl -X POST https://api.orbit.devotel.io/api/v1/push/voip-devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "voip_token": "APNS_VOIP_TOKEN_HEX",
    "bundle_id": "com.yourcompany.orbit-agent"
  }'

• قيمة platform هي ios أو android. على iOS يكون voip_token رمز PushKit (CallKit)؛ وعلى Android رمز تسجيل FCM المستخدم لقناة المكالمات عالية الأولوية.
• قيمة bundle_id (iOS فقط) هي معرّف حزمة التطبيق — موضوع إشعار VoIP هو <bundle_id>.voip.
• يعيد الاستجابة الجهاز المسجل (id، platform، last_seen_at).

​

2. إصدار بيانات اعتماد الهاتف البرمجي

​

الهاتف البرمجي المدمج في لوحة التحكم / المضمّن عبر LiveKit

curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/token \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "token": "<livekit access token>",
    "media_url": "wss://..."
  }
}

​

الهاتف البرمجي المضمّن عبر SIP/WSS

curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callerIdNumber": "+15559876", "deviceLabel": "agent-desk-04" }'

{
  "data": {
    "sipUsername": "u_agent_x1a2b3",
    "sipPassword": "...",
    "sipDomain": "sip.orbit.devotel.io",
    "wssUrl": "wss://...",
    "iceServers": [{ "urls": "stun:..." }],
    "callerIdNumber": "+15559876",
    "expiresAt": 1716110400000
  }
}

• تعيش بيانات الاعتماد 60 دقيقة — أعد التسجيل قبل expiresAt وإلا انقطعت الجلسة.
• يجب أن يكون callerIdNumber رقمًا تملكه مؤسستك (وإلا فُرض 403) — هكذا يُحظر انتحال هوية المتصل الصادرة.
• يرتبط اسم المستخدم بمؤسستك، فلا يمكن إعادة تشغيل اسم مستخدم مسروق ضد مستأجر آخر.
• إصدار الرموز محدد النطاق بـ owner/admin/developer — ليست نقطة نهاية عامة ومجهولة.

​

3. اختر كيف تصل المكالمات الواردة إلى الهاتف البرمجي

• DNIS → طابور → هاتف برمجي. المسار الأشيع: يرسل التوجيه الوارد لرقم هاتفك المكالمة إلى طابور ACD، ويعرضها الطابور على الهاتف البرمجي في متصفح موظف متاح (وإن كان على تطبيق الجوال، فإشعار VoIP — القسم 1). تضبط هذا لكل رقم في توجيه الأرقام بلوحة التحكم، أو عبر منشئ التدفقات.
• DNIS → توجيه SIP. وجّه المكالمات الواردة إلى مجال SIP الذي تعيش عليه تسجيلات هاتفك البرمجي. استخدم هذا عندما تهبط حركتك الواردة أصلًا على SIP (مثلاً رقم DID محوَّل إلى عنوان SIP URI خاص بك) وتريد أن يجيب الهاتف البرمجي المسجل مباشرة.
• هاتف المتصل البرمجي يجري المكالمات الصادرة. للفرق التي تقودها المكالمات الصادرة لا تنشأ مسألة الوارد أصلًا — يبدأ الموظف المكالمات، وأية إجابة واردة تكون على رقم موجَّه إلى طابور (عودة إلى الخيار الأول).

​

4. مقطع JS كامل — الميكروفون، وإشعار VoIP، والاحتياط في المتصفح

import { OrbitSoftphone } from "@devotel-orbit/web";

const softphone = new OrbitSoftphone({
  apiBaseUrl: "https://api.orbit.devotel.io",
  apiKey: "YOUR_API_KEY", // serve from your backend — never commit it
  // Optional: force a media URL. Omit to use the token response.
  // mediaUrl: "wss://...",
  onCallStateChange: (s) => console.log("softphone state:", s),
  onError: (e) => handleSoftphoneFailure(e), // ← fallback lives here
});

// 1. Mic is gated on the browser's getUserMedia. Ask for it on a user
//    gesture (a click) — not page load — so the permission prompt is
//    attributed and the mic isn't held open on an idle tab.
async function armMicrophone() {
  await navigator.mediaDevices.getUserMedia({ audio: true });
  await softphone.connect(); // mints token + publishes mic
}

// 2. Place an outbound call.
async function callCustomer(e164) {
  return softphone.dial(e164); // returns call_id when ringing
}

// 3. Fallback: if the browser/media path can't connect, hand the call
//    to a click-to-call bridge (the caller's desk phone or mobile
//    rings, and the agent talks there). This is also the path when an
//    enterprise network blocks WebRTC entirely.
function handleSoftphoneFailure(err) {
  console.warn("WebRTC unavailable, falling back:", err.message);
  // show "call me on my device" UI → POST /voice/click-to-call instead
}

// VoIP push (mobile only): the browser cannot receive a VoIP push -
// mobile handles it natively. From the browser, the inbound ring just
// arrives when an inbound call is routed to the agent's room.

​

5. التحقق واستكشاف الأخطاء

1. أصدر بيانات اعتماد (القسم 2)، وصِل العميل (القسم 4)، وابحث عن حدث connect للغرفة أو registered لـ SIP.
2. أجرِ مكالمة صادرة إلى جوالك — ينبغي أن تسمع رنينًا ثم صوتًا في الاتجاهين عند الإجابة.
3. وجّه مكالمة واردة إلى رقمك (القسم 3) وتأكد أن الهاتف البرمجي يرن ويجيب.
4. إذا كنت قد سجلت جهاز VoIP للجوال (القسم 1)، فضع تطبيق الجوال في الخلفية وتأكد من ظهور واجهة مكالمة واردة أصلية.

​

إلى أين تذهب بعد ذلك

• متطلبات شبكة الهاتف البرمجي — المنافذ والمضيفات وقائمة الوكيل لإدراجها في القائمة البيضاء لمكالمات المتصفح على جدار ناري مؤسسي أو VPN.
• صفحة المكالمة التجريبية في SDK — أجرِ مكالمة تجريبية صادرة حقيقية من لوحة التحكم (Developer → SDK Live Demo) للتأكد من سلامة هذا الإعداد من طرف إلى طرف.
• إعداد SIP trunk — إن أردت إحضار ناقل/trunk خاص بك إلى جانب الهاتف البرمجي في المتصفح.
• طوابير الصوت — طابور ACD الذي تمر عبره المكالمات الواردة قبل أن يجيب الهاتف البرمجي.
• Web SDK — خريطة الأحداث الكاملة لـ Softphone وسائر أسطح SDK.
• رحلة تأهيل الأسبوع الأول للموظفين — الرحلة التي تضع الهاتف البرمجي في الأسبوع الأول لموظف جديد (من المصدر الإنجليزي حتى يُنشر البديل المترجم).