Getting Started

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

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

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، وتصبح جاهزة خلال ثوانٍ. وهي للمكالمات الواردة فقط، وترد بإخلاء مسؤولية صوتي قصير، وتحدد لوحة التحكم المؤسسة بعشرة أرقام منها. مثالية للاختبار الأول، وليست للإنتاج.
• أرقام VoIP — تُجلب من مزودك الخاص عبر اتصال VoIP. يتصل Twilio وTelnyx مباشرةً (يوفر Telnyx إعدادًا موجّهًا)؛ وسيصل SignalWire وVonage قريبًا — ويمكنك الوصول إليهما اليوم عبر إعداد 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) — أنشئ الأدوات، واضبط الوضع والوكيل، وأدر النطاقات المسموح بها، وانسخ مقتطف التضمين. راجع إنشاء أداة ويب.

في API: /v1/publishable-key، /v1/mic-session، و وثائق Widget SDK.

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

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

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

الاتصالات#

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

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

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

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

الحملات#

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

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

للمكالمات البرمجية لمرة واحدة: واجهة API للمكالمات الصادرة.

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

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

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

المحاكاة#

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

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

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

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

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

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

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

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

التجارب#

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

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

المشكلات#

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

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

في واجهة برمجة التطبيقات: /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). لديك ما يصل إلى 10 ثوانٍ للاستجابة؛ وعند انتهاء المهلة، يعالج الوكيل المعيّن ثابتًا المكالمة.
• الأحداث غير الحاجبة هي إشعارات إرسال دون انتظار، ويُعاد إرسالها بتراجع أُسّي — راجع دلالات التسليم.

يحمل كل طلب توقيع HMAC-SHA256 في 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" فيجيب من هذه الوثائق، ويقدّم إرشادات خطوة بخطوة تسلّط الضوء على عناصر التحكم الفعلية، ويمكنه إعادة تشغيل أي من الجولات الإرشادية. إنها أسرع طريقة للعثور على عنصر تحكم تذكره هذه الصفحة. راجع اسأل المساعد الذكي داخل التطبيق.

جمع المفاهيم معًا#