صدى
English لوحة التحكم
حزم SDK / Laravel

Laravel

sada/laravel تغلّف الـ REST API في facade — إنشاء المكالمات، إصدار الرموز، القائمة، الإنهاء — وتضيف ميدل وير يتحقق من توقيع الـ webhooks عنك.

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

01التثبيت والإعداد

اطلب الحزمة واضبط ثلاثة متغيرات بيئة. ملف الإعداد يُنشر إلى config/sada.php إن أردت تغيير الافتراضيات.

$ composer require sada/laravel
$ php artisan vendor:publish # pick the Sada config → config/sada.php (optional)
.env
SADA_SECRET_KEY=sk_test_4vN8kR2pXa61Jd0s
SADA_BASE_URL=https://sada.g4t.io
SADA_WEBHOOK_SECRET=whsec_Q7mX2pLr9vB4nK8sT1wZ5yH3cJ6dF0gA

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

Sada::calls()->create() يأخذ حقول POST /calls نفسها ويعيد Sada\Laravel\Call. كل حقل في كائن المكالمة خاصية عليه.

app/Http/Controllers/CallController.php
1 use Sada\Laravel\Facades\Sada;
2
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 ]);
9
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

03إصدار رمز انضمام

$call->token() يعيد نص الـ JWT لـ SDK العميل. استدعِه بعد التحقق من الهوية عندك، مرة لكل مشارك، وأعده إلى التطبيق.

app/Http/Controllers/CallController.php
1 $token = $call->token($request->user()->id, ttl: 300, displayName: 'محمود عباس');
2
3 return response()->json([
4 'call_id' => $call->id,
5 'token' => $token, // hand this to @sada/web or the Flutter SDK
6 ]);

04القائمة والجلب والإنهاء

بقية الـ API دالة لكل مسار. list() يقبل مرشّحات GET /calls نفسها ويعيد data وmeta.

app/Http/Controllers/CallController.php
1 $calls = Sada::calls()->list(['status' => 'ringing', 'per_page' => 20]);
2 $calls['data']; // Sada\Laravel\Call[]
3 $calls['meta']; // current_page, per_page, total, …
4
5 $call = Sada::calls()->get('call_k3j9x2m7qa');
6
7 $call = Sada::calls()->end('call_k3j9x2m7qa', ['reason' => 'hangup']);
8 $call->end(); // the same, on an instance

05استقبال الـ webhooks

سجّل الميدل وير sada.webhook ‏(Sada\Laravel\Http\Middleware\VerifyWebhookSignature) على مسارك: يردّ بـ 401 على التوقيع الخاطئ أو القديم باستخدام SADA_WEBHOOK_SECRET. ثم اقرأ الحدث بـ Webhook::fromRequest().

routes/api.php
1 use Illuminate\Http\Request;
2 use Sada\Laravel\Webhook;
3
4 Route::post('/webhooks/sada', function (Request $request) {
5 $webhook = Webhook::fromRequest($request);
6
7 match ($webhook->event) {
8 'call.ended' => Order::where('call_id', $webhook->callId)
9 ->update(['call_minutes' => $webhook->data['participant_minutes']]),
10 'call.missed' => MissedCallNotification::send($webhook->callId),
11 default => null,
12 };
13
14 return response()->noContent();
15 })->middleware('sada.webhook');

للتحقق يدوياً — داخل مهمة في الطابور مثلاً — استخدم Signature::verify() مع الجسم الخام.

app/Http/Controllers/SadaWebhookController.php
1 use Sada\Laravel\Webhooks\Signature;
2
3 $ok = Signature::verify(
4 $request->getContent(), // the raw body — never re-encode it
5 $request->header('X-Sada-Signature'),
6 $secret, // SADA_WEBHOOK_SECRET
7 tolerance: 300,
8 );
9
10 abort_unless($ok, 401);

06الأخطاء

كل استجابة غير 2xx ترمي Sada\Laravel\Exceptions\ApiException مع حالة HTTP ورسالة الـ API، ولأخطاء التحقق الأخطاء مفهرسة بالحقل.

app/Http/Controllers/CallController.php
1 use Sada\Laravel\Exceptions\ApiException;
2
3 try {
4 $token = $call->token($userRef);
5 } catch (ApiException $e) {
6 $e->status; // 422
7 $e->getMessage(); // "Call is full"
8 $e->errors; // validation errors keyed by field, or []
9 }

07الإعداد

متغيرات البيئة التي يقرأها config/sada.php.

المتغيّرالافتراضيالوصف
SADA_SECRET_KEY — المفتاح السري للتطبيق، تجريبي أو فعلي.
SADA_BASE_URL https://sada.g4t.io أصل الـ API. غيّره فقط لبيئة staging من صدى.
SADA_WEBHOOK_SECRET — سرّ التوقيع من لوحة التحكم ← Webhooks، يستخدمه sada.webhook.
✓ شكراً، وصلتنا ملاحظتك.
→ السابق JavaScript التالي ← Node.js