المفاهيم الأساسية

خريطة لكل ما في المنصة — ما وظيفة كل كائن، وأين يوجد في لوحة التحكم، وأي واجهة API تتعامل معه.

ThunderPhone هي منصة متكاملة لبناء وتشغيل وتحسين وكلاء الصوت بالذكاء الاصطناعي. هذه الصفحة هي الخريطة: كل مفهوم ستصادفه، قسم قصير لكل منها، مع واجهة لوحة التحكم وواجهة API التي تدعمه. تصفّحها مرة واحدة، ثم عُد إليها متى احتجت إلى توضيح مصطلح.

يعكس الشريط الجانبي للوحة التحكم هذه البنية:

المؤسسات#

المؤسسة هي وحدة الإشغال. ينتمي كل مورد آخر — الوكلاء وأرقام الهواتف والمكالمات والمفاتيح — إلى مؤسسة واحدة بالضبط. يمكن لحسابك الانتماء إلى مؤسسات متعددة؛ ولكل منها رصيدها الخاص ومفاتيحها الخاصة وقائمة أعضائها الخاصة.

يرتبط مفتاح API sk_live_ الذي تنشئه ضمن المؤسسة ← المفاتيح بمؤسسة واحدة. هذا الارتباط هو ما يجعل واجهة REST API مسطّحة إلى هذا الحد: لا تضع معرّف مؤسسة في مسارات URL، لأن مفتاحك يعرّفها بالفعل.

في لوحة التحكم: مبدّل المؤسسة (تذييل الشريط الجانبي) وإعدادات المؤسسة — علامات تبويب حسابي، وعام، والمفاتيح، والتنبيهات، وإعدادات الفوترة، وسجل الفوترة. راجع مرجع إعدادات المؤسسة.

في واجهة API: /v1/orgs, /v1/developer/api-keys.

الوكلاء#

الوكيل هو إعداد الذكاء الاصطناعي الذي يدير مكالمة. ويضم:

• موجّه يحكم ما يقوله الوكيل وكيف يتصرف — بما في ذلك إجراءات المكالمة مثل التحويلات وضغطات لوحة المفاتيح وإنهاء المكالمات، وهي أسطر موجّه عادية وليست إعدادات منفصلة.
• مستوى المحرك (spark, bolt, storm-*): تم تحسين Spark للتكلفة، وBolt للسرعة، وStorm للذكاء في الموجّهات المعقدة.
• صوت بالإضافة إلى لغة أساسية ولغات إضافية اختيارية — ينتقل الوكيل تلقائياً عندما يغيّر المتصل اللغة. راجع اللغات المدعومة.
• إمكانات مرفقة: التطبيقات المتصلة، اتصالات API، قواعد المعرفة، خوادم MCP، و أدوات الدوال المضمنة.
• عناصر ضبط السلوك: ترتيب التحدث، ووضع الإقرار، والمسار الخلفي، والمهلة الزمنية للانتظار.

تُحفظ التعديلات في أداة الإنشاء تلقائياً في مسودة؛ ولا يتم نشر أي شيء حتى تنقر نشر. تؤخذ لقطة لكل عملية نشر في علامة تبويب السجل في أداة الإنشاء، بحيث يمكنك فحص أي إصدار سابق واستعادته.

في لوحة التحكم: وكلاء الصوت ← أداة إنشاء الوكيل (/dashboard/agents). راجع أنشئ أول وكيل صوت بالذكاء الاصطناعي.

في واجهة API: /v1/agents — عمليات CRUD، والتكرار، والتحويل، وسجل الإصدارات، ومساعدات الموجّهات.

الأصوات#

تحتوي مكتبة الأصوات على الأصوات التي يمكن للوكيل استخدامها، وعينات قابلة للتشغيل منها، واللغات المتوافقة، وتصنيفات الجنس واللهجة، وأي رسوم إضافية للأصوات أو اللغات المميزة. تتيح لك معاينة مدفوعة تركيب عبارتك الخاصة المكوّنة من 1–500 حرفًا قبل الاختيار.

يمكن للمؤسسات المؤهلة أيضًا إنشاء أصوات مخصصة من عينة قصيرة بتنسيق WAV أو MP3. تخضع الأصوات المخصصة لحصة وحدّة إنشاء غير متزامنة؛ وبمجرد جاهزيتها، تظهر في أداة اختيار الوكيل نفسها إلى جانب أصوات المكتبة.

