n8n-nodes-zernio-messaging

حزمة Community Node مخصصة لـ Autoverse Unified Inbox. تعتمد على العقد الرسمي الحالي v1 ولا ترسل أي طلبات إلى عناوين يحددها المستخدم خارج Base URL الموجود في الاعتماد.

ما تم تنفيذه

• Autoverse Omnichannel: رفع Binary مباشر حتى 25MB عبر /v1/media/upload-direct، وتنزيل ميديا الواردة إلى Binary داخل n8n حتى 50MB افتراضيًا، ثم إرسال نص، رابط مرفق، WhatsApp/Generic Template، WhatsApp Interactive، Location، Contact، وRaw JSON مضبوط.
• عمليات المحادثات والرسائل: بدء محادثة، قائمة/بحث/قراءة المحادثات، قائمة الرسائل، تعديل وحذف الرسائل، reactions، typing، وmark read.
• Autoverse Omnichannel Trigger: استقبال Webhooks والتحقق من X-Zernio-Signature أو legacy X-Late-Signature بـ HMAC-SHA256، مع فلتر أحداث ومنع Event IDs المكررة خلال دورة العمل.
• حماية الأسرار: API key داخل Credential فقط ولا يدخل في json أو رسائل الخطأ.
• Idempotency-Key اختياري للإرسال؛ Autoverse يحتفظ بالمفاتيح الناجحة 24 ساعة. لا توجد إعادة محاولات صامتة.
• continueOnFail يعيد عنصر خطأ مرتبطًا بالعنصر الأصلي.
• downloadMedia يرسل Authorization فقط إلى نطاق Zernio/النطاق الأساسي الموثوق، ويجلب CDN الخارجي بدون Authorization. يدعم forceAnonymous وmaxBytesMB وbinaryPropertyName.
• الأسماء القديمة sendTypingIndicator وmarkAsRead ما زالت aliases لنفس العمليات الجديدة، لذلك لا تحتاج Workflows القديمة إلى تعديل.
• حقول الـCollections اختيارية على مستوى تعريف n8n؛ التحقق من Template Name وContact Name يتم وقت التنفيذ فقط، حتى لا تظهر أخطاء Missing or invalid required parameters: name, language في عمليات مثل downloadMedia أو typing.

التثبيت

npm install
npm run build
npm pack
# ثبّت ملف tgz الناتج داخل n8n أو انسخ الحزمة إلى مجلد community-nodes

أضف Credential باسم Autoverse Omnichannel API، أدخل API Key، واترك Base URL الافتراضي https://zernio.com/api.

إرسال رسالة

اختر Send Message، أدخل Account ID وConversation ID، ثم نوع الرسالة. جميع الحقول تدعم Expressions مثل:

{{$json.accountId}}
{{$json.conversationId}}
{{$json.message}}
{{$json.orderId + ":" + $json.attempt}}

للمرفقات عبر رابط يجب أن يكون الرابط عامًا. لرفع Binary، استخدم Upload Binary Media، واختر اسم خاصية Binary؛ يرجع Autoverse رابطًا عامًا يمكن تمريره إلى Send Message. الحد الرسمي 25MB والتخزين المؤقت يحذف بعد 7 أيام.

لتنزيل مرفق قادم من Webhook، استخدم Download Media وأدخل {{$json.message.attachments[0].url}} أو مسار الرابط الموجود في بياناتك. روابط Autoverse فقط تستخدم Credential؛ روابط fbcdn.net أو CDN الخارجية لا تستلم API Key.

WhatsApp

القوالب المنظمة تستخدم Template Fields بدل كتابة JSON يدويًا، مع اسم القالب واللغة والمكونات ووسائط الرأس. وتبقى Template Raw JSON متاحة داخل وضع Raw المتقدم. Interactive له JSON مستقل لأن مخططه متشعب حسب نوع الرسالة. جهات الاتصال لها واجهة منظمة للاسم والهاتف والبريد والمؤسسة. Additional Fields تجمع quick replies وbuttons وreply-to وlink preview وcategory وmessage tag وTelegram reply markup. يدعم اختيار category قيم utility وmarketing وauthentication، لكن صلاحية القيمة تعتمد على المنصة والحساب والعقد الحالي؛ استجابة Autoverse هي المرجع النهائي.

Webhook Trigger

أنشئ subscription في Autoverse Dashboard → Webhooks بنفس URL الذي يعرضه n8n، واضبط secret نفسه في Trigger. Autoverse يرسل Event ID ثابتًا في X-Zernio-Event-Id ويمكن فلترة message.received مثلًا. يفضل تشغيل HTTPS وعدم تعطيل التوقيع.

أمثلة Workflow

1. Webhook/AI Agent → Autoverse Omnichannel، مع {{$json.conversationId}} و{{$json.output}}.
2. Google Sheets/CRM → Split in Batches → Autoverse Omnichannel، مع مفتاح {{$json.customerId + ":" + $execution.id}} إذا كان مناسبًا لسياسة التكرار.
3. Autoverse Omnichannel Trigger (message.received) → IF/Router → Template أو Interactive reply.

الاختبارات

npm run build
npm test
npm run lint
npm run pack:check

لا توجد اختبارات Live في الحزمة؛ لا يتم الادعاء بإرسال حقيقي دون API key وتجربة صريحة من المستخدم. أخطاء 429 و5xx لا تعاد تلقائيًا لأن فشل الاستجابة قد يحدث بعد قبول الرسالة من المنصة؛ استخدم reconciliation وIdempotency وفق توثيق Zernio.

مصادر العقد

• Autoverse OpenAPI
• Autoverse Omnichannel API Docs
• n8n Community Nodes