🚀 n8n-nodes-fourjawaly

مجموعة شاملة من n8n nodes للتكامل مع 4Jawaly API - إرسال SMS وWhatsApp والمزيد!

---

✨ المميزات الرئيسية

📱 4Jawaly SMS Sender

• ✅ إرسال SMS فردي وجماعي
• ✅ الحصول على رصيد الحساب
• ✅ إدارة أسماء المرسلين
• ✅ معالجة ذكية للدفعات (Batch Processing)

💬 4Jawaly WhatsApp Sender

• ✅ إرسال رسائل تفاعلية بأزرار (Interactive Buttons)
• ✅ إرسال قوائم تفاعلية (Interactive Lists)
• ✅ إرسال القوالب المعتمدة (Templates)
• ✅ إرسال المواقع (Locations) مع دعم Google Maps
• ✅ إرسال الوسائط (صور، فيديو، صوت، ملفات)
• ✅ إدارة المحادثات (Assign/Unassign)
• ✅ إدارة التسميات (Labels)
• ✅ قائمة المشاريع والفريق
• ✅ Validation للأزرار المكررة - يمنع الأخطاء قبل الإرسال

🛠️ 4Jawaly Actions (أدوات مساعدة)

• ✅ كشف اللغة (عربي/إنجليزي)
• ✅ تحويل الأرقام العربية إلى إنجليزية
• ✅ كشف الدولة من رقم الهاتف
• ✅ توليد أكواد عشوائية (OTP)
• ✅ Base64 Encode/Decode
• ✅ Hash Text (MD5, SHA256, SHA512)
• ✅ استبدال الكلمات المفتاحية في النصوص
• ✅ 🔍 كشف وجود الصوت في JSON (Detect Audio)
  • يكشف الملفات الصوتية تلقائياً في JSON
  • يفحص type === "audio" والامتدادات الصوتية
  • يرجع URL للملفات الصوتية الموجودة
• ✅ 🎙️ تحويل الصوت إلى نص (Transcribe Audio)
  • دعم ممتاز للغة العربية باستخدام OpenAI Whisper
  • تحويل ملفات WhatsApp الصوتية (.ogg) إلى نص
  • مصادر متعددة: File Path، URL، Binary Data
  • صيغ مخرجات متنوعة: Text، JSON، Verbose JSON
  • 🌍 ترجمة تلقائية: يترجم النص تلقائياً للعربية والإنجليزية

---

📦 التثبيت

الطريقة 1: من npm (الأسهل) ⭐

npm install n8n-nodes-fourjawaly

الطريقة 2: من داخل n8n (مباشرة)

1. افتح n8n
2. اذهب إلى Settings → Community Nodes
3. اضغط Install
4. أدخل: n8n-nodes-fourjawaly
5. اضغط Install
6. أعد تشغيل n8n

الطريقة 3: من المصدر

git clone https://github.com/4jawalycom/n8n-nodes-4jawaly.git
cd n8n-nodes-4jawaly
npm install
npm run build
npm link

---

🚀 الاستخدام السريع

1️⃣ إعداد Credentials

1. في n8n، اذهب إلى Credentials → New
2. ابحث عن 4Jawaly API
3. اختر طريقة المصادقة:
   • Basic Auth: أدخل App ID و App Secret
   • Basic Raw: أدخل Authorization header كامل
   • JWT Token: أدخل JWT token
   • Auth0: أدخل بيانات Auth0
4. اضغط Save

2️⃣ إرسال SMS

Manual Trigger
  ↓
4Jawaly SMS Sender
  Operation: Send SMS
  Phone: 966500000000
  Message: مرحباً بك في 4jawaly!
  Sender: YourBrand
  ↓
Success ✅

3️⃣ إرسال WhatsApp مع أزرار

Manual Trigger
  ↓
4Jawaly WhatsApp Sender
  Operation: Send Interactive Message
  Phone: 201033588998
  Message: اختر أحد الخيارات:
  Button 1: نعم ✅
  Button 2: لا ❌
  Button 3: ربما 🤔
  WhatsApp Project ID: 591
  ↓
Success ✅

4️⃣ استخدام Actions (كشف اللغة)

Manual Trigger
  ↓
4Jawaly Actions
  Operation: Detect Language
  Text: مرحباً بك
  ↓
Result: عربي (Arabic) ✅

5️⃣ كشف الصوت في JSON

Webhook (WhatsApp Message)
  ↓
4Jawaly Actions
  Operation: Detect Audio
  JSON Path: (اترك فارغ للبحث في كل JSON)
  ↓
