إرسال رسائل القوالب مع متغيرات مخصصة عبر WhatChimp API

أرسل رسائل القوالب مع بيانات المشتركين الديناميكية عبر API

Updated 10 February 2026

عندما ترسل رسائل قوالب WhatsApp عبر WhatChimp، غالباً ما تريد تخصيصها بمعلومات خاصة بالمشترك مثل أسماء الشركات والمواقع وتفاصيل الحساب أو التفضيلات. الحقول المخصصة (تسمى أيضاً المتغيرات المخصصة) تتيح لك تخزين هذه البيانات مباشرة على ملف تعريف كل مشترك. عندما يشير قالبك إلى هذه الحقول، يسحب API تلقائياً القيم من بيانات المشترك المخزنة.

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

هل تحتاج لإرسال قيم مختلفة مع كل رسالة؟ إذا كنت ترسل بيانات ديناميكية تتغير لكل رسالة (مثل رموز OTP أو أرقام الطلبات أو معرفات التتبع)، استخدم متغيرات القالب بدلاً من ذلك. الحقول المخصصة هي للبيانات التي تبقى مع ملف تعريف المشترك.

Video: https://www.youtube.com/watch?v=yd1O0Sd_zDQ

كيف تعمل المتغيرات المخصصة مع القوالب

يتم تخزين الحقول المخصصة على ملف تعريف المشترك في WhatChimp. عندما ترسل قالباً يتضمن عناصر نائبة للحقول المخصصة، يسترجع النظام تلقائياً القيم من بيانات ذلك المشترك ويدرجها في الرسالة.

إليك التدفق النموذجي:

الخطوة أ. تقوم بتعيين company="Acme Corp" و country="United States" على مشترك باستخدام API أو واجهة المستخدم.

الخطوة ب. رسالة القالب المعتمدة تقول: "مرحباً {{first_name}}، عرض خاص لعملاء {{company}} في {{country}}!"

الخطوة ج. تستدعي API الإرسال فقط باسم القالب ورقم هاتف المشترك — لا حاجة لمعاملات المتغيرات.

الخطوة د. يتلقى المستلم: "مرحباً John، عرض خاص لعملاء Acme Corp في United States!"

يسحب النظام "Acme Corp" و "United States" من الحقول المخصصة المخزنة للمشترك تلقائياً. لا تمرر أبداً هذه القيم في طلب الإرسال.

الخطوة 1: إنشاء حقول مخصصة

قبل أن تتمكن من استخدام الحقول المخصصة في القوالب أو تخزينها على المشتركين، تحتاج لإنشائها في WhatChimp.

الخطوة أ. سجل الدخول إلى حساب WhatChimp الخاص بك وانتقل إلى Subscriber Manager > Manage Custom Fields، أو اذهب مباشرة إلى /whatsapp/subscriber/manager/custom-field/list.

الخطوة ب. انقر على زر Create لإضافة حقل مخصص جديد.

الخطوة ج. أدخل اسم حقل (مثل company، country، customer_email، membership_level). استخدم أحرف صغيرة مع شرطات سفلية للاتساق.

الخطوة د. حدد نوع الرد (نص، بريد إلكتروني، هاتف، رقم، إلخ) بناءً على نوع البيانات التي سيخزنها الحقل.

الخطوة ه. انقر على Save لإنشاء الحقل.

كرر هذه العملية لجميع الحقول المخصصة التي تحتاجها. تشمل الحقول الشائعة اسم الشركة والموقع ونوع الحساب والصناعة أو أي معلومات خاصة بالمشترك يستخدمها عملك.

الخطوة 2: إعداد المشترك وقيم الحقول المخصصة عبر API

قبل إرسال قالب يستخدم حقولاً مخصصة، يجب أن يكون المشترك موجوداً في حساب WhatChimp الخاص بك ولديه قيم حقول مخصصة معينة لملفه الشخصي.

إنشاء المشترك (إذا لم يكن موجوداً بعد)

إذا لم يكن المشترك موجوداً بالفعل في حساب WhatChimp الخاص بك، تحتاج لإنشائه أولاً باستخدام API إنشاء المشترك.

Endpoint: POST /api/v1/whatsapp/subscriber/create

المعاملات:

مثال على الطلب:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/create \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phoneNumberID=1234567890" \
  -d "name=John Doe" \
  -d "phoneNumber=15551234567"

استجابة النجاح:

{"status":"1","mesasge":"WhatsApp subscriber has been created."}

إذا كان المشترك موجوداً بالفعل، يعيد API "Something went wrong or subscriber already exist." — هذا متوقع، ويمكنك تخطي هذه الخطوة والانتقال مباشرة لتعيين الحقول المخصصة أدناه.

التحقق من الحقول المخصصة المتاحة

استرجع قائمة الحقول المخصصة التي أنشأتها للتحقق من أسماء الحقول الدقيقة.

Endpoint: POST /api/v1/whatsapp/subscriber/custom-fields/list

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/custom-fields/list \
  -d "apiToken=YOUR_API_TOKEN"

الاستجابة:

{
  "status": "1",
  "message": "Custom fields retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "company",
      "reply_type": "text"
    },
    {
      "id": 2,
      "name": "country",
      "reply_type": "text"
    },
    {
      "id": 3,
      "name": "customer_email",
      "reply_type": "email"
    }
  ]
}

لاحظ أسماء الحقول التي ستستخدمها في الخطوة التالية.

تعيين حقول مخصصة للمشترك

الآن عيّن قيم الحقول المخصصة على ملف تعريف المشترك. يعمل هذا سواء أنشأت المشترك للتو أو كان موجوداً بالفعل.