في لوحة التحكم: الأصوات (/dashboard/voices). راجع مكتبة الأصوات والأصوات المخصصة.

في واجهة API: /v1/voices، عينات الأصوات، و الأصوات المخصصة.

أرقام الهاتف#

ينتمي رقم الهاتف إلى مؤسسة ويوجّه المكالمات الواردة إلى وكيل (ويمكنه إجراء المكالمات الصادرة). مصدران:

• أرقام ThunderPhone — أرقام أمريكية حقيقية يتم توفيرها من مجموعة ThunderPhone، وتصبح جاهزة خلال ثوانٍ، $1/شهريًا بالإضافة إلى رسم قدره 1¢/للدقيقة . تبدأ للمكالمات الواردة فقط. يمكن لمسؤول المؤسسة طلب إجراء المكالمات الصادرة من صفحة أرقام الهاتف؛ تراجع ThunderPhone كل طلب يدويًا، ويمكن للأرقام المعتمدة إجراء المكالمات وتشغيل الحملات. يمكن للمؤسسة الاحتفاظ بـ 25 رقمًا افتراضيًا.
• أرقام VoIP — تُجلب من مزودك الخاص عبر اتصال VoIP. يتصل Twilio وTelnyx مباشرةً باستخدام مفتاح API (يوفر Telnyx أيضًا إعدادًا موجّهًا لحساب جديد)؛ ويتصل SignalWire وVonage وPlivo وأي خط SIP آخر عبر إعداد SIP، وهو تهيئة SIP يدوية. بعد الاستيراد والتحقق، تدعم أرقام VoIP المكالمات الواردة والصادرة.

يتيح لك كل صف لرقم تعيين وضع توجيه واختيار الوكيل الوارد ووضع تسمية للرقم.

في لوحة التحكم: أرقام الهاتف (/dashboard/phone-numbers). راجع الحصول على رقم هاتف.

في واجهة API: /v1/phone-numbers، /v1/voip-connections، /v1/phone-number-labels.

المكالمات#

تتحول كل مكالمة واردة أو مكالمة صادرة أو محاكاة أو جلسة عنصر واجهة إلى سجل مكالمة. يحمل سجل المكالمة النص المفرغ الكامل الموسوم بالأدوار، وسجل التبادلات المنظّم (بما في ذلك استدعاءات الأدوات)، وتسجيلًا، وإجمالي الفوترة، وتقارير اختيارية لتقييم الذكاء الاصطناعي والمشكلات.

أثناء كون المكالمة مباشرة، يمكنك فتحها والاستماع إليها — تنضم بصمت، ولا يسمعك أي شخص في المكالمة. بعد بدء الاستماع، يمكنك الهمس: اكتب توجيهًا يصل مباشرة إلى وكيلك أثناء المكالمة؛ لن يسمعه المتصل أبدًا، وسيتبعه الوكيل مباشرةً.

في لوحة التحكم: سجل المكالمات (/dashboard/call-history) من أجل الأرشيف وتفاصيل كل مكالمة؛ والمباشرة للمكالمات الجارية. راجع مراجعة مكالماتك والاستماع إليها وتدريبها.

في واجهة API: /v1/calls — قائمة، نص مفرغ، سجل، صوت، تقييم، تصدير؛ /v1/issue-reports.

بوابات العملاء#

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

في لوحة التحكم: بوابات العملاء (/dashboard/client-portals). راجع بوابات العملاء.

في واجهة API: /v1/client-portals لواجهة إدارة المسؤولين.

أدوات الويب#

تمنح أداة الويب زوار موقعك محادثة عبر الميكروفون مع وكيل صوتي — من دون الحاجة إلى رقم هاتف. وتتحقق من الهوية باستخدام مفتاح قابل للنشر (pk_live_...) لا يمكن للمتصفحات استخدامه إلا من نطاقاتك المسموح بها، لذا فهو آمن في التعليمات البرمجية من جانب العميل. قائمة النطاقات ليست مصادقة، وإعدادات الجلسة التي قد ترسلها الصفحة تكون معطلة إلى أن تسمح بها على المفتاح.

تعمل المفاتيح في أحد وضعين: agent (مرتبط بشكل ثابت بوكيل واحد) أو webhook (يختار خادمك الإعداد لكل زائر — راجع الإعداد الديناميكي لكل مكالمة). تمر جلسات الأداة عبر البنية التحتية نفسها للمكالمات الهاتفية.

