WhatsApp: Send
Send one or more WhatsApp messages, with optional media, via the Mersal API.
3 min read
Send one or more WhatsApp messages in a single request. The request shape mirrors SMS: Send, with additional optional fields for attaching media to a message.
Endpoint
POSThttps://mersal.it/api/whatsapp/send
Authentication
Requires your personal API key via the Api-key header (or the api_key query/body fallback). See Authentication.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
contact | array | Yes | Array of recipients. Must contain at least 1 item. |
contact.*.number | string | Yes | The recipient's WhatsApp number. |
contact.*.message | string | Yes | The message body. |
contact.*.gateway_identifier | string | No | UID of a specific WhatsApp gateway to send through (e.g. a specific WhatsApp Cloud API connection or QR-linked device). Omit to use your account's default/active WhatsApp gateway. |
contact.*.schedule_at | string | No | Schedule delivery for a future time, format Y-m-d H:i:s. Omit to send immediately. |
contact.*.media | string | No | Media type to attach: one of image, audio, video, document. |
contact.*.url | string | No | Public URL of the media file to send. Required when media is set. |
contact.*.filename | string | No | Display filename for document media. |
For interactive list messages (WhatsApp list picker UI), use the separate POST /api/whatsapp/send-list endpoint.
Example request
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()Example response
{
"success": true,
"message": "WhatsApp message queued successfully",
"data": {
"contact": [
{
"number": "+201234567890",
"status": "queued"
}
]
}
}On validation failure, Mersal returns 422:
{
"success": false,
"message": "Validation failed",
"errors": {
"contact.0.message": ["The contact.0.message field is required."]
}
}Errors
Common failure modes are a missing/invalid API key, an expired subscription, or a 422 validation error on the contact array (including invalid media/url combinations). See Errors and Status Codes for the full reference.
Was this page helpful?