Messages and media
Send a message using an active connection and the owning customer's key. A successful request accepts the operation; use the returned message ID or webhooks to track delivery. For private messages, to is an international phone number such as +249900000000. Use the group-message endpoint for groups.
Supported message types
| Type | Request fields |
|---|---|
text | text is required. |
image, video, document | Provide an HTTPS media_url, or upload media using multipart/form-data. Optional fields include caption and filename. |
audio | Provide a file or URL. Set voice_note: true for a native PTT voice note using mono OGG/Opus. Audio does not accept text or captions. Jawib does not transcode media. |
otp | otp_code: 4–8 digits. Optional otp_ttl_seconds: 60–900. Private messages only. Requires messages:write:otp or messages:write. |
reaction | reaction_to: original WhatsApp message ID. emoji: one emoji, or an empty string/null to remove your reaction. |
Media constraints
Images may be up to 5 MiB. Other media may be up to 10 MiB. URL-based media must use a public HTTPS address; private-network destinations are rejected. The separate playground accepts media URLs. Use multipart requests from your server to upload local files.
Image example
{
"connection_id": "CONNECTION_UUID",
"to": "+249900000000",
"type": "image",
"media_url": "https://example.com/image.png",
"caption": "Example image"
}
Voice-note example
{
"connection_id": "CONNECTION_UUID",
"to": "+249900000000",
"type": "audio",
"media_url": "https://example.com/recording.ogg",
"voice_note": true
}
Message lifecycle
The message resource exposes status and timestamps such as sent_at, delivered_at, read_at, and failed_at. Delivery and read events depend on what WhatsApp reports. For a group, a participant receipt does not establish delivery to every member.
Send a unique Idempotency-Key for each logical sending operation. Reuse it with the same method, path, and body when retrying after a network interruption.
Send a message
curl --request POST "https://playjawib.com/api/v2/messages" \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json' \
--header 'Idempotency-Key: unique-operation-123' \
--header 'Content-Type: application/json' \
--data '{
"connection_id": "CONNECTION_UUID",
"to": "+249900000000",
"type": "text",
"text": "Hello from Jawib",
"client_reference": "message-123"
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_API_KEY'))
->withHeader('Idempotency-Key', 'unique-operation-123')
->send('POST', 'https://playjawib.com/api/v2/messages', [
'json' => json_decode(<<<'JSON'
{
"connection_id": "CONNECTION_UUID",
"to": "+249900000000",
"type": "text",
"text": "Hello from Jawib",
"client_reference": "message-123"
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.JAWIB_API_KEY}`,
Accept: 'application/json',
'Idempotency-Key': 'unique-operation-123',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"connection_id": "CONNECTION_UUID",
"to": "+249900000000",
"type": "text",
"text": "Hello from Jawib",
"client_reference": "message-123"
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
connection_idrequired | string | — |
torequired | string | International phone, private JID, or owned group JID (requires groups:write). |
typerequired | string | text / image / audio / video / document / reaction / otp |
text | string | — |
caption | string | — |
media_url | string | — |
media | string | — |
filename | string | — |
otp_code | string | — |
voice_note | boolean | Only for audio. true sends PTT and requires a valid mono OGG/Opus stream. No transcoding. Incoming content resources/webhooks also expose voice_note. |
sender_type | string | human requires conversations:write; automation requires external reply mode for inbox-enabled connections. |
otp_ttl_seconds | integer | — |
{
"data": {
"id": "019c0000-0000-7000-8000-000000000003",
"destination_type": "private",
"group_id": null,
"receipt_scope": "recipient",
"type": "text",
"voice_note": false,
"status": "sent",
"failure_code": null,
"sent_at": "2026-10-29T09:00:00+00:00",
"delivered_at": null,
"read_at": null,
"failed_at": null,
"expires_at": "2026-11-28T09:00:00+00:00"
}
}Illustrative values. Use the actual identifiers and credentials returned by your request.
Retrieve a message
Replace {message} with the actual IDs returned by the API.
curl --request GET "https://playjawib.com/api/v2/messages/{message}" \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_API_KEY'))
->send('GET', 'https://playjawib.com/api/v2/messages/{message}');
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/messages/{message}', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.JAWIB_API_KEY}`,
Accept: 'application/json'
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');{
"data": {
"id": "019c0000-0000-7000-8000-000000000003",
"destination_type": "private",
"group_id": null,
"receipt_scope": "recipient",
"type": "text",
"voice_note": false,
"status": "sent",
"failure_code": null,
"sent_at": "2026-10-29T09:00:00+00:00",
"delivered_at": null,
"read_at": null,
"failed_at": null,
"expires_at": "2026-11-28T09:00:00+00:00"
}
}Illustrative values. Use the actual identifiers and credentials returned by your request.