WhatsApp: الإرسال

إرسال رسالة أو أكثر عبر WhatsApp، مع إمكانية إرفاق وسائط، باستخدام واجهة برمجة تطبيقات Mersal.

4 دقيقة قراءة

أرسل رسالة WhatsApp واحدة أو أكثر في طلب واحد. يطابق شكل الطلب SMS: الإرسال، مع حقول اختيارية إضافية لإرفاق وسائط بالرسالة.

المصادقة

يتطلب مفتاح API الشخصي الخاص بك عبر ترويسة Api-key (أو بديل api_key في معامل الرابط/نص الطلب). راجع المصادقة.

معاملات الطلب

الاسم	النوع	مطلوب	الوصف
`contact`	array	نعم	مصفوفة المستلمين. يجب أن تحتوي على عنصر واحد على الأقل.
`contact.*.number`	string	نعم	رقم WhatsApp الخاص بالمستلم.
`contact.*.message`	string	نعم	نص الرسالة.
`contact.*.gateway_identifier`	string	لا	معرّف UID لبوابة WhatsApp محددة للإرسال عبرها (مثل اتصال WhatsApp Cloud API معيّن أو جهاز مرتبط عبر QR). احذف هذا الحقل لاستخدام بوابة WhatsApp الافتراضية/النشطة في حسابك.
`contact.*.schedule_at`	string	لا	جدولة التسليم لوقت لاحق، بصيغة `Y-m-d H:i:s`. احذف هذا الحقل للإرسال الفوري.
`contact.*.media`	string	لا	نوع الوسائط المرفقة: أحد الأنواع `image` أو `audio` أو `video` أو `document`.
`contact.*.url`	string	لا	رابط عام لملف الوسائط المراد إرساله. مطلوب عند تحديد `media`.
`contact.*.filename`	string	لا	اسم الملف المعروض لوسائط `document`.

لإرسال الرسائل التفاعلية من نوع القائمة (واجهة اختيار القائمة في WhatsApp)، استخدم النقطة الطرفية المنفصلة POST /api/whatsapp/send-list.

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

curl -X POST https://mersal.it/api/whatsapp/send \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": [
      {
        "number": "+201234567890",
        "message": "Here is your invoice.",
        "media": "document",
        "url": "https://example.com/files/invoice-1042.pdf",
        "filename": "invoice-1042.pdf"
      }
    ]
  }'

<?php
 
$response = Http::withHeaders([
    'Api-key' => 'YOUR_API_KEY',
    'Content-Type' => 'application/json',
])->post('https://mersal.it/api/whatsapp/send', [
    'contact' => [
        [
            'number' => '+201234567890',
            'message' => 'Here is your invoice.',
            'media' => 'document',
            'url' => 'https://example.com/files/invoice-1042.pdf',
            'filename' => 'invoice-1042.pdf',
        ],
    ],
]);
 
$data = $response->json();

<?php
 
$payload = [
    'contact' => [
        [
            'number' => '+201234567890',
            'message' => 'Here is your invoice.',
            'media' => 'document',
            'url' => 'https://example.com/files/invoice-1042.pdf',
            'filename' => 'invoice-1042.pdf',
        ],
    ],
];
 
$ch = curl_init('https://mersal.it/api/whatsapp/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Api-key: YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
 
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch("https://mersal.it/api/whatsapp/send", {
  method: "POST",
  headers: {
    "Api-key": process.env.MERSAL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact: [
      {
        number: "+201234567890",
        message: "Here is your invoice.",
        media: "document",
        url: "https://example.com/files/invoice-1042.pdf",
        filename: "invoice-1042.pdf",
      },
    ],
  }),
});
 
const data = await response.json();

import os
import requests
 
response = requests.post(
    "https://mersal.it/api/whatsapp/send",
    headers={"Api-key": os.environ["MERSAL_API_KEY"]},
    json={
        "contact": [
            {
                "number": "+201234567890",
                "message": "Here is your invoice.",
                "media": "document",
                "url": "https://example.com/files/invoice-1042.pdf",
                "filename": "invoice-1042.pdf",
            }
        ]
    },
)
 
data = response.json()

أنواع الوسائط المدعومة

النوع	القيمة	ملاحظات
صورة	`image`	JPG / PNG عبر رابط عام.
صوت	`audio`	ملفات صوتية قياسية (MP3, OGG).
فيديو	`video`	MP4 عبر رابط عام.
ملف	`document`	أي ملف (PDF, XLSX, …) — استخدم `filename` لتحديد الاسم الظاهر للمستلم.

مثال على الاستجابة

{
  "success": true,
  "message": "WhatsApp message queued successfully",
  "data": {
    "contact": [
      {
        "number": "+201234567890",
        "status": "queued"
      }
    ]
  }
}

عند فشل التحقق من صحة البيانات، تُرجع Mersal الحالة 422:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.message": ["The contact.0.message field is required."]
  }
}

من أي رقم بيتم الإرسال؟

الرسائل تُرسل من بوابة WhatsApp النشطة في حسابك — سواء كانت اتصال WhatsApp Cloud API رسمي أو جهاز مرتبط عبر QR برقمك الشخصي. راجع ربط واتساب عبر QR لتفاصيل الربط.

أكثر حالات الفشل شيوعًا هي مفتاح API مفقود أو غير صالح، أو اشتراك منتهي الصلاحية، أو خطأ تحقق 422 في مصفوفة contact (بما في ذلك تركيبات غير صالحة من media/url). راجع الأخطاء ورموز الحالة للمرجع الكامل.

SMS: الإرسال

Email: الإرسال

هل ساعدتك هذه الصفحة؟