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

# تضمين أداة الويب

> أضف وكيلاً صوتياً إلى موقعك للتسويق أو الدعم — دون الحاجة إلى رقم هاتف.

توفّر أداة الويب لزوار موقعك محادثة بالنقر للتحدث
مع وكيل ذكاء اصطناعي، باستخدام ميكروفون المتصفح. وهي حزمة تطوير برمجيات منفصلة لـ
JavaScript / React ولها [مرجع حزمة تطوير البرامج](/ar/widget/overview) الخاص بها
— يركّز هذا الدليل على الإعدادات في ThunderPhone التي تحتاجها أداة الويب.

<Note>
  يمكنك تنفيذ كل ذلك دون cURL: إذ تنشئ صفحة لوحة التحكم **أدوات الويب**
  (`/dashboard/web-widgets`) الأداة، وتضبط وضعها ووكيلها، وتدير النطاقات المسموح بها،
  وتزوّدك بمقتطف التضمين.
</Note>

## المتطلبات الأساسية

<Steps>
  <Step title="إنشاء وكيل">
    الوكيل الذي سيشغّل موجّهه وصوته جلسة أداة الويب. اضبط
    `widget_enabled: true` (القيمة الافتراضية).
  </Step>

  <Step title="تحديد وضع التوجيه">
    * `mode="agent"` — وكيل ثابت واحد لكل مفتاح. وهو الأبسط.
    * `mode="webhook"` — يختار خادمك الوكيل لكل زائر عبر
      [خطاف ويب `web.incoming`](/ar/webhooks/call-incoming). استخدم هذا الخيار
      للمستخدمين المسجلين، أو اختبارات A/B، أو التوجيه لكل صفحة.
  </Step>

  <Step title="إدراج النطاقات المسموح بها">
    المفاتيح القابلة للنشر مقيّدة بالأصل. يجب أن تسمّي كل اسم مضيف
    سيضمّن أداة الويب. يُسمح دائمًا بـ `localhost` / `127.0.0.1`
    أثناء التطوير المحلي.
  </Step>
</Steps>

## إنشاء مفتاح قابل للنشر

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

تتضمن الاستجابة `key` يبدأ بـ `pk_live_...`. **المفاتيح القابلة
للنشر عامة حسب التصميم** — ومن الآمن تضمينها في حزمة الواجهة الأمامية.
راجع [مرجع المفاتيح القابلة للنشر](/api-reference/publishable-keys) للاطلاع على
جميع الحقول.

<Warning>
  يجب أن يحتوي `allowed_domains` على إدخال واحد على الأقل. يطابق `*.example.com`
  النطاقات الفرعية (مثل `api.example.com`) ولكنه **لا** يطابق
  النطاق المجرد. تُرفض أحرف البدل المجردة مثل `*` أو `*.*`.
</Warning>

## أضف أداة الويب إلى موقعك

تغطي [وثائق حزمة تطوير أدوات الويب](/ar/widget/overview) ثلاثة خيارات للتكامل:

<CardGroup cols={3}>
  <Card title="مكوّن React" icon="react" href="/ar/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="خطاف بلا واجهة" icon="circle-nodes" href="/ar/widget/headless-hook">
    `useThunderPhone()` لواجهات المستخدم المخصصة.
  </Card>

  <Card title="وسم برنامج CDN النصي" icon="code" href="/ar/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` للمواقع التي لا تستخدم حزمًا.
  </Card>
</CardGroup>

تقبل الخيارات الثلاثة نفسها `publishableKey` وتعرض زر الميكروفون
بالإضافة إلى عنصر الصوت أثناء المكالمة.

يُقتطع `context` الخاص بأداة الويب عند 12,000 حرف (نحو 3,400
رمز من نص إنجليزي نموذجي) ويُحتسب ضمن
[الرسوم الإضافية لحجم الموجّه](/ar/guides/billing-and-topups).

## خطافات ويب وضع أداة الويب

عندما يكون `mode="webhook"`، يستدعي ThunderPhone قيمة `webhook_url` في كل
بداية جلسة بحمولة `web.incoming`. أعد إعداد الوكيل
الذي تريد تشغيله لهذا الزائر — فهو يتبع [مخطط الاستجابة](/ar/webhooks/call-incoming)
نفسه المستخدم في المكالمات الهاتفية:

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

يمكنك دمج السياق من جلستك الخاصة (العميل الذي يتصفح،
والصفحة التي يتصفحها) في الموجّه، وتبديل الوكلاء لكل عملية طرح.

## راقب الجلسات

تظهر جلسات الأداة في
[`GET /v1/calls`](/api-reference/calls#list-calls) مع
`direction="widget"` — وبنفس النص المفرغ والتسجيل والتقييم
والفوترة الخاصة بالمكالمات الهاتفية. رشّح حسب `direction` لإنشاء
لوحة معلومات خاصة بالأداة فقط.

***

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="مرجع SDK الأداة" icon="window-maximize" href="/ar/widget/overview">
    تفاصيل التكامل مع React / hook / CDN.
  </Card>

  <Card title="إعدادات ديناميكية لكل مكالمة" icon="bolt" href="/ar/guides/dynamic-call-config">
    نفّذ تدفق `mode="webhook"` بالكامل.
  </Card>

  <Card title="مرجع المفاتيح القابلة للنشر" icon="key" href="/api-reference/publishable-keys">
    كل حقل في مورد المفتاح.
  </Card>

  <Card title="واجهة API لجلسات الميكروفون" icon="microphone" href="/api-reference/mic-sessions">
    تجاوز الأداة؛ واستخدم LiveKit مباشرةً لواجهات مستخدم مخصصة.
  </Card>
</CardGroup>