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."
}