إرسال رسالة واتساب عبر API: أمثلة cURL وNode وPython وPHP

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_update \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=INV-400

// Node.js 18+ (fetch وFormData مدمجان)
const form = new FormData();
form.append("batchId", "0");
form.append("campaignName", "order-updates");
form.append("destinationNo", "971500000000");
form.append("messageType", "TEMPLATE");
form.append("templateName", "order_update");
form.append("templateLanguage", "en_US");
form.append("bodyTemplateVariables", "INV-400");

const res = await fetch("https://api.broadnet.me/whatsapp/message/sendbulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` }, // يضبط fetch حد multipart
  body: form,
});
console.log(await res.json());

import os
import requests

fields = {
    "batchId": "0",
    "campaignName": "order-updates",
    "destinationNo": "971500000000",
    "messageType": "TEMPLATE",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "bodyTemplateVariables": "INV-400",
}

# أرسل كل حقل بوصفه جزء multipart (files=) لا مرمَّزًا بالعناوين (data=).
r = requests.post(
    "https://api.broadnet.me/whatsapp/message/sendbulk",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.json())

<?php
$ch = curl_init("https://api.broadnet.me/whatsapp/message/sendbulk");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BROADNET_TOKEN")],
    // المصفوفة (لا النص) تجعل cURL يرسل multipart/form-data.
    CURLOPT_POSTFIELDS => [
        "batchId" => "0",
        "campaignName" => "order-updates",
        "destinationNo" => "971500000000",
        "messageType" => "TEMPLATE",
        "templateName" => "order_update",
        "templateLanguage" => "en_US",
        "bodyTemplateVariables" => "INV-400",
    ],
]);
echo curl_exec($ch);
curl_close($ch);

{
  "totalFiles": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalDuplicates": 0,
  "batchId": "2609091405000000001",
  "fileResults": [
    {
      "fileName": "direct",
      "totalRecords": 1,
      "successCount": 1,
      "failedRecipients": [],
      "duplicateRecipients": []
    }
  ],
  "message": "Messages queued for delivery"
}

ما حقول الطلب الأهم؟

تعتمد الحقول المطلوبة على messageType. هذه هي الشائعة.

تستخدم الجدولة scheduled وscheduleTime وgmt، ويخنق delay التسليم. القائمة الكاملة في مرجع واتساب API.

كيف أرسل قالبًا بزر أو رمز OTP؟

أضف قيمة الزر في buttonsTemplateVariable. وفي قالب مصادقة بزر نسخ الرمز، مرّر الرمز في حقلي النص والزر معًا.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=login_code \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=482913 \
  -F buttonsTemplateVariable=482913

هنا login_code عنصر نائب لقالب المصادقة المعتمد الخاص بك. ولأزرار متعددة يقبل buttonsTemplateVariable مصفوفة JSON. ولّد الرمز على خادمك، وخزّنه مجزّأً مع انتهاء صلاحية، ولا تسجله أبدًا. ويغطي دليل OTP التسليم بالنقرة الواحدة وبلا نقرات ونسخ الرمز.

كيف أرد داخل نافذة خدمة العملاء؟

استخدم نوع رسالة جلسة. يحتاج الرد النصي العادي إلى messageType=TEXT وcontent.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEXT \
  -F campaignName=support \
  -F "content=Your order has shipped. Reply here if you need anything."

لأزرار الرد، أرسل messageType=INTERACTIVE وinteractivePayload يتبع صيغة الرسالة التفاعلية لدى Meta.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=INTERACTIVE \
  -F campaignName=support \
  -F 'interactivePayload={"type":"button","body":{"text":"Confirm your delivery slot?"},"action":{"buttons":[{"type":"reply","reply":{"id":"slot_ok","title":"Confirm"}},{"type":"reply","reply":{"id":"slot_change","title":"Change"}}]}}'

لتعليم رسالة واردة مقروءة، وإظهار مؤشر الكتابة اختياريًا، استدعِ POST /whatsapp/message/read بصيغة JSON:

