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

# Web Callback Widget

> ضمِّن زر «اطلب معاودة الاتصال» جاهزًا في أيّ موقع — دون أن يمسّ أيّ مفتاح API المتصفّح.

أداة معاودة الاتصال عبر الويب هي زرّ جاهز تلصقه في أيّ موقع. ينقر الزائر عليه، ويُدخل رقمه، ويؤكّد رمزًا لمرّة واحدة، فيتّصل به Wave — دون أن يمسّ أيّ مفتاح API المتصفّح أبدًا.

تعمل الأداة فوق [Web Callback](/ar/web-callback): فهي تُجري الاتصال نفسه بنقرة واحدة، لكنّها تنقل المُشغِّل إلى متصفّح الزائر بدلًا من الـ backend الخاصّ بك.

## التضمين

انسخ الشيفرة من لوحة التحكّم (**Web Callback** ← *شيفرة التضمين*) — معرّف مشروعك مُعبّأ لك — والصقها قبل وسم `</body>` الختامي مباشرةً:

```html theme={null}
<script src="https://wave.sa/widget.js"
        data-project-id="YOUR_PROJECT_ID"
        data-api-url="https://api.wave.sa"
        data-lang="ar"
        data-accent="#6b12a8"></script>
```

| السمة                     | مطلوبة | الوصف                                                               |
| ------------------------- | ------ | ------------------------------------------------------------------- |
| `data-project-id`         | ✅      | معرّف مشروعك. عامّ — ولا يعمل إلّا من أصل مسموح به.                 |
| `data-api-url`            | —      | عنوان قاعدة Wave API. الافتراضيّ `https://api.wave.sa`.             |
| `data-recaptcha-site-key` | —      | مفتاح موقع reCAPTCHA v3. يُفعّل الحماية من الروبوتات (انظر أدناه).  |
| `data-lang`               | —      | `en` أو `ar`. تُعرض العربيّة من اليمين إلى اليسار. الافتراضيّ `en`. |
| `data-accent`             | —      | لون تمييز الزرّ واللوحة (أيّ لون CSS).                              |
| `data-button-text`        | —      | تجاوز نصّ الزرّ (الافتراضيّ: «اتصل بي»).                            |

## كيف تعمل

<Steps>
  <Step title="يطلب الزائر معاودة الاتصال">
    ينقر الزرّ ويُدخل رقم جوّاله السعوديّ.
  </Step>

  <Step title="يؤكّد رمزًا لمرّة واحدة">
    يُرسل Wave رمزًا عبر SMS، فيُدخله الزائر. هذا يُثبت ملكيّته للرقم، فلا يمكن
    استخدام الأداة للاتصال بشخص غريب أبدًا.
  </Step>

  <Step title="يتّصل به Wave">
    عند رمز صحيح، يُجري Wave معاودة الاتصال. تظهر المكالمة في **Call Logs**
    وتُطلق [webhooks](/ar/webhooks) كأيّ مكالمة أخرى.
  </Step>
</Steps>

<Note>
  **لا مفتاح API في المتصفّح.** تتحدّث الأداة فقط إلى نقاط النهاية العامّة
  `/v1/public/widget/*` المحدّدة بمعرّف مشروعك العامّ `project_id`. تبقى مفاتيح
  الـ API السرّيّة على خوادمك.
</Note>

## الأصول المسموح بها

تُرفض الأداة في كلّ مكان حتّى تُدرج المواقع التي تُضمّنها. أضِف أصل كلّ موقع في
لوحة التحكّم ضمن **Web Callback** ← *الأصول المسموح بها* (مثل
`https://www.your-site.com`). يُرفض أيّ طلب من أصل آخر بالرمز
`403 WIDGET_ORIGIN_NOT_ALLOWED`.

<Warning>
  الأصل هو المخطّط + المضيف + المنفذ الاختياريّ، **دون مسار** — مثل
  `https://shop.example.com`، لا `https://shop.example.com/contact`. لا يُقبل
  إلّا HTTPS (باستثناء `http://localhost` للتطوير المحلّيّ).
</Warning>

## reCAPTCHA (مُوصى به للإنتاج)

بما أنّ الأداة قد تصرف مالًا (كلّ معاودة اتصال مكالمة حقيقيّة)، نوصي بإضافة
Google reCAPTCHA v3. أنشئ زوج مفاتيح v3، ثمّ أضِف مفتاح الموقع إلى الشيفرة:

```html theme={null}
<script src="https://wave.sa/widget.js"
        data-project-id="YOUR_PROJECT_ID"
        data-recaptcha-site-key="YOUR_RECAPTCHA_SITE_KEY"></script>
```

يتحقّق Wave من الرمز على الخادم عند أوّل طلب رمز. وباجتماعه مع الرمز لمرّة واحدة
وقائمة الأصول المسموح بها، يُبعد ذلك إساءة الاستخدام الآليّة.

## التخصيص

* **اللغة والاتجاه** — `data-lang="ar"` يبدّل الأداة إلى العربيّة ويقلبها من
  اليمين إلى اليسار.
* **اللون** — `data-accent` يُنسّق الزرّ واللوحة.
* **النصّ** — `data-button-text` يتجاوز نصّ الزرّ.

الأداة سكربت واحد قائم بذاته دون أيّ اعتماديّات خارجيّة وبأنماط مُسبَقة، فلا
يتعارض مع CSS موقعك.