> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkiasoft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ربط القنوات من داخل منتجك

> دع مستخدميك يربطون واتساب وماسنجر وانستجرام وتيك توك من داخل تطبيقك، عبر نافذة تسجيل دخول نستضيفها نحن.

إن كنت تبني على Linkiasoft، فلا ينبغي أن يغادر مستخدموك منتجك لربط رقم واتساب أو صفحة فيسبوك. تمنحك **جلسة الربط** رابطًا يُستخدم مرة واحدة لصفحة نستضيفها. تفتحه في نافذة منبثقة، فيسجّل الشخص دخوله عبر ميتا أو تيك توك هناك، وتعود النتيجة إلى نافذتك.

لن تتعامل أبدًا مع بيانات اعتماد ميتا أو تيك توك، ولا تحتاج إلى تطبيق ميتا خاص بك.

| المنصة | `platform` | تسجيل الدخول عبر |
| - | - | - |
| واتساب للأعمال | `whatsapp` | فيسبوك — رقم جديد، أو تطبيق واتساب للأعمال الموجود على الهاتف |
| واتساب (رمز QR) | `whatsapp_qr` | بلا تسجيل دخول — يمسح الشخص رمز QR أو يُدخل رمز ربط على الهاتف، كما في واتساب ويب |
| ماسنجر | `facebook` | فيسبوك — يختار الشخص صفحة واحدة |
| انستجرام | `instagram` | حساب انستجرام احترافي |
| تيك توك | `tiktok` | حساب تيك توك |

**تُنشأ القناة دائمًا في مساحة العمل التي يملكها مفتاح API.** ولا تستطيع جلسة الربط إضافة قناة في أي مكان آخر.

## كيف يعمل

**1. الخادم لديك ينشئ جلسة**