في لوحة التحكم: أدوات الويب (/dashboard/web-widgets) — أنشئ أدوات، واضبط الوضع والوكيل، وأدر النطاقات المسموح بها، وانسخ مقتطف التضمين. راجع إنشاء أداة ويب.

في واجهة برمجة التطبيقات: /v1/publishable-key، و/v1/mic-session، و وثائق SDK للأداة.

قواعد المعرفة#

قاعدة المعرفة هي مجموعة من المستندات التي يمكن لوكيلك البحث فيها أثناء المكالمة لإسناد إجاباته — حمّل ملفات، أو الصق نصًا، أو استورد صفحات ويب عبر عنوان URL، ثم أرفق قاعدة المعرفة بوكيل في أداة الإنشاء. يستعلم الوكيل عنها باستخدام أداة بحث مدمجة كلما تطلبت المحادثة ذلك.

في لوحة التحكم: المعرفة (/dashboard/knowledge) من أجل مكتبة المستندات؛ وقسم المعرفة في أداة الإنشاء لإرفاق واحدة ب وكيل. راجع تزويد وكيلك بقاعدة معرفة.

الاتصالات#

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

• التطبيقات (/dashboard/app-connections) — اتصالات OAuth مع Slack وHubSpot وSalesforce وGoogle Calendar وGoogle Sheets وCal.com. اتصل مرة واحدة، ثم فعّل أدوات كل عملية على حدة (نشر رسالة في Slack، أو إدراج أو تحديث جهة اتصال في HubSpot، أو حجز موعد في Cal.com…) لأي وكيل. راجع ربط التطبيقات.
• واجهات برمجة التطبيقات (/dashboard/api-connections) — حوّل أي واجهة HTTP API إلى إجراء للوكيل. الصق أمر cURL، وسيُنشئ معالج الذكاء الاصطناعي مسودة لتعريف الأداة، أو أنشئها يدويًا؛ يرسل زر طلب اختبار مكالمة في بيئة معزولة قبل الإطلاق. راجع اتصالات واجهات برمجة التطبيقات — واجهة لوحة التحكم لـ /v1/integrations.
• MCP (/dashboard/mcp-connections) — أضف خادم Model Context Protocol عبر عنوان URL ودع الوكيل يستخدم الأدوات التي يوفّرها. راجع إضافة خادم MCP.
• VoIP (/dashboard/voip-connections) — بيانات اعتماد المزوّد من أجل استخدام أرقام هاتفك الخاصة. راجع ربط مزوّد VoIP.

يوفر ThunderPhone أيضًا نقطة نهاية MCP خاصة به، بحيث يمكن لعميل MCP خارجي سرد الوكلاء، وفحص المكالمات والنصوص المفرغة، وإجراء المكالمات. راجع استخدام ThunderPhone كخادم MCP.

في واجهة برمجة التطبيقات: /v1/integrations، و/v1/mcp-servers، و /v1/voip-connections؛ راجع أيضًا إنشاء تكامل أداة.

الحملات#

تُجري الحملة مكالمات صادرة على نطاق واسع: حمّل ملف CSV يضم جهات الاتصال، واختر الوكيل ورقم الاتصال الصادر، واضبط نافذة الاتصال (الأيام والساعات، مع مراعاة المنطقة الزمنية)، والتزامن، وسياسة إعادة المحاولة (الحد الأقصى للمحاولات والنتائج التي — عدم الرد، والبريد الصوتي، والفشل — تُعاد محاولتها). تعالج الحملة القائمة وتسجل كل مكالمة في سجل المكالمات.

في لوحة التحكم: الحملات (/dashboard/campaigns). راجع تشغيل حملة مكالمات صادرة.

للمكالمات البرمجية لمرة واحدة: استخدم واجهة برمجة تطبيقات المكالمات الصادرة.

المراقبة المباشرة#

يعرض المباشر كل مكالمة جارية عبر المؤسسة، ويتيح لك فتح أي منها للاستماع والتحدث همسًا في الوقت الفعلي. إنه واجهة الإشراف: راقب موجّهًا جديدًا أثناء أول حركة مرور فعلية له، أو تابع حملةً جارية.

في لوحة التحكم: المباشر (/dashboard/live). راجع مراقبة المكالمات المباشرة والإشراف عليها.

المحاكاة#

