دليل إعداد التكامل

واتساب + n8n: أرسل رسائل واتساب واستقبلها من سير العمل لديك

يعمل اليوم عبر عقدة HTTP Requestآخر تحقق: أكتوبر 2026

لدى Spun واجهة REST API مبنية لهذا النوع من الأتمتة تحديدًا، ولا يحتاج n8n إلى أي شيء خاص لاستخدامها: عقدة «HTTP Request» مع رمز Bearer ترسل رسائل واتساب، وترفع الوسائط، وتنشئ جهات الاتصال وتحدّثها، وتطبّق التسميات، وتتحقق مما إذا كان الرقم على واتساب. وتستقبل عقدة المشغّل «Webhook» أحداث واتساب الحقيقية في الاتجاه المعاكس، موقّعةً كي تتمكن من إثبات أنها جاءت من Spun.

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

1. أنشئ مفتاح API

  1. 1

    افتح «مفاتيح API»

    في صندوق الوارد في Spun: «الإعدادات»، ثم «الويب هوكس»، ثم «إدارة مفاتيح API»، ثم «مفتاح جديد».

  2. 2

    سمِّه واختر الصلاحيات

    أعطه اسمًا مثل «n8n Production». فعّل فقط ما يحتاجه سير العمل: «Send Messages» للنصوص والوسائط، و«Check Phone Numbers»، و«Manage Contacts»، و«Read Contacts»، و«Manage Labels»، و«Read Labels». وكل نقطة نهاية أدناه تذكر الصلاحية التي تتطلبها.

  3. 3

    انسخه مرة واحدة

    يبدأ المفتاح بـ wap_ ويُعرض مرة واحدة فقط. خزّنه في n8n كبيانات اعتماد (credential)، ولا تلصقه أبدًا في معامل عقدة حيث ينتهي به الأمر في سجل التنفيذ.

  4. 4

    اختياري: اقصر المفتاح على خادم n8n لديك

    لنسخة n8n المستضافة ذاتيًا عنوان IP صادر ثابت، وهذا يجعل مفتاح API أكثر أمانًا بكثير من المعتاد. اضبط «عناوين IP المسموح بها» على المفتاح لتكون عنوان الخروج لخادم n8n أو نطاق CIDR الخاص به، فيصبح المفتاح المسروق عديم الفائدة من أي مكان آخر. وإذا تركت الحقل فارغًا، يعمل المفتاح من أي مكان. والخطأ في ضبطه لا يمنعك أبدًا من الوصول إلى «الإعدادات»، لأنها تستخدم تسجيل دخولك إلى Spun لا المفتاح.

في n8n، أضف المفتاح كبيانات اعتماد من نوع «Header Auth»: اسم الترويسة Authorization، وقيمة الترويسة Bearer wap_YOUR_KEY. وأعد استخدام بيانات الاعتماد هذه نفسها في كل عقدة Spun في كل سير عمل.

2. أرسل رسائل واتساب من سير العمل

أضف عقدة «HTTP Request»، واضبط الطريقة (method) وعنوان URL، وأرفق بيانات اعتماد «Header Auth»، وأرسل JSON. تقع كل نقاط النهاية تحت عنوان URL الأساسي نفسه، https://api.spun.com/api/integrations.

  • send-message (الصلاحية: «Send Messages»): رسالة نصية. إذا صادف أن قناة واتساب غير متصلة، تجيب الواجهة بـ 202 مع queue_id بدلًا من الفشل، وتُرسل الرسالة حين تعود القناة للاتصال.
  • send-media («Send Messages»): صورة أو فيديو أو ملف صوتي أو رسالة صوتية أو مستند، من رابط URL عام أو برفع base64، مع تعليق اختياري على الصور والفيديو والمستندات.
  • check-phone («Check Phone Numbers»): هل لدى هذا الرقم واتساب. تقبل حتى 20 رقمًا في استدعاء واحد، لذا اجمعها في دفعة واحدة بدلًا من التكرار في حلقة.
  • create-contact و update-contact («Manage Contacts»): حافظ على تزامن سجل العميل المحتمل من نموذج أو نظام CRM أو جدول بيانات. تمرير رقم هاتف يحدّث جهة الاتصال الموجودة بدلًا من إنشاء نسخة مكررة.
  • contacts («Read Contacts»): ابحث عن جهة اتصال برقم الهاتف أو بالمعرّف.
  • apply-label و remove-label («Manage Labels»): ضع تسمية على محادثة من مشغّل خارجي، مثلًا ضع التسمية «عميل محتمل جديد» على محادثة لحظة إرسال نموذج.
  • labels («Read Labels»): اعرض التسميات في الحساب، وهي أيضًا أرخص طريقة للتأكد من أن المفتاح يعمل.
