يحوّل هذا المسار كل رسالة صوتية واردة من WhatsApp إلى نص داخل n8n. وهو نسخة n8n من السكربت الموجود في دليل رسائل WhatsApp الصوتية: التحويل نفسه بـ ffmpeg وطلب التفريغ نفسه. أسماء العقد والخيارات أدناه رُوجعت مقابل توثيق n8n وشيفرته المصدرية في 2026-11-14؛ والروابط في المصادر.
ما تحتاج إليه
- n8n مستضاف ذاتيًا. يقول توثيق n8n إن عقدة Execute Command غير متاحة على n8n Cloud، ومعطّلة افتراضيًا منذ n8n 2.0.
- ffmpeg على مضيف n8n. مع Docker، يعمل الأمر داخل حاوية n8n لا على مضيف Docker، لذا يجب أن يكون ffmpeg داخل الصورة (image).
- بيانات اعتماد WhatsApp Business Cloud في n8n، مربوطة بتطبيق Meta مع حساب WhatsApp Business الخاص بك، إضافة إلى رمز الوصول (access token) لذلك التطبيق.
- مفتاح BroadNet API. تحصل الحسابات الجديدة على رصيد مبدئي بقيمة $5 دون بطاقة، ويعمل عليه نموذجا التفريغ كلاهما.
تجهيز n8n: ffmpeg وExecute Command ومجلد للملفات
صورة Docker الرسمية لـ n8n لا تحتوي على مدير حزم. ويشرح توثيق n8n كيف تعيد apk في صورة مخصّصة لتثبيت curl؛ وملف Dockerfile نفسه مع ffmpeg بدلًا من curl يعطيك ffmpeg:
FROM n8nio/n8n
USER root
# Restore the apk package manager (removed from the base image)
COPY --from=alpine:3.22 /sbin/apk /sbin/apk
COPY --from=alpine:3.22 /lib/apk /lib/apk
COPY --from=alpine:3.22 /usr/lib/libapk* /usr/lib/
RUN apk add --no-cache ffmpeg
USER node
ابنِ الصورة بالأمر docker build -t n8n-ffmpeg . وشغّل n8n-ffmpeg بدلًا من n8nio/n8n. استبدال ffmpeg تعديل منّا على مثال curl في توثيق n8n، لذا شغّل ffmpeg -version مرة واحدة في عقدة Execute Command للتأكد.
ثم اضبط متغيرَي بيئة:
| المتغير | القيمة | السبب |
|---|---|---|
NODES_EXCLUDE |
"[]" |
عقدة Execute Command محظورة افتراضيًا. والقائمة الفارغة تلغي حظرها وحظر كل عقدة أخرى يحظرها n8n افتراضيًا، فأعد إضافة أي عقدة تريد إبقاءها محظورة. |
N8N_RESTRICT_FILE_ACCESS_TO |
اتركه دون ضبط | منذ n8n 2.0 قيمته الافتراضية ~/.n8n-files. وفي الصورة الرسمية هذا هو /home/node/.n8n-files، المجلد المستخدم أدناه. |
المسار عقدة بعقدة
| # | العقدة | الإعداد |
|---|---|---|
| 1 | WhatsApp Trigger | Event: Messages |
| 2 | If | {{ $json.messages?.[0]?.type ?? '' }} is equal to audio |
| 3 | WhatsApp Business Cloud | Resource Media، وOperation Download، وMedia ID {{ $json.messages[0].audio.id }} |
| 4 | HTTP Request | GET {{ $json.url }}، مع الترويسة Authorization: Bearer <WhatsApp access token>، وResponse Format File، وPut Output in Field data |
| 5 | Read/Write Files from Disk | Write File to Disk، والمسار /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg، وInput Binary Field data |
| 6 | Execute Command | أمر ffmpeg أدناه |
| 7 | Read/Write Files from Disk | Read File(s) From Disk، ومسار ملف .wav، وPut Output File in Field data |
| 8 | HTTP Request | POST إلى نقطة نهاية التفريغ، أدناه |
العقد من 5 إلى 7 موجودة لأن Execute Command تشغّل أمر shell ولا تأخذ البيانات الثنائية (binary data) من n8n، فيذهب الملف إلى القرص ثم يعود منه.
استورد المسار بدلًا من بنائه
نزّل المسار بصيغة JSON لـ n8n (8 عقد، مضبوطة للعربية) واستورده في n8n عبر Import from File. لا يحتوي الملف على أي مفاتيح أو رموز وصول. كل عقدة تحتاج إلى تسجيل دخول فيها بيانات اعتماد مؤقتة يبدأ اسمها بـ REPLACE:؛ افتح تلك العقد الأربع واختر بيانات اعتمادك. رُوجعت أسماء أنواع العقد وأسماء المعاملات مقابل الشيفرة المصدرية لـ n8n في 2026-11-14؛ ويشرح الدليل أدناه كل عقدة، فيمكنك أيضًا بناء المسار يدويًا.
1–2. التشغيل عند وصول الرسائل، والإبقاء على الصوت فقط
في الشيفرة المصدرية لـ n8n، يُخرج WhatsApp Trigger عنصرًا واحدًا لكل تغيير في webhook من Meta، وقائمة الرسائل تحت messages. النصوص والصور والرسائل الصوتية كلها تصل عبر حدث Messages، لذا لا تمرّر عقدة If إلا العناصر التي تكون قيمة type في رسالتها الأولى audio. وإشعارات التسليم والقراءة تصل عبر الحدث نفسه من دون قائمة messages؛ والتعبير ?? '' يحوّل هذه القيمة المفقودة إلى نص فارغ حتى لا يفشل فحص النوع الصارم عليها.
يسمح WhatsApp برابط webhook مسجّل واحد لكل تطبيق. ويحذّر توثيق n8n من أن التبديل بين رابطَي الاختبار والإنتاج في الـ trigger يستبدل الرابط المسجّل، فيتوقف الرابط الآخر عن استقبال الأحداث.
3–4. تنزيل الرسالة الصوتية من Meta
تستدعي عملية Download في عقدة WhatsApp نقطة نهاية الوسائط في Meta بمعرّف الوسائط، وتعيد JSON فيه url، لا الملف الصوتي. ويقول توثيق Meta إن هذا الرابط صالح لمدة 5 دقائق وإن التنزيل يفشل من دون رمز الوصول الخاص بك. لذا تجلب عقدة HTTP Request التالية {{ $json.url }} مع الرمز في ترويسة Authorization، وتحفظ الاستجابة كملف في الحقل data. وفي n8n، خزّن الرمز في بيانات اعتماد من نوع Header Auth (الاسم Authorization، والقيمة Bearer متبوعة بالرمز) بدلًا من كتابته داخل العقدة.
5–7. التحويل إلى WAV بـ ffmpeg
اكتب الملف إلى القرص (العقدة 5)، ثم حوّله في عقدة Execute Command (العقدة 6):
ffmpeg -y -loglevel error -i /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg -ar 16000 -ac 1 /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.wav
الخياران -ar 16000 -ac 1 ينتجان WAV أحادي القناة بتردد 16 kHz، وهو التحويل الذي يستخدمه توثيق BroadNet للرسائل الصوتية. ومعرّف الوسائط رقم، فاستخدامه في اسم ملف آمن. وتقرأ العقدة 7 ملف .wav وتعيده إلى الحقل data.
8. التفريغ
أنشئ بيانات اعتماد ثانية من نوع Header Auth لـ BroadNet (الاسم Authorization، والقيمة Bearer متبوعة بمفتاح BroadNet). ثم اضبط آخر عقدة HTTP Request:
| الحقل | القيمة |
|---|---|
| Method | POST |
| URL | https://inference.broadnet.ai/v1/audio/transcriptions |
| Authentication | Generic Credential Type، ثم Header Auth، ثم بيانات اعتماد BroadNet |
| Send Body | مفعّل، وBody Content Type Form-Data |
معامل الجسم model |
broadnet/cohere-transcribe-arabic (أو broadnet/cohere-transcribe للغات الـ 13 الأخرى) |
معامل الجسم language |
ar (أو en، es، …) |
معامل الجسم file |
Parameter Type n8n Binary File، وInput Data Field Name data |
تصل الاستجابة بصيغة JSON والنص المفرّغ في text، فتقرأ العقد اللاحقة {{ $json.text }}. وهو الطلب نفسه الذي يرسله أمر curl هذا:
curl https://inference.broadnet.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-F model=broadnet/cohere-transcribe-arabic \
-F language=ar \
-F file=@voice-note.wav
أرسل language دائمًا. فمن دونه قد تعود العربية مكتوبة بحروف لاتينية.
ماذا تفعل بالنص
احفظه في نظام CRM أو نظام الدعم الفني لديك، أو مرّره إلى نموذج محادثة ليلخّص الرسالة أو يصنّفها. ويشرح دليل n8n المتوافق مع OpenAI كيف توجّه عقدة OpenAI Chat Model في n8n إلى BroadNet بالمفتاح نفسه. وللتنظيف، أضف عقدة Execute Command أخيرة تحذف الملفين الخاصين بمعرّف الوسائط ذاك.
حل المشكلات
- الـ trigger لا يستقبل شيئًا. تحقق من أن المسار منشور على رابط الإنتاج، وأن تطبيق Meta مشترك في حساب WhatsApp Business؛ إذ يقول توثيق n8n إن n8n لا ينشئ هذا الاشتراك.
- تنزيل الوسائط يعيد 404. انتهت صلاحية الرابط بعد 5 دقائق. يقول توثيق Meta أن تطلب رابط وسائط جديدًا، وأن تجدّد رمز الوصول إن فشل ذلك أيضًا.
- “Unrecognized node type” أو عقدة Execute Command مفقودة. هي محظورة افتراضيًا منذ n8n 2.0؛ اضبط
NODES_EXCLUDE. ffmpeg: not found. الصورة لا تحتوي على ffmpeg؛ ابنِ الصورة المخصّصة أعلاه.- الوصول إلى الملف غير مسموح. اكتب تحت
/home/node/.n8n-files، أو اضبطN8N_RESTRICT_FILE_ACCESS_TOعلى المجلد الذي تستخدمه. - 400 أو 413 أو 429 من BroadNet. يعني 413 أن الملف أكبر من 26,214,400 بايت (نحو 13 دقيقة من WAV أحادي القناة بتردد 16 kHz)؛ ويعني 429 كثرة الطلبات في الوقت نفسه. راجع رموز أخطاء BroadNet وإعادة المحاولة.
الدقة واللهجات ومقارنة سعر BroadNet بواجهات تحويل الكلام إلى نص الأخرى موجودة في دليل تحويل الكلام العربي إلى نص. ولأسعار المعالجة الدفعية والبث لأكثر من 20 منتجًا لتحويل الكلام إلى نص، مع مصدر كل سعر وتاريخ مراجعته، راجع مؤشر أسعار واجهات تحويل الكلام إلى نص المفتوح.