Result: {
  hasAudio: true,
  message: "نعم، يحتوي على صوت",
  audioType: "audio",
  firstAudioUrl: "https://...File.ogg",
  audioFilesCount: 1
} ✅

6️⃣ تحويل صوت WhatsApp إلى نص

Manual Trigger
  ↓
4Jawaly Actions
  Operation: Transcribe Audio
  Service: OpenAI Whisper
  Audio Source: File Path
  File Path: /path/to/WhatsApp Ptt 2025-11-12 at 4.36.17 PM.ogg
  Language: Arabic (العربية)
  Response Format: JSON
  ↓
Result: {
  text: "النص المستخرج من الملف الصوتي",
  language: "ar",
  success: true
} ✅

7️⃣ تحويل صوت + ترجمة تلقائية 🌍

Webhook (WhatsApp Voice Message)
  ↓
4Jawaly Actions
  Operation: Transcribe Audio
  Service: OpenAI Whisper
  Audio Source: URL
  Audio URL: {{ $('Webhook').item.json.body.whatsapp_message.text.body }}
  Language: Auto Detect
  Response Format: JSON
  Auto Translate: ✅ true  ← تفعيل الترجمة
  ↓
Result: {
  text: "السلام عليكم كيف حالك",
  language: "auto",
  translations: {
    original_language: "arabic",
    original_text: "السلام عليكم كيف حالك",
    arabic_text: "السلام عليكم كيف حالك",
    english_text: "Peace be upon you, how are you"
  }
} ✅

// إذا كان بالإنجليزية:
{
  text: "Hello how are you",
  translations: {
    original_language: "english",
    original_text: "Hello how are you",
    arabic_text: "مرحباً كيف حالك",
    english_text: "Hello how are you"
  }
}

// إذا كان بلغة أخرى:
{
  text: "Bonjour comment allez-vous",
  translations: {
    original_language: "other",
    original_text: "Bonjour comment allez-vous",
    arabic_text: "مرحباً كيف حالك",
    english_text: "Hello how are you"
  }
}

---

📚 الوثائق

• 📖 دليل 4Jawaly الكامل
• 🧪 دليل الاختبار السريع
• 🔧 حل المشاكل
• 📋 الوثائق بالعربية

---

📋 قائمة الـ Nodes

📱 4Jawaly SMS Sender

العمليات المتاحة:

1. Send SMS - إرسال رسالة نصية واحدة
2. Send Bulk SMS - إرسال رسائل جماعية
3. Get Balance - الحصول على رصيد الحساب والباقات
4. Get Senders - الحصول على أسماء المرسلين المتاحة

---

💬 4Jawaly WhatsApp Sender

العمليات المتاحة:

📤 إرسال الرسائل:

1. Send Interactive Message - رسائل تفاعلية بأزرار (حتى 3 أزرار)
2. Send Interactive List - قوائم تفاعلية (حتى 10 عناصر)
3. Send Template - إرسال قوالب WhatsApp المعتمدة
4. Send Location - إرسال موقع (إحداثيات أو Google Maps)
5. Send Image - إرسال صورة مع نص اختياري
6. Send Audio - إرسال ملف صوتي (MP3, OGG, M4A - حد أقصى 16MB)
7. Send Video - إرسال فيديو (MP4 - حد أقصى 16MB)
8. Send Document - إرسال ملف (PDF, DOCX, XLSX - حد أقصى 100MB)

👥 إدارة المحادثات:
9. Assign Conversation - تعيين محادثة لوكيل
10. Unassign Conversation - إلغاء تعيين محادثة
11. Get Team List - الحصول على قائمة الفريق

🏷️ إدارة التسميات:
12. Assign Label - إضافة تسمية لمحادثة
13. List Labels - عرض قائمة التسميات
14. Delete Label - حذف تسمية

📊 إدارة المشاريع:
15. List Projects - عرض مشاريع WhatsApp

---

🛠️ 4Jawaly Actions

العمليات المتاحة:

🌐 اللغة والنصوص:

1. Detect Language - كشف لغة النص (عربي/إنجليزي)

   • يدعم 3 صيغ للنتيجة: عربي، إنجليزي، أو كود (ar/en)
   • يعطي إحصائيات تفصيلية عن النص

2. Convert to English - تحويل الأرقام العربية إلى إنجليزية

   • مثال: ١٢٣٤٥ → 12345

3. Replace Keywords - استبدال الكلمات المفتاحية

   • مثال: "مرحباً {{name}}" → "مرحباً أحمد"

