---
title: "تضمين أداة الويب"
description: "أضف وكيلاً صوتياً إلى موقعك التسويقي أو موقع الدعم باستخدام وسم برمجي واحد — يتحدث الزوار إليه مباشرةً من المتصفح، من دون الحاجة إلى رقم هاتف."
---

تمنح أداة الويب زوّار موقعك محادثة بالنقر للتحدث
مع وكيل ذكاء اصطناعي، باستخدام ميكروفون المتصفح. وهي حزمة SDK مستقلة
بلغة JavaScript / React لها [مرجع SDK](/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="إدراج النطاقات المسموح بها">
    سمِّ كل اسم مضيف سيضمّن الأداة. ترسل المتصفحات مصدر
    الصفحة مع كل طلب جلسة، لذا تمنع القائمة مفتاحك
    من العمل عندما ينسخه شخص إلى موقع آخر. هذه ليست
    مصادقة: يمكن لنص برمجي خارج المتصفح إرسال أي ترويسة
    `Origin`. لا يُسمح بـ `localhost` تلقائيًا في بيئة الإنتاج؛ لاختباره محليًا
    مقابل واجهة برمجة التطبيقات للإنتاج، أضف `localhost` إلى
    القائمة.
  </Step>
  <Step title="اختيار تجاوزات المتصفح">
    حدّد إعدادات الجلسة التي يمكن لصفحتك إرسالها. لا تقبل المفاتيح الجديدة
    أيًا منها؛ راجع [تجاوزات المتصفح](#browser-overrides).
  </Step>
</Steps>

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

<CodeGroup>
```bash Static agent
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"],
    "allowed_overrides": ["context"]
  }'
```

```bash Dynamic via webhook
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>

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

تغطي [وثائق SDK للأداة](/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` | `context` | نص من الصفحة، يُلحق بموجّه الوكيل كمرجع |
| `variables` | لا يوجد (طلب `POST /v1/widget/session` خام فقط) | قيم للعناصر النائبة `{{variable}}` في الموجّه |
| `voice` | `voice` | صوت الوكيل لهذه الجلسة |
| `language` | `language` | اللغة التي تبدأ بها الجلسة |

مفتاحك القابل للنشر عام، لذا يمكن لأي شخص يملكه إرسال هذه
الإعدادات، بما في ذلك من نص برمجي ينتحل نطاقك. ولذلك يكون كل إعداد
معطلاً إلى أن تسمح به على المفتاح: فعِّله ضمن **تجاوزات المتصفح** عند إنشاء
الأداة أو تعديلها في لوحة التحكم، أو اضبط
`allowed_overrides` عبر
[واجهة برمجة تطبيقات المفاتيح القابلة للنشر](/api-reference/publishable-keys). اسمح فقط بما
ترسله صفحتك فعلياً.

يفشل طلب الجلسة الذي يحمل إعدادًا لا يسمح به المفتاح
برمز `400` ويذكر اسمه:

```json
{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}
```

ينطبق الفحص في كلا الوضعين. في وضع webhook، يُعاد توجيه الإعداد المسموح به
أيضًا إلى webhook `web.incoming` الخاص بك (يصل `context` باسم
`website_context`). تسمح المفاتيح التي أُنشئت قبل وجود هذا الإعداد بالإعدادات
الأربعة كلها، لذا تستمر التضمينات الحالية في العمل؛ عطّل ما لا تستخدمه.

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

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

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

```json
{
  "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="مرجع Widget 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="واجهة برمجة تطبيقات جلسات الميكروفون" icon="microphone" href="/api-reference/mic-sessions">
    تجاوز الودجت؛ واستخدم LiveKit مباشرةً لواجهات مستخدم مخصصة.
  </Card>
</CardGroup>