إرسال رسالة واتساب (POST /api/integrations/send-message)
POST https://api.spun.com/api/integrations/send-message
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "to": "15551234567",
  "text": "Hi {{ $json.first_name }}, thanks for getting in touch.",
  "idempotency_key": "{{ $execution.id }}"
}

مرّر مفتاح منع التكرار idempotency_key مع عمليات الإرسال، واجعل قيمته ثابتة طوال التشغيل، مثل {{ $execution.id }}. وإذا أعاد n8n تشغيل العقدة، يتعرّف Spun على المفتاح بدلًا من إرسال الرسالة مرتين.

3. أرسل ملفًا أو صورة أو رسالة صوتية

تذهب الوسائط إلى نقطة نهاية منفصلة. قدّم واحدًا فقط من الاثنين: media_url، الذي يجلبه Spun، أو media_base64، الذي يرفعه Spun نيابةً عنك أولًا.

  • قيمة type واحدة من: image أو video أو audio أو voice أو document.
  • يُحمل التعليق على image و video و document. أما الملفات الصوتية والرسائل الصوتية فلا تعليق لها في واتساب.
  • الرسالة الصوتية المرسلة كـ base64 تُحوَّل تلقائيًا إلى الصيغة التي يتوقعها واتساب. أما الرسالة الصوتية الممررة كرابط URL فتُرسل كما هي تمامًا، لذا يجب أن تكون بصيغة ogg أو opus مسبقًا، وإلا فأرسلها كـ base64 ودع Spun يحوّلها.
  • الوسائط لا توضع في قائمة الانتظار عمدًا حين تكون القناة غير متصلة. النص يوضع في قائمة الانتظار، أما الوسائط فتجيب بـ 409 channel_offline بدلًا من ذلك، لأن إعادة تشغيل رسالة وسائط من قائمة الانتظار كانت ستسلّمها كنص. تعامل مع 409 بإعادة المحاولة في n8n بدلًا من اعتباره فشلًا دائمًا.
إرسال مستند (POST /api/integrations/send-media)
POST https://api.spun.com/api/integrations/send-media
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "type": "document",
  "to": "15551234567",
  "media_url": "https://example.com/invoice-1043.pdf",
  "filename": "invoice-1043.pdf",
  "caption": "Your invoice"
}

