إرسال قالب واتساب

POST https://app.alaaqat.com/api/broadcasts/{id}/send

حيث id هو معرّف قالب واتساب الذي تريد إرساله. ترسل هذه النقطة القالب إلى جهة اتصال واحدة من رقم واتساب الذي ينتمي إليه القالب. يحتاج مفتاح واجهة التطبيق البرمجية إلى الإمكانية broadcast-send.

لا يُرسل إلا القالب المعتمد. ترفض هذه النقطة قوالب المصادقة، فأرسلها عبر إرسال رمز تحقق واتساب.

يُحتسب كل قالب ترسله من رصيد الرسائل الشهري في خطتك.

ترويسة الطلب

{
    "Accept": "application/json"
}

إذا أرسلت ملفاً للترويسة، فأرسل محتوى الطلب بصيغة multipart/form-data. أما دون ملف، فيصلح أيضاً محتوى بصيغة JSON مع الترويسة Content-Type: application/json.

محتوى الطلب

{
    contact_id: string,
    header?: {
        file?: File
    },
    components?: [
        {
            type: 'header' | 'body' | 'button',
            sub_type?: 'url' | 'copy_code',
            index?: number,
            parameters?: [
                {
                    type: 'text' | 'image' | 'video' | 'document' | 'location' | 'payload',
                    payload?: string,
                    location?: {
                        name: string,
                        address: string,
                        latitude: number,
                        longitude: number
                    }
                }
            ]
        }
    ]
}
الحقل مطلوب التحققات الوصف
contact_id مطلوب معرّف إحدى جهات اتصالك جهة الاتصال التي تستلم القالب.
header.file مطلوب إذا كانت ترويسة القالب صورة أو فيديو أو مستنداً يعتمد على الترويسة، راجع وسائط الترويسة الوسائط التي تظهر في ترويسة القالب.
components مطلوب إذا كان في القالب زر نسخ رمز مصفوفة القيم التي تملؤها وقت الإرسال، راجع المكونات.
components.*.type مطلوب header أو body أو button جزء القالب الذي تعود إليه القيم.
components.*.sub_type اختياري url أو copy_code نوع الزر، إذا كان المكوّن button.
components.*.index اختياري عدد صحيح ترتيب الزر بين أزرار القالب، بدءاً من 0، إذا كان المكوّن button.
components.*.parameters اختياري مصفوفة قيم ذلك الجزء من القالب.
components..parameters..type مطلوب text أو image أو video أو document أو location أو payload نوع القيمة.
components..parameters..payload مطلوب إذا كان النوع payload نص دون مسافات رمز العرض في زر نسخ الرمز.
components..parameters..location.name مطلوب إذا كان النوع location نص اسم المكان في ترويسة الموقع.
components..parameters..location.address مطلوب إذا كان النوع location نص عنوان المكان في ترويسة الموقع.
components..parameters..location.latitude مطلوب إذا كان النوع location رقم خط عرض المكان.
components..parameters..location.longitude مطلوب إذا كان النوع location رقم خط طول المكان.

وسائط الترويسة

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

صيغة الترويسة أنواع الملفات الحجم الأقصى
صورة PNG وJPEG 5 ميغابايت
فيديو MP4 و3GPP 16 ميغابايت
مستند PDF والنص العادي وWord وExcel وPowerPoint 100 ميغابايت

يجب ألا يقل حجم أي ملف عن 10 كيلوبايت، ويجب أن يطابق محتوى الملف وامتداده معاً أحد الأنواع المسموحة.

المكونات

لا ترسل المكونات إلا للأجزاء التي تتغير من إرسال إلى آخر:

  • زر نسخ الرمز: مكوّن من نوع button بالنوع الفرعي copy_code، مع index الزر، ومعطى واحد من نوع payload يحمل رمز العرض.
  • ترويسة الموقع: مكوّن من نوع header مع معطى واحد من نوع location يحمل بيانات المكان.

لا ترسل مكونات لمتغيرات نص الترويسة ونص القالب، إذ يملؤها نظام علاقات من خصائص جهة الاتصال، وفق الخاصية التي رُبط بها كل متغير عند إنشاء القالب. أما وسائط الترويسة فتأتي من header.file.

{warning} إذا لم تكن لدى جهة الاتصال قيمة لخاصية يستخدمها أحد متغيرات القالب، فلن يُرسل شيء وتكون الاستجابة 400. املأ خاصية جهة الاتصال أولاً ثم أعد الإرسال.

