---
title: "أداة صوتية قابلة للتضمين"
description: "أضف وكيلاً صوتياً بالذكاء الاصطناعي إلى أي موقع ويب ببضعة أسطر من التعليمات البرمجية"
---

تتيح أداة ThunderPhone الصوتية القابلة للتضمين لزوّار موقعك التحدث إلى وكيل ذكاء اصطناعي مباشرةً من المتصفح. لا حاجة إلى مكالمة هاتفية -- ينقر المستخدمون زرًا ويبدؤون محادثة صوتية في الوقت الفعلي مدعومة من ThunderPhone.

تُعرض الأداة كشريط بتأثير زجاجي يتكيف مع النسقين الفاتح والداكن، مع ألوان تمييز وموضع قابلين للتخصيص. تُوزَّع كحزمة npm باسم `@thunderphone/widget`، وهي متاحة أيضًا عبر CDN للبيئات التي لا تستخدم أدوات تجميع الحزم.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

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

قبل تضمين الأداة، أكمل هذه الخطوات الثلاث في [لوحة تحكم ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="إنشاء أداة ويب">
  انتقل إلى **أدوات الويب** في لوحة التحكم وأنشئ أداة. اختر الوكيل الذي تريد إتاحته. لكل أداة مفتاح قابل للنشر خاص بها (`pk_live_...`) وآمن تضمينه في التعليمات البرمجية من جهة العميل؛ يُحدَّد الوكيل من المفتاح.
</Step>

<Step title="تهيئة النطاقات المسموح بها">
  في الأداة نفسها، أضف النطاقات التي ستُضمَّن فيها. تُدعَم أحرف البدل (مثل `*.example.com`). تمنع القائمة عمل الأداة عندما ينسخ شخص مفتاحك إلى موقع آخر؛ وهي ليست مصادقة، إذ يمكن لنص برمجي خارج المتصفح إرسال أي ترويسة `Origin`. لا يُسمح بـ `localhost` تلقائيًا في بيئة الإنتاج: أضِفه إلى القائمة للاختبار محليًا باستخدام واجهة برمجة التطبيقات للإنتاج.
</Step>

<Step title="اختيار تجاوزات المتصفح">
  إذا كانت صفحتك تضبط `language` أو `voice` أو `context`، ففعّل كلًّا منها ضمن **تجاوزات المتصفح**. لا تقبل الأدوات الجديدة أيًا منها، ويفشل طلب الجلسة الذي يتضمن إعدادًا غير مفعّل بالخطأ `400 override_not_allowed`. راجع [تجاوزات المتصفح](/ar/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  المفاتيح القابلة للنشر (`pk_live_...`) **ليست** نفسها رموز API السرية الخاصة بك. صُممت المفاتيح القابلة للنشر للاستخدام من جانب العميل، ويقتصر نطاقها على جلسات الأداة ضمن نطاقاتك المسموح بها. لا تستخدم رمز API السري مطلقًا في التعليمات البرمجية من جانب العميل.
</Warning>

<Note>
  تنتهي جلسات الأداة بعد 30 دقيقة افتراضيًا، أو قبل ذلك إذا كانت مدة المكالمة القصوى الخاصة بالوكيل أقصر. غيّر الحد لكل مفتاح باستخدام `max_call_duration_seconds` في [المفتاح القابل للنشر](/api-reference/publishable-keys) (حتى 6 ساعات)، أو اضبطه على `null` لاستخدام حد الوكيل الخاص.
</Note>

---

## البدء السريع

ثبّت الحزمة:

```bash
npm install @thunderphone/widget
```

أضف الأداة إلى تطبيقك:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

هذا كل شيء. سيرى مستخدموك شريط اتصال بتأثير زجاجي يربطهم بوكيل الذكاء الاصطناعي الخاص بك بنقرة واحدة.

---

## التخصيص

تحتوي الأداة على أربع خصائص للمظهر:

| الخاصية | القيمة الافتراضية | الوصف |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` للزجاج الأبيض، و`'dark'` للزجاج الداكن |
| `primaryColor` | `'#000000'` (فاتح) / `'#ffffff'` (داكن) | لون التمييز لزر البدء وشكل الموجة ومؤشر الاتصال |
| `title` | `'Voice assistant'` | النص المعروض في الأداة |
| `position` | `'bottom-right'` | زاوية إطار العرض: `'bottom-right'`، `'bottom-left'`، `'top-right'`، `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

تخصص ثلاث خصائص إضافية الجلسة بدلًا من المظهر -- وتُمرَّر جميعها إلى طلب الجلسة عند بدء مكالمة. لا تعمل كل منها إلا إذا كان المفتاح القابل للنشر للأداة يسمح بها ضمن **تجاوزات المتصفح**؛ وإلا يفشل طلب الجلسة بالرمز `400 override_not_allowed`:

| الخاصية | الوصف |
|------|-------------|
| `language` | تجاوز لغة لكل جلسة -- رمز أو إعدادات محلية مثل `en` أو `es` أو `fr-FR` |
| `voice` | تجاوز صوت لكل جلسة -- اسم صوت مثل `maria` |
| `context` | سياق واقعي للصفحة أو الموقع يُمرَّر إلى الوكيل (يُقتطع على جانب الخادم إلى 12,000 حرف) |

راجع [مرجع مكوّن React](/ar/widget/react) للاطلاع على جدول الخصائص الكامل.

لإنشاء واجهة مستخدم مخصصة بالكامل، استخدم [الخطاف بلا واجهة](/ar/widget/headless-hook) لإدارة الجلسة الصوتية أثناء بناء واجهتك الخاصة. يوفّر الخطاف مستويات الصوت في الوقت الفعلي لإنشاء تصورات مرئية تتفاعل مع الصوت.

كل محادثة في الأداة هي مكالمة. وتُحتسب ضمن [حد المكالمات المتزامنة](/api-reference/introduction#call-limits) لمؤسستك (20 مكالمة قيد التنفيذ افتراضيًا، مشتركة مع مكالمات الهاتف والمكالمات الأخرى) وضمن حد الأداة البالغ 25 جلسة نشطة (أو حد المكالمات المتزامنة لديك، إذا كان أعلى). عند بلوغ أي من الحدين، لا يمكن بدء محادثة جديدة حتى تنتهي مكالمة.

---

## خيارات التكامل

اختر طريقة التكامل التي تناسب منظومتك:

<CardGroup cols={3}>
  <Card title="مكوّن React" icon="react" href="/ar/widget/react">
    مكوّن واجهة مستخدم جاهز مسبقًا مع عناصر تحكم مدمجة بالمكالمات وعرض للحالة. استورده، مرّر الخصائص، وانتهى الأمر.
  </Card>
  <Card title="خطاف Headless" icon="code" href="/ar/widget/headless-hook">
    تحكم كامل في واجهة المستخدم. يدير الخطاف `useThunderPhone` الجلسة الصوتية بينما تنشئ واجهتك الخاصة.
  </Card>
  <Card title="وسم CDN / Script" icon="globe" href="/ar/widget/cdn-script-tag">
    لا حاجة إلى أداة تجميع. حمّل الأداة عبر وسم script للمواقع الثابتة وWordPress والبيئات الأخرى غير المعتمدة على React.
  </Card>
</CardGroup>

---

## التنسيق

تأتي الأداة مع سمات فاتحة وداكنة مدمجة يتحكم بها الخاصية `theme`، ولون تمييز يتحكم به الخاصية `primaryColor`. ولتخصيص أعمق، يمكنك تجاوز خصائص وفئات CSS المخصصة. راجع [دليل التنسيق](/ar/widget/styling) للتفاصيل.

<Note>
  هل تحتاج إلى مساعدة؟ تواصل معنا عبر [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>