المحاكاة هي متصل يعمل بالذكاء الاصطناعي يجري محادثة فعلية مع وكيلك — نفس مسار الاتصالات الهاتفية، ونص مفرغ فعلي، وتقييم فعلي — بحيث يمكنك الاختبار قبل الإطلاق (وبعده). وجّهها إلى وكيل أو رقم هاتف، واكتب سيناريو المتصل بنفسك أو أنشئ سيناريوهات باستخدام الذكاء الاصطناعي انطلاقًا من موجّه الوكيل (بما في ذلك الحالات الحدية، إذا طلبت ذلك)، وراقب المكالمة مباشرةً.

تُجمَّع السيناريوهات ضمن مجموعات تثبّت حدًا أدنى لمعدل النجاح ويمكنها فرض قيود على الإصدارات في CI؛ ويُبلّغ عن حالات التراجع مقارنةً بخط الأساس المقبول لكل سيناريو.

في لوحة التحكم: المحاكاة (/dashboard/simulations)، بالإضافة إلى زر محاكاة داخل منشئ الوكيل. راجع محاكاة مكالمة.

في واجهة API: /v1/test-calls ومشغّل المجموعة — راجع اختبار وكيل من البداية إلى النهاية.

مجموعات التحقق#

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

في لوحة التحكم: مجموعات التحقق (/dashboard/validation) لمجموعة بيانات المؤسسة، وعلامة التبويب التحقق في منشئ الوكيل لعمليات التشغيل. راجع مجموعات التحقق.

في واجهة API: /v1/validation-sets ونقاط نهاية إعادة تشغيل الوكيل/المثال في صفحة المرجع نفسها.

التجارب#

تجري التجربة اختبارات A/B لإعدادات الوكيل على حركة المرور الفعلية: حدّد المتغيرات (موجّهات أو محركات أو إعدادات مختلفة)، ووزّع حركة المرور بينها، وقارن النتائج لكل متغير. استخدمها بدلًا من بناء منطق المجموعات يدويًا في webhook.

في لوحة التحكم: التجارب (/dashboard/experiments) وعلامة التبويب A/B في منشئ الوكيل. راجع التجارب (اختبار A/B).

المشكلات#

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

في لوحة التحكم: المشكلات (/dashboard/issues)، بالإضافة إلى وضع علامات لكل مكالمة في سجل المكالمات. راجع فرز المشكلات.

في واجهة API: /v1/issue-reports.

التقارير#

يجيب التقرير عن سؤال بلغة طبيعية حول بيانات مكالماتك ("ما أهم ثلاثة أسباب دفعت المتصلين إلى طلب التحدث إلى شخص الأسبوع الماضي؟") بتحليل مكتوب بالذكاء الاصطناعي، ومحدّد بالنطاق وفقًا للوكلاء ونطاق التاريخ اللذين تختارهما.

في لوحة التحكم: التقارير (/dashboard/reports). راجع التقارير.

قابلية المراقبة#

قابلية المراقبة هي واجهة المقاييس: حجم المكالمات والنتائج والجودة بمرور الوقت، مع إمكانية التصفية حسب الوكيل والنافذة الزمنية، والتصدير للتحليل اللاحق.

في لوحة التحكم: قابلية المراقبة (/dashboard/observability). راجع قابلية المراقبة.

التنبيهات#

تراقب قاعدة تنبيه مقياسًا (معدل النجاح، معدل الفشل، متوسط النتيجة، حجم المكالمات، حالات تراجع المجموعات) خلال نافذة زمنية وتُفعَّل عند تجاوزه الحد الذي تحدده. تُرسل الإشعارات إلى البريد الإلكتروني وSlack، وتُطلق حدث alert.triggered إلى نقاط نهاية webhook الخاصة بك.

في لوحة التحكم: المؤسسة ← التنبيهات. راجع التنبيهات.

خطافات الويب#

يرسل ThunderPhone خطافات ويب HTTP POST إلى خادمك عند حدوث أمور أثناء المكالمة وبعدها. نموذجا تسليم:

• نقاط نهاية خطافات الويب (موصى بها): أدِر عدة عناوين URL في /v1/developer/webhook-endpoints باستخدام أسرار لكل نقطة نهاية واشتراكات أحداث لكل نقطة نهاية.
• خطاف الويب القديم بعنوان URL واحد: عنوان URL واحد لكل مؤسسة. يُدار من /v1/webhook أو ضمن المؤسسة ← عام. يُحتفَظ به للتوافق مع الإصدارات السابقة.

تنقسم الأحداث إلى فئتين:

