البدء / رموز الانضمام

رموز الانضمام

رمز الانضمام JWT قصير العمر يصدره خادمك لمستخدم واحد للانضمام إلى مكالمة واحدة. التطبيق يسلّمه إلى الـ SDK ولا يرى مفتاحك السري أبداً.

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

01ما هو الرمز

خادمك يستدعي POST /calls/{call_id}/tokens بمعرّف المستخدم واسمه الظاهر. يسجّل صدى المشارك ويعيد JWT بتوقيع HS256 يعيش 5 دقائق افتراضياً (من 60 ثانية إلى ساعة). طرف الصوت يتحقق من التوقيع ومن الحقل exp قبل أن يُدخل المشارك.

ولأن الرمز مرتبط بـ user_ref واحد وcall_id واحد، لا يمكن إعادة استخدامه لمكالمة أخرى، وينتهي قبل أن يتمكن أحد من إعادة إرساله.

02الطلب

أصدر الرموز بعد التحقق من الهوية عندك: المستخدم الذي يطلب الرمز يجب أن يكون هو من تضعه في user_ref.

POST /api/v1/calls/{call_id}/tokens

الاسم	النوع	إلزامي	الافتراضي	الوصف
`user_ref`	`string ≤ 120`	نعم	`—`	معرّفك للمستخدم (معرّف قاعدة البيانات، UUID…). يظهر في الـ webhooks وسجل المكالمات.
`display_name`	`string ≤ 80`	نعم	`—`	ما يراه بقية المشاركين. الأسماء العربية مقبولة.
`ttl`	`integer 60–3600`	لا	`300`	عمر الرمز بالثواني. يجب أن ينضم التطبيق قبل انتهائه.

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

-H "Authorization: Bearer sk_test_4vN8kR2pXa61Jd0s" \

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

-d '{"user_ref": "u_1842", "display_name": "محمود عباس", "ttl": 300}'

03الاستجابة

تحمل الاستجابة الرمز ووقت انتهائه وسجل المشارك الذي أُنشئ له.

الاستجابة

1 {

2 "message": "Join token issued successfully",

3 "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzYWRhIiwic3ViIjoidV8xODQyIiwi…",

4 "expires_at": "2026-10-21T09:35:00.000000Z",

5 "participant": {

6 "user_ref": "u_1842",

7 "display_name": "محمود عباس",

8 "platform": null,

9 "muted": false,

10 "latency_ms": null,

11 "loss_pct": null,

12 "jitter_ms": null,

13 "joined_at": "2026-10-21T09:30:04.000000Z",

14 "left_at": null

15 }

16 }

04داخل الرمز

الـ SDK يفكّ الحمولة ليعرف أي مكالمة وأي منطقة يتصل بها. لا تحتاج إلى فكّها بنفسك، لكنها غير مشفّرة — لا تضع أي شيء خاص في display_name.

payload

1 {

2 "iss": "sada",

3 "sub": "u_1842",

4 "name": "محمود عباس",

5 "call_id": "call_k3j9x2m7qa",

6 "app": "pk_test_7f3a9c2e1b84",

7 "env": "test",

8 "region": "baghdad",

9 "pid": 5812,

10 "iat": 1792315800,

11 "exp": 1792316100

12 }

الحقل	المعنى
`iss`	دائماً `sada`.
`sub`	الـ `user_ref` الخاص بك.
`name`	الاسم الظاهر `display_name`.
`call_id`	المكالمة التي يفتحها هذا الرمز.
`app`	المفتاح العام للتطبيق في هذه البيئة.
`env`	`test` أو `live`.
`region`	`baghdad` أو `dubai` أو `istanbul`.
`pid`	معرّف المشارك الذي عيّنه صدى.
`iat`	وقت الإصدار (ثوانٍ unix).
`exp`	وقت الانتهاء (ثوانٍ unix).

05القواعد

أمور يفرضها الـ API عند إصدار الرمز.

1 رمز واحد لكل مشارك. إصدار الرمز ينشئ سجل المشارك ويرسل participant.joined إلى الـ webhooks — والرمز الثاني في المكالمة الفردية هو ما ينقلها من ringing إلى in_progress.
2 تتسع المكالمة لمشاركَين نشطَين على الأكثر إن كانت one_to_one ولعشرة إن كانت group. بعد ذلك يردّ الـ API بـ 422 Call is full. من يغادر يحرّر مقعده.
3 الرموز تُصدر فقط للمكالمات الحيّة (ringing أو in_progress). المكالمة المنتهية أو الفائتة تردّ بـ 422 Call is not live.
4 الرمز موقّع من صدى. تدوير مفتاحك السري لا يُبطل الرموز الصادرة من قبل.

06عبر حزم SDK

حزمة Laravel تغلّف المسار في $call->token()؛ وبدون SDK هو طلب HTTP واحد.

app/Http/Controllers/CallController.php

1 $token = $call->token($request->user()->id, ttl: 300, displayName: 'محمود عباس');

3 return response()->json([

4 'call_id' => $call->id,

5 'token' => $token, // hand this to @sada/web or the Flutter SDK

6 ]);

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

2 -H "Authorization: Bearer sk_test_4vN8kR2pXa61Jd0s" \

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

4 -d '{"user_ref": "u_1842", "display_name": "محمود عباس", "ttl": 300}'

1 {