Skip to content
JawibDocumentationWHATSAPP API · v2
Documentation/Messages and media

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

TypeRequest fields
texttext is required.
image, video, documentProvide an HTTPS media_url, or upload media using multipart/form-data. Optional fields include caption and filename.
audioProvide 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.
otpotp_code: 4–8 digits. Optional otp_ttl_seconds: 60–900. Private messages only. Requires messages:write:otp or messages:write.
reactionreaction_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

POST/api/v2/messages
Key owner: Customer or direct companyRequired scope: messages:write
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"
}'
Request body fields
FieldTypeDescription
connection_idrequiredstring—
torequiredstringInternational phone, private JID, or owned group JID (requires groups:write).
typerequiredstringtext / image / audio / video / document / reaction / otp
textstring—
captionstring—
media_urlstring—
mediastring—
filenamestring—
otp_codestring—
voice_notebooleanOnly for audio. true sends PTT and requires a valid mono OGG/Opus stream. No transcoding. Incoming content resources/webhooks also expose voice_note.
sender_typestringhuman requires conversations:write; automation requires external reply mode for inbox-enabled connections.
otp_ttl_secondsinteger—
Response example 202
{
    "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

GET/api/v2/messages/{message}
Key owner: Customer or direct companyRequired scope: messages:read

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'
Response example 200
{
    "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.

Jawib API documentationAPI v2 · HTTPS / JSON
Search guides and API endpoints · Press Esc to close