4. شغّل سير عمل من حدث في واتساب

  1. 1

    أنشئ عقدة Webhook أولًا

    أضف عقدة المشغّل «Webhook» إلى سير عمل جديد وانسخ «Production URL» الخاص بها. لا يخدم n8n هذا العنوان إلا أثناء تفعيل سير العمل، لذا فعّله قبل الاختبار.

  2. 2

    الصق العنوان في Spun

    «الإعدادات»، ثم «الويب هوكس»، ثم «إضافة ويب هوك». الصق عنوان n8n، واختر الأحداث التي يجب أن تشغّله، واحفظ. يوقّع Spun كل تسليم بالسر المعروض لذلك الاشتراك.

  3. 3

    أرسل رسالة تجريبية

    راسل رقم واتساب المتصل من هاتفك. تلتقط عقدة «Webhook» المحتوى الحقيقي، وهو العيّنة التي تبني عليها بقية سير العمل.

  • الأحداث التي يمكنك الاشتراك فيها: رسالة واردة، ورسالة صادرة، وإنشاء جهة اتصال، وتحديث جهة اتصال، وحذف جهة اتصال، وتعيين تسمية، واكتمال تدفق دردشة، ومعالجة رسالة من قائمة الانتظار، وتأهيل عميل محتمل، وأرشفة محادثة، واكتمال مكالمة.
  • الترويسة X-Webhook-Signature هي HMAC-SHA256 لمحتوى الطلب الخام كما هو بالضبط، مكتوبةً بالصيغة sha256 متبوعة بالقيمة الست عشرية (hex digest). تحقق منها مقابل بايتات المحتوى الخام، لا مقابل نسخة أعيد تسلسلها من JSON بعد تحليله، لأن ترتيب المفاتيح غير مضمون أن يبقى كما هو بعد التحليل وإعادة الترميز.
  • تُعاد محاولة التسليم حتى ثلاث مرات: فورًا، ثم بعد 5 ثوانٍ، ثم بعد 30 ثانية، وتنتظر كل محاولة 10 ثوانٍ للحصول على استجابة. وأي استجابة 2xx تُحتسب تسليمًا ناجحًا.
  • وبسبب إعادة المحاولة هذه قد يصل الحدث نفسه مرتين. تبقى قيمة event_id كما هي عبر إعادات المحاولة لحدث واحد، فاستخدمها لتجاهل التكرارات.
ما يرسله Spun عند message.inbound
POST https://your-n8n.example.com/webhook/abc123
X-Webhook-Event: message.inbound
X-Webhook-Delivery: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=<hmac of the raw body>

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "message.inbound",
  "timestamp": "2026-08-18T10:30:00.000Z",
  "org_id": "123",
  "data": {
    "message_id": "[email protected]_ABC123",
    "chat_id": "[email protected]",
    "from": "15551234567",
    "type": "text",
    "text": "Hello!"
  }
}

التحقق من التوقيع أهم مما يبدو: عنوان Webhook هو الشيء الوحيد الذي يحمي سير العمل، وعناوين Webhook في n8n قابلة للتخمين بما يكفي ليستحق الأمر التحقق من التوقيع.

محتوى Webhook من واتساب، حقلًا حقلًا

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

  • قيمة peer_phone_e164 هي null للمجموعات وللمحادثات التي لا يقف خلفها رقم هاتف.
  • إذا لم تكتمل معالجة ملف لحظة إرسال الحدث، تكون media_pending بقيمة true و media_url بقيمة null. ولا يُرسل الحدث مرة أخرى حين يصبح الملف جاهزًا، لذا أضف ملاحظة تشير إلى المحادثة في Spun.
  • يُطلق الحدث conversation.closed حين تُؤرشف محادثة في Spun، و conversation.reopened حين تُعاد، وبهذا يُبقي سير العمل تذكرة أو سجلًا متوافقًا مع صندوق الوارد.
  • إغلاق محادثة أو إعادة فتحها من سير العمل يمر عبر POST /api/integrations/conversations/close و /reopen، ويتطلبان صلاحية «إغلاق وإعادة فتح المحادثات» على المفتاح.
حقول إضافية في message.inbound و message.outbound (للتوضيح)
{
  "is_group": false,
  "peer_phone_e164": "+15551234567",
  "contact_id": "8812",
  "contact_name": "Sarah Miller",
  "contact_email": "[email protected]",
  "type": "image",
  "text": null,
  "caption": "The damaged box",
  "media_url": "https://<signed link, valid for 24 hours>",
  "media_mime": "image/jpeg",
  "media_filename": null,
  "media_size": 182344,
  "media_pending": false
}

ذات صلة: الوثائق: كل حدث وكل حقل، مع تفاصيل التوقيع وإعادة المحاولة

سير عمل جاهز لمكاتب المساعدة

تُشغّل Webhooks والواجهة نفسها سير عمل جاهزًا على n8n يحوّل محادثات واتساب إلى تذاكر في مكتب المساعدة، ويعيد ردود الموظفين إلى واتساب. ولكل منها دليل إعداد.

