POST https://app.alaaqat.com/api/broadcasts/{id}/send
Where id is the ID of the WhatsApp template you want to send. Sends the template to one contact, from the WhatsApp number the template belongs to. Your API key needs the broadcast-send ability.
Only approved templates can be sent. Authentication templates are refused here: send them with Send WhatsApp OTP.
Every template you send counts toward your plan's monthly message allowance.
{
"Accept": "application/json"
}When you send a header file, send the body as multipart/form-data. Without a file, a JSON body with Content-Type: application/json works too.
{
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
}
}
]
}
]
}| Field | Required | Validation | Description |
|---|---|---|---|
| contact_id | Required | The ID of one of your contacts | The contact who receives the template. |
| header.file | Required when the template's header is an image, a video or a document | Depends on the header, see Header media | The media shown in the template's header. |
| components | Required when the template has a copy code button | An array | The values you fill in at send time, see Components. |
| components.*.type | Required | header, body or button |
The part of the template the values belong to. |
| components.*.sub_type | Optional | url or copy_code |
For a button, the kind of button. |
| components.*.index | Optional | A whole number | For a button, its position among the template's buttons, starting at 0. |
| components.*.parameters | Optional | An array | The values for that part of the template. |
| components..parameters..type | Required | text, image, video, document, location or payload |
The kind of value. |
| components..parameters..payload | Required when the type is payload |
Text with no spaces | The offer code of a copy code button. |
| components..parameters..location.name | Required when the type is location |
Text | The name of the place in a location header. |
| components..parameters..location.address | Required when the type is location |
Text | The address of the place in a location header. |
| components..parameters..location.latitude | Required when the type is location |
A number | The latitude of the place. |
| components..parameters..location.longitude | Required when the type is location |
A number | The longitude of the place. |
The file you can send depends on the format of the template's header:
| Header format | File types | Maximum size |
|---|---|---|
| Image | PNG, JPEG | 5 MB |
| Video | MP4, 3GPP | 16 MB |
| Document | PDF, plain text, Word, Excel, PowerPoint | 100 MB |
Every file must be at least 10 KB. Both the file's content and its extension must match one of the allowed types.
You only send components for the parts of a template that change from one send to the next:
button component with the copy_code sub type, the button's index, and one payload parameter that holds the offer code.header component with one location parameter that holds the place.You don't send components for the variables in the header and body text. Alaaqat fills them in from the contact's properties, using the property each variable was mapped to when the template was created. The header media comes from header.file.
{warning} If the contact has no value for a property that one of the template's variables uses, nothing is sent and the response is
400. Fill in the contact's property first, then send again.
A template with a copy code button as its second button:
{
"contact_id": "6650f1a2b3c4d5e6f7a8b901",
"components": [
{
"type": "button",
"sub_type": "copy_code",
"index": 1,
"parameters": [
{
"type": "payload",
"payload": "SPRING25"
}
]
}
]
}A template with a location header:
{
"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
}
}
]
}
]
}A template with an image header, sent as 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"Returns the sent Message under data, with the template it was sent from under 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"
}
}
}
}| Status | Meaning |
|---|---|
| 400 | The contact has no value for a property that one of the template's variables uses. The message names the property. |
| 402 | Your plan's monthly message allowance is used up. See the plans on the pricing page. |
| 403 | The template is not approved, it is an authentication template, the contact has unsubscribed, or your API key lacks the broadcast-send ability. |
| 404 | No template exists with this ID. |
| 422 | Validation failed: for example, the contact is not one of yours, the header file has the wrong type or size, or the offer code is missing. |
The 400 response looks like this:
{
"message": "The attribute firstname must exist on this object."
}