📱 أرقام الهواتف:
4. Detect Country - كشف الدولة من رقم الهاتف

• يدعم جميع الدول العربية + دول رئيسية أخرى
• يتحقق من صحة طول الرقم
• يعطي: اسم الدولة، العلم، كود الدولة

🔐 الأمان والتشفير:
5. Generate Random Code - توليد أكواد عشوائية

• أنواع: رقمي، أحرف وأرقام، أحرف فقط، أحرف كبيرة، أحرف صغيرة
• مثالي لـ OTP codes

6. Base64 Encode/Decode - تشفير وفك تشفير Base64

7. Hash Text - تحويل النص إلى hash

   • خوارزميات: MD5, SHA-1, SHA-256, SHA-512

🔍 كشف ومعالجة الصوت:
8. Detect Audio - كشف وجود ملفات صوتية في JSON

• يفحص type === "audio" تلقائياً
• يكشف الامتدادات: .ogg, .mp3, .wav, .m4a, .aac, وأكثر
• يعطي URL للملفات الموجودة
• مثالي للـ Webhooks من WhatsApp

9. Transcribe Audio - تحويل الصوت إلى نص (Speech to Text)

المميزات:

• 🌟 دعم ممتاز للغة العربية - باستخدام OpenAI Whisper API
• 📁 مصادر متعددة:
  • File Path: مسار ملف محلي
  • URL: رابط مباشر للملف
  • Binary Data: من node سابق
• 🔤 صيغ الإخراج:
  • Text Only: النص فقط
  • JSON: مع تفاصيل إضافية
  • Verbose JSON: مع timestamps تفصيلية
  • SRT: ملفات ترجمة
  • VTT: ملفات ترجمة ويب
• 🌍 لغات مدعومة:
  • العربية (دعم ممتاز)
  • الإنجليزية
  • الفرنسية، الألمانية، الإسبانية، وأكثر
  • Auto-detect: كشف تلقائي
• 🔧 خيارات متقدمة:
  • Temperature: التحكم في دقة النتائج
  • Prompt: نص توجيهي لتحسين الدقة
  • Translate: ترجمة تلقائية للإنجليزية

حالات الاستخدام:

• 📱 تحويل رسائل WhatsApp الصوتية
• 🎥 استخراج نص من الفيديوهات
• 📝 تفريغ الاجتماعات والمقابلات
• 🎧 تحويل البودكاست إلى نص
• 📚 إنشاء ترجمات للفيديوهات

---

🎯 حالات الاستخدام

للـ SMS:

• 📲 OTP Codes - أكواد التحقق الثنائي
• 📦 Order Notifications - إشعارات الطلبات
• 📢 Marketing Campaigns - الحملات التسويقية
• ⏰ Alerts & Reminders - التنبيهات والتذكيرات

للـ WhatsApp:

• 💬 Customer Support - دعم العملاء التفاعلي
• 🤖 Chatbots - بناء بوتات ذكية
• 📊 Surveys - استطلاعات الرأي
• 🎯 Lead Generation - جمع بيانات العملاء المحتملين
• 📍 Location Sharing - مشاركة المواقع
• 📎 File Sharing - مشاركة الملفات والمستندات

للـ Actions:

• 🌍 Multi-language Support - دعم متعدد اللغات
• ✅ Phone Validation - التحقق من أرقام الهواتف
• 🔑 OTP Generation - توليد أكواد التحقق
• 🔐 Data Security - تشفير البيانات

---

🔄 التحديثات

لتحديث الإصدار:

./update-version.sh

هذا سيقوم بـ:

• ✅ توليد رقم إصدار جديد تلقائياً
• ✅ تحديث package.json
• ✅ بناء المشروع
• ✅ إنشاء الحزمة
• ✅ إنشاء Git tag
• ✅ تجهيز الملفات للنشر

---

🤝 المساهمة

المساهمات مرحب بها! يرجى:

1. Fork المشروع
2. إنشاء branch جديد (git checkout -b feature/amazing-feature)
3. Commit التغييرات (git commit -m 'Add amazing feature')
4. Push إلى Branch (git push origin feature/amazing-feature)
5. فتح Pull Request

---

📝 الترخيص

MIT License - راجع LICENSE.md

---

📞 الدعم

• GitHub Issues: إنشاء issue
• دعم 4Jawaly: support@4jawaly.com
• الموقع: https://www.4jawaly.com

---

🙏 شكر خاص

• n8n - منصة workflow automation
• 4Jawaly - خدمة SMS API

---

صنع بـ ❤️ لمجتمع n8n العربي