المكالمات / المكالمات الفردية والرنين

المكالمات الفردية والرنين

المكالمة الفردية تصل بين شخصين بالضبط. أنشئها مع تفعيل ring فيظهر للمتلقي شاشة الاتصال الأصلية؛ أصدر رمزاً لكل طرف ويتكفّل الـ SDK بالباقي.

حُدّث في 21 أكتوبر 2026 عدّل هذه الصفحة

01إنشاء المكالمة

type افتراضياً one_to_one وring افتراضياً true، فأقصر طلب هو POST /calls فارغ. مرّر metadata لتربط المكالمة بشيء في نظامك — طلب، حجز، تذكرة.

app/Http/Controllers/CallController.php server.js

1 use Sada\Laravel\Facades\Sada;

3 $call = Sada::calls()->create([

4 'type' => 'one_to_one', // or 'group'

5 'ring' => true,

6 'region' => 'auto', // baghdad · dubai · istanbul

7 'metadata' => ['order_id' => 'ord_42'],

8 ]);

10 $call->id; // "call_k3j9x2m7qa"

11 $call->status; // "ringing"

12 $call->type; // "one_to_one"

13 $call->region; // "baghdad"

14 $call->toArray(); // the full call object

1 import { sada } from './sada.js';

3 app.post('/calls', async (req, res) => {

4 const { call } = await sada('/calls', { method: 'POST', body: { type: 'one_to_one', ring: true } });

6 const { token } = await sada(`/calls/${call.call_id}/tokens`, {

7 method: 'POST',

8 body: { user_ref: String(req.user.id), display_name: req.user.name, ttl: 300 },

9 });

11 res.json({ callId: call.call_id, token });

12 });

1 curl -X POST https://sada.g4t.io/api/v1/calls \

2 -H "Authorization: Bearer sk_test_4vN8kR2pXa61Jd0s" \

3 -H "Content-Type: application/json" \

4 -d '{"type": "one_to_one", "ring": true, "metadata": {"order_id": "ord_42"}}'

الاستجابة

1 {

2 "message": "Call created successfully",

3 "call": {

4 "call_id": "call_k3j9x2m7qa",

5 "env": "test",

6 "type": "one_to_one",

7 "status": "ringing",

8 "status_text": "Ringing",

9 "region": "baghdad",

10 "ring": true,

11 "metadata": { "order_id": "ord_42" },

12 "duration_seconds": 0,

13 "participant_minutes": 0,

14 "avg_latency_ms": null,

15 "started_at": "2026-10-21T09:30:00.000000Z",

16 "connected_at": null,

17 "ended_at": null,

18 "created_at": "2026-10-21T09:30:00.000000Z",

19 "updated_at": "2026-10-21T09:30:00.000000Z"

20 }

21 }

02دورة الحياة

تمرّ المكالمة ببضع حالات. كل تغيير يُسجَّل في الخط الزمني للمكالمة (events) والمهم منها يصل إلى الـ webhooks.

الحالة	المعنى
`ringing`	أُنشئت بـ `ring: true`؛ المتلقي يُستدعى. يُرسل `call.started`.
`in_progress`	حصل الطرفان على رمز (الرمز الثاني يضبط `connected_at`)، أو أُنشئت المكالمة بـ `ring: false`.
`completed`	انتهت بعد أن اتصلت. يحمل `call.ended` المدة ودقائق المشاركين.
`missed`	انتهت قبل أن يتصل أحد. يُرسل `call.missed` ولا يُفوتر شيء.
`declined`	رفض المتلقي المكالمة من شاشة الرنين.
`failed`	تعذّر إنشاء اتصال الصوت.

03الرنين الأصلي

مع ring: true يعرض هاتف المتلقي شاشة اتصال النظام — CallKit على iOS وfull-screen intent على Android — حتى والتطبيق مغلق. يقبل المتلقي، فيطلب تطبيقك رمزاً من خادمك، وينضم الـ SDK.

الرنين يحتاج بيانات إشعارات للتطبيق في لوحة التحكم ← بيانات الإشعارات: مفتاح Apple VoIP ‏(.p8) مع معرّف المفتاح ومعرّف الفريق، وملف حساب خدمة Firebase ‏(JSON). بدونها تُنشأ المكالمة وتعمل عندما يفتح المتلقي التطبيق؛ لكنها لا ترنّ.

iOS · CallKit ارفع مفتاح Apple VoIP ‏(.p8) في بيانات الإشعارات.

Android · Full-screen intent ارفع ملف حساب خدمة Firebase ‏(JSON).

استخدم ring: false حين يكون الطرفان على الشاشة أصلاً — زر «تحدّث مع السائق» بعد أن فتح الاثنان الطلب — فتبدأ المكالمة in_progress فوراً.

04إنهاء المكالمة

مغادرة أحد الطرفين من الـ SDK ‏(call.leave()) تنهي المكالمة الفردية. ويستطيع خادمك إغلاقها نيابة عنهما بـ POST /calls/{call_id}/end: يُفصل الجميع، ويصل الباقين حدث ended بسبب ended، ويُرسل call.ended أو call.missed إلى الـ webhooks.

إنهاء مكالمة غير حيّة يردّ بـ 422 Call is not live. ويستطيع المشغّلون إنهاء مكالمة حيّة قسراً من لوحة التحكم؛ يسجّلها الخط الزمني forced بواسطة dashboard.

curl -X POST https://sada.g4t.io/api/v1/calls/call_k3j9x2m7qa/end \

-H "Authorization: Bearer sk_test_4vN8kR2pXa61Jd0s"

الاستجابة

{ "message": "Call ended successfully" }

05البيانات الوصفية

metadata كائن JSON حتى 20 مفتاحاً يُخزَّن مع المكالمة ويُعاد كما هو في كائن المكالمة وفي كل webhook. استخدمه لتجد طرفك من القصة — order_id أو booking_id أو support_ticket — بدل جدول ربط.

البيانات الوصفية ظاهرة لكل من يقرأ سجل مكالماتك والـ webhooks، فاقتصر على المعرّفات لا البيانات الشخصية.

✓ شكراً، وصلتنا ملاحظتك.

→ السابق دقائق المشاركين التالي ← المكالمات الجماعية