أضف مكالمات فيديو ورسائل
لأي موقع في 5 دقائق.

1. بداية سريعة (5 دقائق)

ثلاث خطوات من الصفر إلى مكالمة فيديو حية على موقعك.

الخطوة 1 — احصل على مفاتيح API

راسل partners@tkawen.com برابط موقعك لتستلم زوج pk_live_… + sk_live_…

الخطوة 2 — على الخادم: تبادل الهوية بـSDK token

في كل تحميل صفحة (من جهة الخادم)، وقّع هوية المستخدم بـsk_live_ وتبادلها بتوكن قصير الصلاحية (ساعة واحدة) آمن للمتصفح. لا تكشف sk_live_ للمتصفح أبداً.

php
// PHP example
$pk = 'pk_live_xxxxx';
$sk = 'sk_live_xxxxx';
$user = ['email' => 'jane@yoursite.com', 'name' => 'Jane Doe'];
$identity = base64_encode(json_encode([
    'email' => $user['email'],
    'name'  => $user['name'],
    'ts'    => time(),
]));
$signature = hash_hmac('sha256', $identity, $sk);

$ch = curl_init('https://liqaa.io/api/public/v1/sdk-token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $sk, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'public_key'      => $pk,
        'identity_base64' => $identity,
        'signature'       => $signature,
    ]),
]);
$res = json_decode(curl_exec($ch), true);
$sdkToken = $res['sdk_token'];

javascript
// Node.js example
const crypto = require('crypto');
const fetch = require('node-fetch');

const pk = 'pk_live_xxxxx';
const sk = 'sk_live_xxxxx';
const identity = Buffer.from(JSON.stringify({
  email: user.email, name: user.name, ts: Math.floor(Date.now()/1000),
})).toString('base64');
const signature = crypto.createHmac('sha256', sk).update(identity).digest('hex');

const r = await fetch('https://liqaa.io/api/public/v1/sdk-token', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + sk, 'Content-Type': 'application/json' },
  body: JSON.stringify({ public_key: pk, identity_base64: identity, signature }),
});
const { sdk_token } = await r.json();

الخطوة 3 — على المتصفح: اختر طريقة التثبيت

الخيار A — npm (مشاريع TypeScript، React، bundlers):

bash
npm install @liqaa/js

javascript
import { LIQAA } from '@liqaa/js';

const liqaa = await LIQAA.init({
  publicKey: 'pk_live_xxxxx',
  sdkToken:  sdkToken,            // from your server
  accent:    '#1d4ed8',
});

document.querySelector('#call-btn')!.addEventListener('click', () => {
  liqaa.startCall('support@yoursite.com', 'Support');
});

تستعمل React؟ استعمل @liqaa/react للـhooks والـcomponents:

bash
npm install @liqaa/react @liqaa/js

tsx
import { LIQAAProvider, LIQAACallButton } from '@liqaa/react';

<LIQAAProvider publicKey={pk} sdkToken={token}>
  <LIQAACallButton email="support@yoursite.com">
    Talk to Support
  </LIQAACallButton>
</LIQAAProvider>

الخيار B — script جاهز (بدون تثبيت، HTML خام / WordPress / إلخ.):

html
<!-- Anywhere in your HTML -->
<script src="https://liqaa.io/sdk.js"
        data-key="pk_live_xxxxx"
        data-token="<%= sdkToken %>"
        data-accent="#1d4ed8"
        data-position="right"></script>

<!-- Trigger anywhere on your page -->
<button onclick="LIQAA.startCall('support@yoursite.com', 'Support')">
  Talk to Support
</button>

في الحالتين، يظهر زر عائم في أسفل اليمين. النقر على زرّك يبدأ مكالمة فيديو داخل موقعك (بدون توجيه خارجي).

2. مرجع JS SDK

سمات وسم Script

3. REST API

وصول مباشر للـAPI للتكاملات server-to-server. صادق باستخدام Authorization: Bearer sk_live_…

مثال: إنشاء مكالمة من الخادم

bash
curl -X POST https://liqaa.io/api/public/v1/conversations \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "caller_email": "agent@yoursite.com",
    "caller_name":  "Support Agent",
    "callee_email": "customer@example.com",
    "callee_name":  "Customer X",
    "external_conversation_id": "ticket-42"
  }'

# Response (201 created or 200 if reused):
{
  "ok": true,
  "reused": false,
  "room_name": "room-abc123",
  "join_url":  "https://liqaa.io/meeting/room-abc123",
  "embed_url": "https://liqaa.io/embed/room-abc123",
  "expires_at": "2026-04-30T18:00:00+00:00"
}

4. Webhooks

اشترك بالأحداث لإبقاء تطبيقك متزامناً. نوقّع كل payload بـsigning_secret(HMAC-SHA256). التسليمات الفاشلة تُعاد المحاولة 5 مرات بتراجع أُسّي (5د، 30د، ساعتان، 6س، 24س).

الأحداث المتاحة

• call.started — يُطلق عند إنشاء غرفة جديدة.
• call.ended — يُطلق عند انتهاء الغرفة (DELETE أو timeout).
• call.declined — يُطلق عند رفض المتلقّي للمكالمة.
• message.sent — يُطلق عند إرسال رسالة (قريباً).
• conversation.created — يُطلق عند فتح محادثة دائمة جديدة.
• * — wildcard، اشترك بكل الأحداث.

الاشتراك

bash
curl -X POST https://liqaa.io/api/public/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://yoursite.com/api/webhooks/liqaa",
    "events": ["call.started","call.ended"],
    "description": "Production endpoint"
  }'

# Response (201 created):
{
  "ok": true,
  "data": { "id": 17, "url": "...", "events": [...], "active": true, ... },
  "signing_secret": "whsec_<save-this-now-shown-only-once>"
}

التحقق من التوقيعات

نُرسل X-LIQAA-Signature: t=<timestamp>,v1=<hmac> مع كل webhook. أعد الحساب وقارن بمساواة constant-time.

php
// PHP — verify webhook
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_LIQAA_SIGNATURE'] ?? '';
parse_str(strtr($header, ',', '&'), $parts);
$timestamp = $parts['t'] ?? '';
$received  = $parts['v1'] ?? '';
$expected  = hash_hmac('sha256', $timestamp . '.' . $payload, $signingSecret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}
// Reject replays older than 5 minutes
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}
$event = json_decode($payload, true);
// $event['event'], $event['data'], ...

لماذا LIQAA؟

• بنية تحتية حديثة — موزّعة عالمياً، تأخير منخفض، جاهزة للإنتاج.
• أسعار شفّافة — ادفع وأنت تنمو، طبقة مجانية للأبد، بدون مفاجآت.
• غرف دائمة — نفس المحادثة = نفس الغرفة عبر المكالمات (بدون تشويش لوحة التحكم).
• متعدّدة اللغات — دعم RTL كامل افتراضياً. إنجليزي، عربي، فرنسي، والمزيد.
• LiveKit SFU — WebRTC مُختبر في الإنتاج تحت الغطاء.
• جاهز للدمج — وسم script واحد، 10 دقائق للدمج.
• أمان بمستوى Stripe — فصل pk/sk، webhooks موقّعة، HMAC.