Endpoint: POST /api/v1/whatsapp/subscriber/chat/assign-custom-fields

المعاملات:

مثال على الطلب:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/chat/assign-custom-fields \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d 'custom_fields={"company":"Acme Corp","country":"United States","customer_email":"john@acme.com"}'

استجابة النجاح:

{
  "status": "1",
  "message": "Subscriber changes have been saved successfully."
}

قيم الحقول المخصصة الآن مخزنة على ملف تعريف هذا المشترك. يمكنك تحديثها في أي وقت عن طريق استدعاء هذا endpoint مرة أخرى بقيم جديدة.

يمكنك أيضاً تعيين حقول مخصصة عن طريق:

• تحرير المشتركين يدوياً في واجهة Subscriber Manager
• استيراد جهات الاتصال عبر CSV مع أعمدة الحقول المخصصة
• استخدام تدفقات chatbot التي تلتقط إدخال المستخدم وتحفظه في الحقول المخصصة
• العمليات الجماعية عبر API المشتركين

الخطوة 3: إنشاء قالب بحقول مخصصة

الآن أنشئ قالب رسالة WhatsApp يستخدم حقولك المخصصة.

الخطوة أ. انتقل إلى Bot Manager > Message Template في لوحة تحكم WhatChimp الخاصة بك.

الخطوة ب. انقر على Create لبدء قالب جديد.

الخطوة ج. اكتب نص رسالتك. عندما تريد إدراج حقل مخصص، انقر على زر القائمة المنسدلة Custom Fields (مع أيقونة الترس) أعلى منطقة نص نص الرسالة. لا تنقر على "Variables" — هذا يدرج متغيرات القالب، التي تعمل بشكل مختلف.

تعرض القائمة المنسدلة Custom Fields جميع الحقول المخصصة التي أنشأتها في الخطوة 1 (مثل Country وEmail وFullName، إلخ). انقر على أي اسم حقل لإدراجه في نص رسالة القالب الخاصة بك.

مثال على نص القالب:

مرحباً {{first_name}}، لدينا عرض خاص لـ {{company}}!

كعميل قيّم في {{country}}، أنت مؤهل للحصول على فوائد حصرية. انقر أدناه لمعرفة المزيد.

الخطوة د. أضف أي أزرار أو رؤوس أو تذييلات يحتاجها قالبك.

الخطوة ه. انقر على Save وأرسل للموافقة من Meta.

انتظر حتى توافق Meta على قالبك. يستغرق هذا عادةً بضع ساعات إلى يوم. بمجرد الموافقة، يمكنك إرساله عبر API.

الخطوة 4: إرسال القالب عبر API

الآن أنت جاهز لإرسال القالب. لاحظ أن طلب الإرسال لا يتضمن أي معاملات متغيرات. يتم سحب قيم الحقول المخصصة تلقائياً من بيانات المشترك المخزنة.

Endpoint: GET/POST /api/v1/whatsapp/send

المعاملات:

مثال على الطلب (GET):

https://app.whatchimp.com/api/v1/whatsapp/send?apiToken=YOUR_API_TOKEN&phone_number_id=1234567890&phone_number=15551234567&template_name=special_offer&language_code=en_US

مثال على الطلب (POST):

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/send \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d "template_name=special_offer" \
  -d "language_code=en_US"

استجابة النجاح:

{
  "status": "1",
  "message": "Message sent successfully",
  "data": {
    "message_id": "wamid.HBgNMTU1NTEyMzQ1NjcVAgARGBI5QTNDQTA3RjU4Q0M1MTBGMkEA"
  }
}

يسحب النظام تلقائياً قيم الحقول المخصصة (company، country، customer_email) من ملف تعريف المشترك ويدرجها في القالب. يرى المستلم رسالة مخصصة بالكامل دون الحاجة لتمرير تلك القيم في كل طلب إرسال.

مثال على سير العمل الكامل

إليك العملية الكاملة من البداية إلى النهاية لإرسال رسائل القوالب مع متغيرات مخصصة:

الإعداد لمرة واحدة:

الخطوة أ. أنشئ حقولاً مخصصة في واجهة WhatChimp (مثل company، country، membership_level).

الخطوة ب. أنشئ واحصل على موافقة لقالب يستخدم تلك الحقول المخصصة.

لكل مشترك:

الخطوة ج. أنشئ المشترك إذا لم يكن موجوداً بالفعل في WhatChimp:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/create \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phoneNumberID=1234567890" \
  -d "name=John Doe" \
  -d "phoneNumber=15551234567"

تخطى هذه الخطوة إذا كان المشترك موجوداً بالفعل في حسابك.

الخطوة د. عيّن قيم الحقول المخصصة على المشترك:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/chat/assign-custom-fields \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d 'custom_fields={"company":"Acme Corp","country":"United States","membership_level":"Gold"}'

الخطوة ه. أرسل القالب (لا حاجة لمعاملات متغيرات):

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/send \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d "template_name=membership_update" \
  -d "language_code=en_US"

يتلقى المشترك رسالة مخصصة مثل: "مرحباً John، عضويتك Gold في Acme Corp نشطة. كعميل في United States، لديك إمكانية الوصول إلى فوائد حصرية."

استكشاف الأخطاء وإصلاحها

مقالات ذات صلة

• Template Variables vs Custom Variables
• Send Template Messages with Variables via WhatChimp API — للبيانات الديناميكية لكل رسالة مثل OTPs وأرقام الطلبات
• WhatChimp Subscriber Management API
• How to Manage Custom Fields and Labels
• Send Template Messages via WhatChimp API
• Getting Started with WhatChimp Developer API