curl -X POST https://api.broadnet.me/whatsapp/message/read \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": "wamid.HBgMOTcxNTAwMDAwMDAwFQIAEhgg", "typing": true }'

راجع دليلنا عن الرسائل التفاعلية لإرشادات التصميم.

كيف أتتبع التسليم؟

تُدفع الحالات إلى webhook المضبوط على حسابك ويمكن قراءتها أيضًا لكل دفعة. ينتقل كل مستلم عبر SUBMITTED وSENT وDELIVERED وREAD، أو ينتهي بـ FAILED أو REJECTED مع السبب.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&status=FAILED&page=0&size=50" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id مطلوب؛ وstatus وdestination وsearch وpage وsize اختيارية، وpage يبدأ من الصفر. استخدم الاستعلام الدوري شبكة أمان للأحداث الفائتة، وابنِ مستقبِلك كما في دليل webhooks. ويمكن أيضًا إيقاف الدفعات مؤقتًا واستئنافها وإلغاؤها بنقاط نهاية الدفعات في المرجع.

ما الأخطاء التي ينبغي معالجتها؟

اقرأ حالة HTTP أولًا، ثم جسم الخطأ. يطلق الـ API الأخطاء في جسم JSON من خمسة حقول، وقد تأتي إخفاقات واتساب الخاصة من Meta.

يشرح دليل رموز الأخطاء لدينا رموز Meta الشائعة. ولأنه لا يوجد مفتاح idempotency، اتبع خطوات الحماية من التكرار في الأخطاء والحدود: اكتب سجلًا معلقًا أولًا، وخزّن batchId العائد، وبعد انتهاء المهلة افحص الحالة قبل الإرسال مجددًا.

مثال تطبيقي: خدمة إشعارات الطلبات

ترسل «سوق رفيق» (اسم افتراضي)، وهي متجر تجزئة في الإمارات، قالب order_update عند شحن الطلب.

1. تكتب خدمة الطلبات صفًا بالمفتاح order-8842-shipped وحالته pending.
2. تستدعي sendbulk مع القالب ورقم الطلب في bodyTemplateVariables.
3. عند 200 تخزّن batchId وتعلّم الصف accepted.
4. يحدّث معالج webhook الصف إلى DELIVERED أو READ، أو FAILED مع السبب.
5. إذا ردّ العميل، تستخدم أداة الدعم رسالة جلسة TEXT داخل النافذة.
6. تقرأ مهمة ليلية bulk-insights لدفعات الأمس وتطابق أي حالات مفقودة.

ما الأخطاء الشائعة؟

• إرسال JSON. نقطة نهاية إرسال واتساب بصيغة multipart؛ ولن ينجح Content-Type: application/json.
• استخدام data= في Python بدل files=، فيُرمَّز النموذج بالعناوين.
• نص حر خارج النافذة، وهذا يفشل. استخدم قالبًا.
• رمز لغة خاطئ، مثل en بدل en_US الخاص بالقالب.
• اعتبار 200 تسليمًا. إنها تعني الوضع في الطابور.
• إعادة محاولة عمياء بعد انتهاء المهلة، فقد تراسل العميل مرتين.
• الرمز في شيفرة العميل. استدعِ الـ API من خلفيتك فقط.
• الحدود: تختلف تفاصيل الحمولة بحسب القالب. أكّد تخطيط المتغيرات لأول حملة مخصصة مع فريقنا.

كيف تساعدك OmniChannels.ai؟

BroadNet مزوّد حلول أعمال رسمي لدى Meta، ويستخدم الإعداد في واتساب للأعمال API مسار Meta Embedded Signup؛ يجهّز فريقنا التسجيل معك، وتبقى الاعتمادات لدى Meta. واجهة REST موثّقة بمواصفة OpenAPI 3.1 وSDK بلغة TypeScript هو @broadnet/cpaas-sdk، وتُوحَّد حالات التسليم عبر القنوات. ابدأ من وثائق واتساب API أو البدء السريع.