---
title: "استخدم ThunderPhone مع n8n"
description: "ثبّت عقدة ThunderPhone لـ n8n، واربط مفتاح API للخادم، وأنشئ سير عمل يُشغَّل في كل مرة تنتهي فيها مكالمة."
---

[n8n](https://n8n.io) أداة لأتمتة سير العمل. تضيف حزمة ThunderPhone
لـ n8n عقدتين:

- تبدأ **ThunderPhone Trigger** سير عمل عند انتهاء مكالمة (**اكتملت
  المكالمة**) أو عند انتهاء تشغيل تقييم مكالمة (**تم تقييم المكالمة**).
- تُجري **ThunderPhone** مكالمات صادرة، وتضيف جهات اتصال إلى الحملات
  وتبدأها، وتجلب المكالمات مع النص المفرغ والتسجيل، وتسرد وكلاءك وأرقام هاتفك.

إنها عقدة مجتمع موثّقة، ومدرجة في
[ThunderPhone على n8n](https://n8n.io/integrations/thunderphone/).

## تثبيت العقدة

في محرر n8n، انقر على **+** لفتح لوحة العقد وابحث عن
**ThunderPhone**. قد يحتاج مالك المثيل إلى إعداد العقد الموثّقة قبل أن يتمكن
المستخدمون الآخرون من إضافتها.

في n8n المستضاف ذاتيًا، يمكنك أيضًا التثبيت باسم الحزمة: افتح
**الإعدادات > عقد المجتمع** وثبّت `n8n-nodes-thunderphone`. تحقّق من مخاطر عقد المجتمع وسياسة المثيل لديك
قبل التثبيت.

## إنشاء مفتاح API للخادم

<Steps>
  <Step title="افتح علامة تبويب المفاتيح">
    في ThunderPhone، انتقل إلى **المؤسسة → المفاتيح** وانقر على **إنشاء مفتاح**.
  </Step>
  <Step title="سمّه">
    استخدم اسمًا يوضح مكان وجود المفتاح، مثل "n8n".
  </Step>
  <Step title="انسخه الآن">
    يظهر السر الكامل `sk_live_...` مرة واحدة. انسخه قبل إغلاق
    مربع الحوار.
  </Step>
</Steps>

يمكن للمسؤول أو المالك فقط إنشاء المفتاح، ويتعامل ThunderPhone مع الطلبات
المُرسلة به على أنها صادرة من ذلك الشخص. يتطلب المشغّل وعمليات الحملة
أن يحتفظ ذلك الشخص بدور المسؤول أو المالك.
تغطي [إنشاء مفتاح API للخادم](/ar/guides/api-keys) التدوير والإلغاء.

## إضافة بيانات الاعتماد في n8n

1. في n8n، أنشئ بيانات اعتماد من النوع **ThunderPhone API**.
2. الصق المفتاح في **مفتاح API**.
3. احفظها وشغّل اختبار بيانات الاعتماد. يقرأ الاختبار مكالمة واحدة من
   مؤسستك باستخدام `GET /v1/calls?limit=1`.

## أنشئ سير عمل أول

يضيف سير العمل هذا صفًا إلى Google Sheet كلما انتهت مكالمة.

<Steps>
  <Step title="أضف المُشغِّل">
    أضف **مُشغِّل ThunderPhone**، واختر بيانات اعتماد ThunderPhone API، ثم
    عيّن **الحدث** إلى **اكتمال المكالمة**.
  </Step>
  <Step title="اجلب المكالمة">
    أضف عقدة **ThunderPhone**. عيّن **المورد** إلى **المكالمة**، و**العملية**
    إلى **جلب**، و**معرّف المكالمة** إلى التعبير `{{ $json.data.call_id }}`.
    الناتج هو [سجل المكالمة](/api-reference/calls) بالإضافة إلى `transcripts`
    و`recording_url`، وهو رابط قصير العمر يكون `null` عندما لا تحتوي المكالمة
    على تسجيل.
  </Step>
  <Step title="أضف صفًا">
    أضف عقدة Google Sheets تُلحق صفًا، ثم عيّن الأعمدة التي تريدها من مخرجات
    جلب المكالمة (راجع الجدول أدناه).
  </Step>
  <Step title="فعّل سير العمل">
    احفظ وفعّل. يسجّل المُشغِّل عنوان URL للإنتاج الخاص به كنقطة نهاية webhook
    في مؤسسة ThunderPhone الخاصة بك. يؤدي إلغاء تفعيل سير العمل إلى حذف نقطة
    النهاية تلك.
  </Step>
  <Step title="اختبره">
    افتح وكيلًا في المنشئ، وانقر **تحدث**، ثم أنهِ المكالمة. تُسلَّم مكالمات
    الاختبار في المنشئ على أنها `web.complete`، وهو أحد الحدثين اللذين يشكّلان
    اكتمال المكالمة، لذا يعمل سير العمل ويظهر صف.
  </Step>
</Steps>

أعمدة مفيدة:

| العمود | التعبير |
|---|---|
| معرّف المكالمة | `{{ $json.call_id }}` |
| الاتجاه | `{{ $json.direction }}` |
| ابتداءً من | `{{ $json.from_number }}` |
| إلى | `{{ $json.to_number }}` |
| وقت البدء | `{{ $json.start_time }}` |
| المدة (ث) | `{{ $json.duration_seconds }}` |
| الحالة | `{{ $json.status }}` |
| سبب الإنهاء | `{{ $json.end_reason }}` |
| رابط المكالمة | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` |

يفتح رابط المكالمة المكالمة في لوحة تحكم ThunderPhone لأعضاء مؤسستك،
مع نصها المفرغ وتسجيلها، لذلك لا تحتاج الورقة إلى الاحتفاظ بأيٍّ منهما.

لإضافة النص المفرغ على أي حال، عيّن
`{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`.
تنتهي صلاحية عنوان URL الخاص بالتسجيل، لذا خزّن معرّف المكالمة وشغّل جلب
المكالمة مجددًا عندما تحتاج إلى رابط جديد. قد تحتوي النصوص المفرغة للمكالمات
والملخصات والتسجيلات على معلومات شخصية أو صحية. أرسلها فقط إلى التطبيقات التي
يُسمح لمؤسستك باستخدامها لهذه البيانات، بموجب BAA عند وجود معلومات صحية،
واحتفظ فقط بالحقول التي تحتاج إليها.

<Note>
  يسلّم ThunderPhone الأحداث باستخدام `POST` إلى **عنوان URL للإنتاج**
  الخاص بالمُشغِّل، لذا يجب أن يكون مثيل n8n الخاص بك متاحًا عبر HTTPS من
  الإنترنت، ويجب أن يكون سير العمل مفعّلًا. يتحقق المُشغِّل من HMAC الخاص
  بـ `X-ThunderPhone-Signature` في كل طلب ويرد بـ `401` على أي طلب غير
  موقّع أو غير صالح.
</Note>

يُخرج المُشغِّل الحدث الكامل: `type` و`event_id` و`data`. راجع
[`telephony.complete` / `web.complete`](/ar/webhooks/call-complete) و
[`call.graded`](/ar/webhooks/events) لكل حقل. يتم التسليم مرة واحدة على الأقل،
ويبقى `event_id` كما هو عبر عمليات إعادة محاولة حدث واحد، لذا تحقّق منه قبل
خطوة يجب ألا تتكرر.

## إجراء مكالمات صادرة بأمان

**إجراء مكالمة صادرة** (المورد **مكالمة صادرة**، العملية **إجراء**)
يأخذ:

| الحقل | المعنى |
|---|---|
| اسم الوكيل أو المعرّف | وكيل محفوظ. تعرض القائمة المنسدلة وكلاءك. |
| اسم رقم الهاتف أو المعرّف | رقم المصدر. تعرض القائمة المنسدلة الأرقام المفعّلة للمكالمات الصادرة فقط. |
| الرقم المستهدف | الوجهة بتنسيق E.164، مثل `+14155552671`. |
| المتغيرات | كائن JSON للقيم الخاصة بالعناصر النائبة في موجّه الوكيل. |
| مفتاح عدم التكرار | معرّف ثابت من سجل أو حدث المصدر. مطلوب. |

اربط **مفتاح عدم التكرار** بمعرّف مما تسبب في التشغيل، مثل
معرّف سجل CRM أو `event_id` الخاص بالمشغّل. ترسل العقدة
`n8n:<node ID>:<your value>`، لذا:

- ترسل إعادة المحاولة التلقائية أو **إعادة تنفيذ التشغيل** المفتاح نفسه، ويعيد
  ThunderPhone المكالمة الأصلية مع `idempotent_replay: true`
  بدلاً من الاتصال مرة أخرى.
- ترسل عقدتا ThunderPhone اللتان تتلقيان السجل نفسه مفاتيح مختلفة.
- تفشل القيمة الفارغة قبل إرسال أي طلب.

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

**الحملات.** تضيف **إضافة جهات الاتصال** (المورد **حملة**) جهات اتصال إلى
حملة مسودة. تتطلب معرّف الحملة ومصفوفة JSON لجهات الاتصال. تحتاج كل جهة اتصال إلى `phone_number`؛ وتتحول المفاتيح الأخرى
إلى متغيرات للمكالمة. تفشل العقدة عندما تُرفض جميع جهات الاتصال، وتضبط
`partial_success: true` عندما يُرفض بعضها فقط. يتطلب **البدء** مربع الاختيار
الذي يؤكد أن الحملة تجري مكالمات حقيقية وتنفق أرصدة ThunderPhone. راجع [الحملات الصادرة](/ar/guides/outbound-campaigns).

قبل أن يبدأ سير العمل في إجراء المكالمات:

- إذا طلب ThunderPhone من مؤسستك تأكيد أن مكالماتها الصادرة
  تتبع TCPA وقوانين الاتصال الأخرى، فيجب على مسؤول تسجيل ذلك
  التأكيد في لوحة التحكم أولاً.
- يجب تفعيل رقم المصدر للمكالمات الصادرة. تصبح الأرقام التي تجلبها من
  مشغّل الاتصالات الخاص بك مؤهلة بعد التحقق منها. تبدأ أرقام ThunderPhone
  كمخصصة للمكالمات الواردة فقط ويمكن الموافقة عليها للاستخدام الصادر: يطلب
  المسؤول ذلك من صفحة أرقام الهاتف. راجع
  [الحصول على رقم هاتف](/ar/guides/get-a-phone-number).
- تقع على عاتق مؤسستك مسؤولية الحصول على موافقة للاتصال بكل رقم
  واتباع قوانين الاتصال المنطبقة. راجع
  [قوانين الاتصال الصادر](/ar/guides/outbound-calling-laws).

## أمثلة على سير العمل

- **جهات اتصال CRM إلى حملة.** أضف جهات اتصال CRM إلى حملة ThunderPhone
  مسودة، ثم ابدأ الحملة بمجرد أن يوافق شخص ما على القائمة.
- **المكالمة المكتملة إلى سجل العميل.** عند اكتمال المكالمة، شغّل الحصول على المكالمة
  واحفظ النص المفرغ ورابط التسجيل في سجل العميل المطابق.
- **الدرجات المنخفضة للمراجعة.** عند تقييم المكالمة، رشّح حسب
  `{{ $json.data.grade.score }}` ووجّه المكالمات ذات الدرجات المنخفضة إلى قائمة انتظار للمراجعة
  مع معرّف المكالمة وتفاصيل الدرجة. يمكن تقييم المكالمة أكثر من مرة،
  ويشغّل كل تنفيذ مكتمل للتقييم المشغّل، لذا احتفظ فقط بأحدث
  `graded_at` لكل معرّف مكالمة.

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

<Note>
  هل ترسل أحداث المكالمات نفسها إلى خادمك بدلاً من ذلك؟ راجع
  [نقاط نهاية Webhook](/ar/webhooks/endpoints).
  يغطي [إجراء مكالمات صادرة](/ar/guides/place-outbound-calls) واجهة API التي تستخدمها
  ميزة إجراء مكالمة صادرة.
</Note>