استدعِ [`POST /v1/connect-sessions`](https://docs.linkiasoft.com/api-reference/connect-sessions/create-a-connect-link) بمفتاح يحمل الصلاحية `channels:manage`، فتحصل على `connectUrl`.

**2. الواجهة لديك تفتحه في نافذة منبثقة**

تنتقل النافذة مباشرة إلى ميتا أو تيك توك لتسجيل الدخول. ومع `whatsapp_qr` تعرض رمز QR للمسح بدلًا من ذلك.

**3. النافذة تبلّغ بالنتيجة ثم تُغلق**

ترسل النتيجة إلى نافذتك عبر `postMessage`، أو تنتقل إلى `redirectUri` إن لم تكن هناك نافذة تُبلَّغ.

**4. الخادم لديك يتحقق**

اقرأ [`GET /v1/connect-sessions/{id}`](https://docs.linkiasoft.com/api-reference/connect-sessions/get-a-connect-session)، أو اشترك في حدث [Webhook](https://docs.linkiasoft.com/ar/webhooks.md) المسمى `connect_session.completed`. سجل الخادم هو المرجع، ورسالة المتصفح مجرد إشارة.

## 1. أنشئ جلسة

افعل ذلك على خادمك — فهو يحتاج مفتاح API الخاص بك، ويجب ألا يصل المفتاح إلى المتصفح أبدًا.

```bash theme={null}
curl -X POST https://social.linkiasoft.com/api/v1/connect-sessions \
  -H "x-api-key: lk_live_..." \
  -H "X-Tenant-Id: 8f6a2b3c-4d5e-4a7b-9c1e-3f2b1a9c0d4e" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "whatsapp",
    "origin": "https://app.example.com",
    "state": "user-4821",
    "locale": "ar"
  }'
```

```json theme={null}
{
  "id": "6f1c8e2a-9b4d-4c7e-8a13-2d5f0b7c9e41",
  "platform": "whatsapp",
  "status": "pending",
  "connectUrl": "https://crm.linkiasoft.com/ar/connect#token=cst_...",
  "channelId": null,
  "channelName": null,
  "state": "user-4821",
  "createdAt": "2026-10-22T09:00:00.000Z",
  "expiresAt": "2026-10-22T09:30:00.000Z",
  "completedAt": null
}
```

| الحقل | وظيفته |
| - | - |
| `platform` | إلزامي. `whatsapp` أو `whatsapp_qr` أو `facebook` أو `instagram` أو `tiktok`. |
| `channelName` | مع `whatsapp_qr` فقط. اسم القناة في Linkiasoft. الافتراضي هو الرقم المربوط، مثل `+201001234567`. |
| `origin` | أصل الصفحة التي تفتح النافذة، مثل `https://app.example.com`. تُرسل النتيجة إلى `window.opener` عند هذا الأصل تحديدًا، ولا شيء غيره. |
| `redirectUri` | وجهة النافذة حين لا تكون لها نافذة فاتحة — مثلًا إن أُغلقت صفحتك أو فُتح الرابط في تبويب كامل. |
| `state` | مرجعك الخاص — معرّف مستخدم أو خطوة إعداد. يُعاد إليك كما هو في كل نتيجة. |
| `locale` | `en` (الافتراضي) أو `ar` — لغة الصفحة المستضافة. |

أرسل `origin` أو `redirectUri` أو كليهما. ويجب أن يستخدم كلاهما `https`؛ ولا يُقبل `http` العادي إلا مع `localhost` لتتمكن من الاختبار محليًا.

> [!WARNING]
>
> الرابط `connectUrl` بمثابة بيانات اعتماد. يعمل **مرة واحدة** وتنتهي صلاحيته بعد **30 دقيقة**. أنشئ جلسة جديدة لكل محاولة، ولا تخزّنه مؤقتًا، ولا تكتبه في السجلات. الرمز موجود في جزء الـ fragment من الرابط، فلا يصل بنفسه إلى سجل خادم ولا إلى ترويسة `Referer` — حافظ على ذلك.

## 2. افتح النافذة المنبثقة

افتحها مباشرة من معالج النقرة. فالنافذة التي تُفتح بعد `await` غالبًا ما يحجبها المتصفح.

```javascript theme={null}
async function connectWhatsApp() {
  // افتح النافذة أولًا ثم حمّل الرابط فيها — حتى تبقى داخل النقرة.
  const popup = window.open('', 'linkia_connect', 'width=520,height=720');
  const { connectUrl } = await fetch('/api/linkia/connect-session', { method: 'POST' })
    .then((r) => r.json());
  popup.location.href = connectUrl;
}

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://crm.linkiasoft.com') return;
  if (event.data?.source !== 'linkia-connect') return;

  const { sessionId, status, platform, channelId, channelName, state } = event.data;
  // status: 'connected' | 'cancelled'
  confirmOnServer(sessionId);
});
```

تحقق دائمًا من `event.origin`. فأي صفحة تستطيع إرسال رسالة إلى نافذتك؛ ورسالتنا وحدها هي القادمة من `https://crm.linkiasoft.com` وتحمل `source: 'linkia-connect'`.

### دون نافذة فاتحة: إعادة التوجيه

حين لا تستطيع النافذة الوصول إلى نافذتك، تنتقل إلى `redirectUri` والنتيجة في سلسلة الاستعلام:

```
https://app.example.com/done?sessionId=6f1c…&status=connected&channelId=b21e…&state=user-4821
```

وتبقى معاملات الاستعلام الموجودة لديك كما هي.

## 3. تحقق على خادمك

```bash theme={null}
curl https://social.linkiasoft.com/api/v1/connect-sessions/6f1c8e2a-9b4d-4c7e-8a13-2d5f0b7c9e41 \
  -H "x-api-key: lk_live_..." \
  -H "X-Tenant-Id: 8f6a2b3c-4d5e-4a7b-9c1e-3f2b1a9c0d4e"
```

| `status` | المعنى |
| - | - |
| `pending` | لم تنتهِ بعد. |
| `connected` | تمّت. و`channelId` هو القناة الجديدة — استخدمه في أي مكان يطلب فيه هذا الـ API قيمة `channelId`. |
| `cancelled` | ضغط الشخص **إلغاء**، أو [ألغيت أنت الجلسة](https://docs.linkiasoft.com/api-reference/connect-sessions/cancel-a-connect-session.md). |
| `expired` | انتهت مهلة الرابط (30 دقيقة) قبل أن يُنهي الشخص. أنشئ جلسة جديدة. |

تبقى الجلسة متاحة للقراءة **24 ساعة**.

إن أغلق الشخص النافذة ببساطة فلن يُرسل شيء — وتبقى الجلسة `pending` حتى تنتهي صلاحيتها. اعتبر النافذة المغلقة دون رسالة "لم يتم الربط"، ودعه يحاول مجددًا.

### أو استمع إلى الـ Webhook

اشترك بنقطة نهاية في `connect_session.completed` من **التكاملات ← Webhooks**. يُطلق الحدث حين تنتهي الجلسة بـ `connected` أو `cancelled`:

```json theme={null}
{
  "event": "connect_session.completed",
  "source": "social",
  "data": {
    "session_id": "6f1c8e2a-9b4d-4c7e-8a13-2d5f0b7c9e41",
    "status": "connected",
    "platform": "whatsapp",
    "channel_id": "b21e7d40-3a55-4f89-9c02-77ab1e6d3c88",
    "channel_name": "Acme Support",
    "state": "user-4821"
  }
}
```

والجلسات التي تنتهي صلاحيتها دون استخدام لا تُطلقه.

## أمور ينبغي معرفتها

**جلسة واحدة، قناة واحدة.** إن شمل تسجيل دخول الشخص إلى فيسبوك عدة صفحات، فإنه يختار واحدة. وشغّل جلسة أخرى للصفحة التالية.

**قواعد مساحة العمل ما زالت سارية.** تُرفض الجلسة مسبقًا بـ `403` إن لم تكن مساحة عملك مفعّلة للربط المباشر مع ميتا لنوع القناة هذا، ويفشل الربط نفسه إن بلغت الخطة حدّ القنوات. وتعرض النافذة السبب للشخص.

**إعادة الربط هي الاستدعاء نفسه.** ربط رقم أو صفحة أو حساب موجود أصلًا كقناة في مساحة عملك يحدّثه بدل أن يضيف نسخة مكررة — ويكون `channelId` هو معرّف القناة الموجودة.

**قد ينتهي واتساب بتحذير.** إن حفظت ميتا الرقم لكنها لم تسجّله في Cloud API بعد، فستظل الجلسة تُبلغ `connected` وتظهر القناة في Linkiasoft على أنها تحتاج إجراءً. تحقق من `connection_status` الخاص بها عبر [`GET /v1/connect/channels`](https://docs.linkiasoft.com/api-reference/channels/list-your-connected-channels) قبل الإرسال.

**واتساب عبر رمز QR.** مع `whatsapp_qr` تعرض النافذة رمز QR فورًا؛ يفتح الشخص واتساب ← الإعدادات ← الأجهزة المرتبطة ← ربط جهاز ويمسحه. ويقدّم تبويب *استخدام رقم الهاتف* رمز ربط من 8 أحرف بدلًا من ذلك، حين يكون الهاتف هو الشاشة الوحيدة. يظل الرقم يعمل في تطبيق واتساب كما كان. هذا ربط غير رسمي (واتساب ويب)، فلا يمكنه إرسال قوالب رسائل واتساب — استخدم `whatsapp` حين تحتاجها. يُتحقق من حد القنوات في الخطة عند إنشاء الجلسة، فتحصل مساحة العمل الممتلئة على `403` قبل أن تُفتح النافذة.

**حاجبات النوافذ المنبثقة.** يجري كل شيء داخل النافذة المنبثقة الواحدة التي تفتحها: يُحمَّل تسجيل الدخول لدى المزوّد في النافذة نفسها ثم يعود إلى صفحتنا، فلا تُفتح نافذة ثانية. افتح النافذة عند نقرة الشخص (لا بعد `await`) لتسمح بها الحاجبات.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.