ذات صلة: كل تكاملات واتساب مع مكاتب المساعدة · Zendesk · Zoho Desk · Freshdesk · HubSpot Service Hub · Jira Service Management

5. الوصف الكامل للواجهة

الوصف الكامل المقروء آليًا للواجهة منشور كمستند OpenAPI 3.1، ويمكن جلبه مجانًا دون الحاجة إلى مفتاح API. فيه كل نقطة نهاية، وكل حقل في الطلب، وشكل كل استجابة، وكل رمز خطأ، وغلاف Webhook (envelope)، وهذا عادةً أسرع من قراءة دليل.

مواصفات OpenAPI 3.1 العامة
curl https://api.spun.com/api/integrations/openapi.json

يستطيع n8n استيراد وصف OpenAPI مباشرةً عند توليد عقدة مخصصة أو عقدة HTTP تصريحية (declarative)، لذا فهذا أقصر طريق من الصفر إلى مجموعة عمليات تعمل.

عقدة Spun أصلية لـ n8n

كل ما سبق يستخدم عقدة «HTTP Request» العامة، ولهذا يعمل اليوم دون انتظار. وهناك عقدة مجتمعية مخصصة لـ Spun مبنية وتمر بمرحلة النشر: فهي تحوّل نقاط النهاية نفسها إلى عمليات مسمّاة بحقول مناسبة، وتضيف بيانات اعتماد Spun مع اختبار اتصال مدمج، وتمنح جانب المشغّل عقدة تشترك وتلغي اشتراكها من تلقاء نفسها حين تفعّل سير العمل أو توقفه، وتتحقق من توقيع كل تسليم نيابةً عنك.

لكنها ليست في سجل العقد المجتمعية في n8n بعد، لذا لا يوجد ما يمكن تثبيته حاليًا، ولا تتظاهر هذه الصفحة بغير ذلك. تصل معها قدرتان: المشغّل الذي يشترك ذاتيًا، والاستعلام الدوري عن سجل الرسائل وفق جدول زمني للحالة التي لا تستطيع فيها نسخة n8n استقبال Webhooks الواردة إطلاقًا. وكلتاهما تعتمد على صلاحيات لمفاتيح API لا يتيحها محرر المفاتيح بعد، لذا توصفان هنا بدلًا من تقديمهما كتعليمات.

إلى أن تُدرج العقدة، يبقى مسار «HTTP Request» في هذه الصفحة هو الطريقة المدعومة لاستخدام Spun مع n8n، ويبقى مدعومًا بعد ذلك أيضًا.

ما يجب معرفته قبل أن تبني عليها

  • حد المعدل 60 طلبًا في الدقيقة لكل مفتاح API عبر كل نقاط النهاية. اجمع فحوص الأرقام حتى 20 في كل استدعاء، وضع عقدة «Wait» داخل أي حلقة تتفرع على قائمة كبيرة.
  • تحتاج نقطة النهاية remove-label إلى معرّف التسمية، بخلاف apply-label التي تقبل اسم التسمية أيضًا. استدعِ نقطة النهاية labels مرة واحدة في بداية سير العمل واحتفظ بالمعرّفات.
  • تُنشأ اشتراكات Webhooks داخل «الإعدادات» في Spun حاليًا. ولا تستطيع أداة سير العمل بعدُ إنشاء اشتراكها الخاص بمفتاح يمكنك إصداره من محرر المفاتيح.
  • هذه واجهة تعتمد على المفاتيح. لا توجد لها شاشة OAuth بعنوان «اربط حساب Spun الخاص بك»، وهذا مقصود: فاتصالات مساعدي الذكاء الاصطناعي تستخدم آلية منفصلة قائمة على الإذن ومفاتيح منفصلة، ولا يمكن الجمع بين الاثنين على مفتاح واحد.
  • كل شيء محصور في رقم واتساب الذي ينتمي إليه المفتاح. والحساب الذي لديه عدة أرقام يكون لكل رقم فيه مفتاح خاص بدلًا من مفتاح واحد يشملها جميعًا.