• الأحداث الحاجبة تتوقع من خادمك الاستجابة بإعدادات تُشكّل المكالمة الجارية — وهي أحداث المكالمات الواردة (telephony.incoming / web.incoming). تنتظر المكالمة الهاتفية مدة تصل إلى 13 ثانية، بما في ذلك إعادة محاولة واحدة، وتنتظر جلسة الأداة 10 ثوانٍ. لا يوجد وكيل بديل: من دون إعدادات قابلة للاستخدام، تُنهى المكالمة الهاتفية وتفشل جلسة الأداة.
• الأحداث غير الحاجبة هي إشعارات تُرسل دون انتظار، ويُعاد إرسالها بتراجع أسي — راجع دلالات التسليم.

يحمل كل طلب توقيع HMAC-SHA256 مرفقًا بطابع زمني في X-ThunderPhone-Signature-V2، بالإضافة إلى التوقيع القديم المعتمد على نص الطلب فقط X-ThunderPhone-Signature. راجع التحقق من التوقيع.

أدوات الدوال#

أداة الدالة هي نقطة نهاية HTTP يمكن لوكيلك استدعاؤها في أثناء المحادثة. تزوّد ThunderPhone بمخطط دالة بأسلوب OpenAI بالإضافة إلى عنوان URL لنقطة النهاية؛ ويقرر الوكيل متى يستدعيها، ويُجري ThunderPhone طلب HTTP الموقّع من خوادمه ويعيد النتيجة إلى الوكيل.

تتضمن الوكلاء أيضًا قدرات مكالمات مدمجة — تحويل المكالمة، وإرسال إدخال لوحة المفاتيح (DTMF)، وإنهاء المكالمة، والانتظار قيد التعليق — تفعّلها بأسطر موجّه بسيطة بدلًا من تعريفات الأدوات.

في لوحة التحكم: قسم اتصالات API في أداة الإنشاء (راجع الاتصالات).

في واجهة API: /v1/integrations و مواصفة أدوات الدوال.

الفريق والأدوار#

لكل مؤسسة قائمة أعضاء تضم دورين: الأعضاء ينشئون الوكلاء ويشغّلونهم؛ والمشرفون يديرون أيضًا الفريق والفوترة. ادعُ عبر البريد الإلكتروني — تنتهي صلاحية الدعوات بعد 7 أيام ويمكن إلغاؤها؛ وتغيّر قائمة ⋯ في صف العضو الأدوار أو تزيل شخصًا. يمكن إعداد تسجيل الدخول الموحّد على مستوى المؤسسة — راجع SSO.

في لوحة التحكم: المؤسسة ← عام. راجع دعوة فريقك.

في واجهة API: /v1/members، /v1/invites.

الفوترة#

ThunderPhone مدفوع مسبقًا. تحمل كل مؤسسة رصيدًا بالدولار الأمريكي؛ وتُخصم تكلفة المكالمات منه وفق السعر لكل دقيقة للوكيل (مستوى المحرك بالإضافة إلى الرسوم الإضافية — تعرض أداة الإنشاء السعر الإجمالي مباشرةً عند تغيير الإعدادات، وتضيف اللغات الإضافية المحددة 3¢/دقيقة). عند وصول الرصيد إلى الصفر، تُرفض المكالمات الواردة وتُرجع المكالمات الصادرة 402 Payment Required.

أضف رصيدًا يدويًا، أو فعّل إعادة الشحن التلقائي باستخدام حد للرصيد، ومبلغ إعادة تعبئة، وحد إنفاق شهري اختياري — حتى لا تنقطع المكالمة في منتصف الجملة.

في لوحة التحكم: المؤسسة ← إعدادات الفوترة و سجل الفوترة. راجع إضافة أموال وتفعيل إعادة الشحن التلقائي، بالإضافة إلى مرجع الأسعار الكامل.

في واجهة API: /v1/billing.

المساعد المرافق داخل التطبيق#

تتضمن لوحة التحكم مساعدًا مرافقًا مدمجًا — اسأله "كيف أفعل X" فيجيب من هذه الوثائق، ويقدّم إرشادات خطوة بخطوة تُبرز عناصر التحكم الفعلية، ويمكنه إعادة تشغيل أي من الجولات الإرشادية. إنه أسرع طريقة للعثور على عنصر تحكم تذكره هذه الصفحة. راجع اسأل المساعد المرافق داخل التطبيق.

جمع العناصر معًا#