> ## 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.

# البدء السريع (API)

> أجب عن أول مكالمة هاتفية لك باستخدام وكيل صوتي بالذكاء الاصطناعي عبر أربع استدعاءات REST.

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

<Info>
  ستحتاج إلى [حساب ThunderPhone](https://app.thunderphone.com).
  التسجيل مجاني ويستغرق أقل من دقيقة. هل تفضّل النقر بدل استخدام curl؟
  يوصلك [البدء السريع من لوحة التحكم](/ar/quickstart-dashboard) إلى المكالمة
  الأولى نفسها دون كتابة أي تعليمات برمجية.
</Info>

## الخطوة 1: الحصول على مفتاح API

<Steps>
  <Step title="تسجيل الدخول">
    افتح [app.thunderphone.com](https://app.thunderphone.com).
  </Step>

  <Step title="الانتقال إلى المفاتيح">
    انتقل إلى **المؤسسة ← المفاتيح** في لوحة التحكم.
  </Step>

  <Step title="إنشاء مفتاح">
    انقر على **إنشاء مفتاح**، وأعطه اسمًا، ثم انسخ قيمة
    `sk_live_...`. يظهر المفتاح الخام **مرة واحدة فقط** — خزّنه
    في مدير الأسرار لديك فورًا.
  </Step>
</Steps>

<Tip>
  هل تواجه مشكلة؟ يشرح [إنشاء مفتاح API للخادم](/ar/guides/api-keys)
  هذا المسار خطوة بخطوة بالتفصيل، ويمكن للمساعد المرافق داخل التطبيق
  إبراز كل عنصر تحكم لك مباشرةً.
</Tip>

في هذا الدليل، استبدل `sk_live_YOUR_API_KEY` بالقيمة التي
نسختها للتو. يعرّف المفتاح مؤسستك تلقائيًا، لذا لا تحتاج مطلقًا إلى
وضع معرّف المؤسسة في عناوين URL.

## الخطوة 2: إنشاء وكيل

يحدّد الوكيل كيفية تعامل الذكاء الاصطناعي مع المحادثات — الموجّه والصوت
ومستوى المنتج والأدوات وأهلية استخدام الأداة المصغّرة.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thunderphone.com/v1/agents \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":   "Customer Support",
      "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      "voice":  "john",
      "product": "spark"
    }'
  ```

  ```python Python theme={null}
  import os, requests

  agent = requests.post(
      "https://api.thunderphone.com/v1/agents",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={
          "name":   "Customer Support",
          "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
          "voice":  "john",
          "product": "spark",
      },
  ).json()
  print("Agent id:", agent["id"])
  ```

  ```javascript Node.js theme={null}
  const agent = await fetch("https://api.thunderphone.com/v1/agents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name:    "Customer Support",
      prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      voice:   "john",
      product: "spark",
    }),
  }).then((r) => r.json());
  console.log("Agent id:", agent.id);
  ```
</CodeGroup>

<Tip>
  مستويات المنتج: `spark` مُحسّن للتكلفة، و`bolt` للسرعة، و
  `storm-base` / `storm-extra` للذكاء في الموجّهات المعقدة. راجع
  [الوكلاء](/api-reference/agents#product-tiers-at-a-glance) للمقارنة
  الكاملة.
</Tip>

## الخطوة 3: توفير رقم هاتف

يطلب هذا الاستدعاء رقمًا من مجموعة ThunderPhone التجريبية ويعيّن وكيلك
الجديد كمعالج للمكالمات الواردة. (لإحضار رقمك الخاص من موفر VoIP،
راجع [اتصالات VoIP](/api-reference/voip-connections)
بدلًا من ذلك.)

<CodeGroup>
  ```bash cURL theme={null}
  # First provision
  curl -X POST https://api.thunderphone.com/v1/phone-numbers \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"area_code": "415"}'

  # Then assign the agent you created in Step 2
  curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"inbound_agent_id": 12}'
  ```

  ```python Python theme={null}
  number = requests.post(
      "https://api.thunderphone.com/v1/phone-numbers",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"area_code": "415"},
  ).json()
  requests.patch(
      f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"inbound_agent_id": agent["id"]},
  )
  print("Your ThunderPhone number:", number["number"])
  ```
</CodeGroup>

يبدأ رقمك الجديد بالحالة `status="provisioning"` ثم ينتقل إلى
`active` خلال بضع ثوانٍ؛ وبحلول وقت إغلاق متصفحك، يكون الرقم جاهزًا
لاستقبال المكالمات.

## الخطوة 4 (اختيارية): إعداد خطاف ويب

للحصول على أحداث في الوقت الفعلي (توجيه المكالمات الديناميكي، والمعالجة بعد المكالمة)، أضف
نقطة نهاية لخطاف ويب. اشترك فقط في الأحداث التي تحتاج إليها.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

تتضمن الاستجابة `secret` يُستخدم لمرة واحدة — انسخه إلى مدير
الأسرار لديك. استخدم هذا السر للتحقق من ترويسة
`X-ThunderPhone-Signature` في الطلبات الواردة (راجع
[نظرة عامة على خطافات الويب](/ar/webhooks/overview)).

## الخطوة 5: اختبار وكيلك

اتصل بالرقم الذي وفّرته للتو. يرد الوكيل، ويعرّف
بنفسه، ويتبع موجّهك.

افحص المكالمة بعد انتهائها:

```bash theme={null}
curl https://api.thunderphone.com/v1/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

تعمّق في مكالمة محددة لجلب النص المفرغ ورابط التسجيل:

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

***

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

<CardGroup cols={2}>
  <Card title="إضافة أدوات الدوال" icon="screwdriver-wrench" href="/ar/tools/overview">
    دع وكيلك يستدعي واجهات API الخاصة بك أثناء المحادثة.
  </Card>

  <Card title="إجراء مكالمات صادرة" icon="arrow-up-right" href="/api-reference/outbound-calls">
    شغّل المكالمات من التعليمات البرمجية الخاصة بك.
  </Card>

  <Card title="التعامل مع خطافات الويب" icon="bolt" href="/ar/webhooks/overview">
    تفاعل مع أحداث المكالمات في الوقت الفعلي.
  </Card>

  <Card title="مرجع API الكامل" icon="book" href="/api-reference/introduction">
    جميع نقاط النهاية العامة، موثقة.
  </Card>
</CardGroup>