ذات صلة: واتساب + Zapier وMake · واتساب + Google Sheets (تكامل أصلي بالكامل، دون حاجة إلى مفتاح API) · واتساب + HubSpot CRM

الأسئلة الشائعة

هل عليّ انتظار عقدة Spun رسمية لاستخدام n8n؟

لا. تغطي عقدة «HTTP Request» كل الإجراءات اليوم: إرسال النصوص والوسائط، وجهات الاتصال، والتسميات، وفحص الأرقام، مع عقدة المشغّل «Webhook» للأحداث الواردة. وتُنشر عقدة أصلية لتسهيل إعداد الأمور نفسها، لا لجعلها ممكنة.

هل توجد عقدة Spun في سجل العقد المجتمعية في n8n؟

ليس بعد. الحزمة مبنية لكنها غير مدرجة، لذا لا يوجد ما يمكن تثبيته حاليًا. إعداد «HTTP Request» في هذه الصفحة يعمل الآن ويستمر في العمل بعد إدراج العقدة.

كيف تتم المصادقة؟

أنشئ مفتاح API من «الإعدادات»، ثم «الويب هوكس»، ثم «إدارة مفاتيح API»، وفعّل الصلاحيات التي تحتاجها فقط، وخزّنه في n8n كبيانات اعتماد «Header Auth» ترسل Authorization: Bearer wap_YOUR_KEY. ويمكنك أيضًا قصر المفتاح على عنوان IP لخادم n8n لديك أو على نطاق عناوينه.

كيف أمنع إعادة المحاولة في n8n من إرسال رسالة واتساب نفسها مرتين؟

أرسل idempotency_key مع الطلب واجعله ثابتًا طوال التشغيل، مثل معرّف التنفيذ في n8n. يتعرّف Spun على المفتاح المكرر ويعيد النتيجة الأصلية بدلًا من الإرسال مرة أخرى.

كيف أتحقق من أن Webhook جاء فعلًا من Spun؟

يحمل كل تسليم الترويسة X-Webhook-Signature، وهي HMAC-SHA256 للمحتوى الخام كما هو بالضبط باستخدام سر الاشتراك، بالصيغة sha256 متبوعة بالقيمة الست عشرية. احسب HMAC نفسه على محتوى الطلب الخام وقارن. استخدم البايتات الخام بدلًا من إعادة ترميز JSON بعد تحليله، لأن ترتيب المفاتيح قد يتغير فتفشل المقارنة مع تسليمات صالحة تمامًا.

ماذا يحدث إذا كانت قناة واتساب غير متصلة حين يعمل سير العمل؟

تُقبل الرسائل النصية وتوضع في قائمة الانتظار، وتخبرك الاستجابة بذلك مع معرّف في قائمة الانتظار يمكنك الاستعلام عنه. أما الوسائط فلا توضع في قائمة الانتظار، وتعيد بدلًا من ذلك خطأ يفيد بأن القناة غير متصلة، لأن رسالة الوسائط المنتظرة كانت ستصل كنص عادي. دع n8n يعيد محاولة تلك العقدة.

ما حدود المعدل؟

60 طلبًا في الدقيقة لكل مفتاح API، عبر كل نقاط النهاية. ويقبل فحص الأرقام 20 رقمًا في استدعاء واحد، وهي أسهل طريقة للبقاء دون الحد بفارق مريح عند التحقق من قائمة.

أين المرجع الكامل للواجهة؟

وصف OpenAPI 3.1 لكل نقطة نهاية منشور على https://api.spun.com/api/integrations/openapi.json ولا يحتاج إلى مفتاح API لقراءته.

احصل على مفتاح API وابدأ البناء

يأتي الوصول إلى API مع باقات واتساب في Spun، إلى جانب صندوق الوارد المشترك للفريق، والردود بالذكاء الاصطناعي، وتكاملات Google Sheets و HubSpot الأصلية. أسعار ثابتة تبدأ من 179 د.إ شهريًا، وتجربة مجانية.

ابدأ مجانًا: 7 أيام من كل الميزات

عرض كل التكاملات