قالب يكون زر نسخ الرمز فيه هو الزر الثاني:

{
    "contact_id": "6650f1a2b3c4d5e6f7a8b901",
    "components": [
        {
            "type": "button",
            "sub_type": "copy_code",
            "index": 1,
            "parameters": [
                {
                    "type": "payload",
                    "payload": "SPRING25"
                }
            ]
        }
    ]
}

قالب بترويسة موقع:

{
    "contact_id": "6650f1a2b3c4d5e6f7a8b901",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "location",
                    "location": {
                        "name": "Al Noor Store",
                        "address": "Rainbow Street 12, Amman",
                        "latitude": 31.9516,
                        "longitude": 35.9239
                    }
                }
            ]
        }
    ]
}

قالب بترويسة صورة، يُرسل بصيغة multipart/form-data:

curl -X POST https://app.alaaqat.com/api/broadcasts/418/send \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -F "contact_id=6650f1a2b3c4d5e6f7a8b901" \
  -F "header[file]=@spring-offer.jpg"

الإستجابة

تُرجع الرسالة المرسلة Message ضمن data، والقالب الذي أُرسلت منه ضمن data.broadcast.

{
    "data": {
        "id": "wamid.{whatsapp-message-id}",
        "contact_channel_id": "962790000000",
        "platform_third_party_id": "123456789012",
        "sender_third_party_id": "123456789012",
        "receiver_third_party_id": "962790000000",
        "status": "sent",
        "broadcast_id": 418,
        "template_type": "whatsapp_broadcast",
        "attachments": [],
        "updated_at": "2026-10-22T08:00:05.000000Z",
        "created_at": "2026-10-22T08:00:05.000000Z",
        "_id": "6656f0a1b2c3d4e5f6a7b801",
        "is_sent_by_the_business": true,
        "broadcast": {
            "id": 418,
            "name": "spring_offer",
            "language": "en",
            "account_id": 1024,
            "template_id": 377,
            "platform_id": 9,
            "status": "APPROVED",
            "created_at": "2026-10-01T12:00:00.000000Z",
            "updated_at": "2026-10-02T09:30:00.000000Z",
            "reason": null,
            "provider": "whatsapp_number",
            "template": {
                "id": 377,
                "header": {
                    "format": "TEXT",
                    "text": "Spring offer",
                    "type": "HEADER"
                },
                "body": {
                    "text": "Enjoy 25% off everything in store this week. Use the code below at checkout.",
                    "type": "BODY"
                },
                "footer": {
                    "text": "Al Noor Store",
                    "type": "FOOTER"
                },
                "buttons": [
                    {
                        "type": "QUICK_REPLY",
                        "text": "Stop promotions",
                        "example": null
                    },
                    {
                        "type": "COPY_CODE",
                        "copy_code": "SPRING25",
                        "example": "SPRING25"
                    }
                ],
                "created_at": "2026-10-01T12:00:00.000000Z",
                "updated_at": "2026-10-02T09:30:00.000000Z",
                "external_id": "{whatsapp-template-id}",
                "name": "spring_offer",
                "category": "MARKETING"
            },
            "platform": {
                "id": 9,
                "verified_name": "Al Noor Store",
                "code_verification_status": "VERIFIED",
                "display_phone_number": "+962 79 000 0000",
                "quality_rating": "GREEN",
                "phone_id": "{phone-number-id}",
                "waba_id": 7,
                "created_at": "2026-02-14T10:00:00.000000Z",
                "updated_at": "2026-10-01T08:00:00.000000Z",
                "name": "Al Noor Store"
            }
        }
    }
}

الأخطاء

الرمز المعنى
400 ليس لدى جهة الاتصال قيمة لخاصية يستخدمها أحد متغيرات القالب، وتذكر الرسالة اسم الخاصية.
402 استُنفد رصيد الرسائل الشهري في خطتك. اطّلع على الخطط في صفحة الأسعار.
403 القالب غير معتمد، أو هو قالب مصادقة، أو ألغت جهة الاتصال اشتراكها، أو لا يملك مفتاحك الإمكانية broadcast-send.
404 لا يوجد قالب بهذا المعرّف.
422 فشل التحقق، كأن تكون جهة الاتصال ليست من جهات اتصالك، أو يكون نوع ملف الترويسة أو حجمه غير مسموح، أو يكون رمز العرض مفقوداً.

تبدو استجابة 400 هكذا:

{
    "message": "The attribute firstname must exist on this object."
}