البدء السريع (واجهة برمجة التطبيقات)
أجب عن أول مكالمة هاتفية باستخدام وكيل صوتي بالذكاء الاصطناعي: احصل على مفتاح API، وأنشئ وكيلاً، وفّر رقم هاتف، وأجرِ مكالمة اختبار مباشرة — كل ذلك عبر واجهة REST API.
يرشدك هذا الدليل خلال استدعاءات REST الأربعة اللازمة للرد على مكالمتك الهاتفية الأولى باستخدام وكيل ذكاء اصطناعي.
الخطوة 1: الحصول على مفتاح API
- تسجيل الدخول
افتح app.thunderphone.com.
- الانتقال إلى المفاتيح
انتقل إلى المؤسسة ← المفاتيح في لوحة التحكم.
- إنشاء مفتاح
انقر على إنشاء مفتاح، وامنحه اسماً، ثم انسخ قيمة
sk_live_.... يُعرض المفتاح الخام مرة واحدة فقط — خزّنه فوراً في مدير الأسرار لديك.
طوال هذا الدليل، استبدل sk_live_YOUR_API_KEY بالقيمة التي
نسختها للتو. يعرّف المفتاح مؤسستك تلقائياً، لذا لا تحتاج مطلقاً إلى
وضع معرّف المؤسسة في عناوين URL.
الخطوة 2: إنشاء وكيل
يحدّد الوكيل كيفية تعامل الذكاء الاصطناعي مع المحادثات — الموجّه والصوت ومستوى المنتج والأدوات وأهلية الأداة المصغّرة.
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"
}'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"])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);الخطوة 3: توفير رقم هاتف
يطلب هذا الاستدعاء رقماً من مجموعة العرض التجريبي في ThunderPhone ويعيّن وكيلك الجديد كمعالج للمكالمات الواردة. (لإحضار رقمك الخاص من مزود VoIP، راجع اتصالات VoIP بدلاً من ذلك.)
# 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}'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"])يبدأ رقمك الجديد بالحالة status="provisioning" وينتقل إلى
active خلال بضع ثوانٍ؛ وبحلول وقت إغلاق المتصفح، يكون الرقم
جاهزاً لاستقبال المكالمات.
الخطوة 4 (اختياري): إعداد خطاف ويب
لأحداث الوقت الفعلي (توجيه المكالمات الديناميكي، والمعالجة بعد المكالمة)، أضف نقطة نهاية لخطاف ويب. اشترك فقط في الأحداث التي تحتاج إليها.
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 في الطلبات الواردة (راجع
نظرة عامة على خطافات الويب).
الخطوة 5: اختبار وكيلك
اتصل بالرقم الذي وفّرته للتو. يرد الوكيل، ويعرّف بنفسه، ويتبع موجّهك.
افحص المكالمة بعد انتهائها:
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"تعمّق في مكالمة محددة لجلب النص المفرغ ورابط التسجيل:
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"