Send WhatsApp messages
Send a REST request and track the message from acceptance to delivery.
Reviewed
Send one message with POST https://api.waaru.app/v1/messages and the messages:send scope. The key selects the sending number. A successful request returns HTTP 202 and a Waaru message ID while delivery continues asynchronously.
Using Node.js? The Waaru SDK supports message sends and delivery-status reads. Its guide includes the published-version boundary and idempotency options. This page describes the underlying REST requests.
Prepare a safe test
Complete the API setup first. Use a recipient you have permission to message. For a non-template reply, have that person send an inbound message to the same connected business number and confirm the 24-hour customer-service window is open.
If a person owns the conversation in Inbox, API sends stop. An authorized teammate must select Release to API before your server continues. Creating a new key does not change conversation ownership.
Send a text reply
Set WAARU_API_KEY through your secret environment. Save the following as message.json, replacing the example recipient with your permitted test number:
{
"messaging_product": "whatsapp",
"to": "+919876543210",
"type": "text",
"text": {
"body": "Thanks. Your enquiry reached the team.",
"preview_url": false
}
}curl --fail-with-body 'https://api.waaru.app/v1/messages' \
--header "Authorization: Bearer $WAARU_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-binary @message.jsonAn accepted response has this shape. Identifiers shown in this guide are illustrative:
{
"messaging_product": "whatsapp",
"messageId": "message_example",
"status": "queued"
}Save messageId before doing further work. The response also includes X-Waaru-Request-Id for request troubleshooting. It is not a message ID or an idempotency key.
Send an approved template
Use the same endpoint and headers with this payload. Replace the template name, language, and variables with the approved template in your account:
{
"messaging_product": "whatsapp",
"to": "+919876543210",
"type": "template",
"template": {
"name": "order_update",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [{ "type": "text", "text": "ORDER-123" }]
}
]
}
}The template must exist for the sending number's WhatsApp Business Account with the exact name and language. Create or sync it in Templates first. Components must match its approved content and variable structure. There is no public template-creation endpoint for API keys.
An approved template is required outside the service window. Approval alone does not authorize a send: consent, restrictions, connected sender, template and phone quality, and current provider state still apply. Yellow quality blocks new business-initiated template admission. It does not by itself block an eligible non-template customer-service reply.
Require an authentication template
For an authentication-only send, add X-Waaru-Require-Authentication: true.
The API rejects a template outside the AUTHENTICATION category with
409 authentication_template_required before persisting the send. Keep this
header unchanged when retrying with the same Idempotency-Key: the stricter
mode is part of the request identity. Authentication codes are omitted from
message reads and callbacks; store the code securely in your sending application
if it is needed for verification.
Track the result
With messages:read, request GET /v1/messages/:messageId using the ID returned above. Outbound statuses are queued, sent, delivered, read, and failed. A failure can include failureCode. A queued response is not proof that Meta accepted or delivered the message, and delivery does not guarantee a read event.
Use message reads or signed status webhooks to reconcile your application's state.
Avoid duplicate sends
The API accepts an optional Idempotency-Key header: 1 to 128 letters, digits, periods, underscores, colons or hyphens. Persist one random value per logical send before making the request. Retry an uncertain response with the same key, recipient and content. Waaru repeats the original 202 acceptance without admitting another send; different content or recipient returns 409. The record survives API-key rotation. No finite expiry or key-reuse window is promised. If the original message was removed, retry returns 409 and does not resend. Without this header, reconcile the message, conversation and callbacks before retrying.
For media, buttons, lists, location, and contact cards, use the message format reference. See errors and retry behavior when admission fails.
Endpoint details
Every request uses Authorization: Bearer $WAARU_API_KEY and a connected number in Developer API mode. The scope below is required. IDs and payloads are illustrative; replace them with your own permitted resources. See authentication and common errors, size limits and retries.
POST /v1/messages
Required scope: messages:send
Requires messages:send.
| Parameter | Location | Required | Constraints |
|---|---|---|---|
Idempotency-Key | header | No | {"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"} Persist one unique value per logical send. Same normalized recipient and content repeats acceptance; changed request returns409. Scope is workspace and number, including after key rotation. |
X-Waaru-Require-Authentication | header | No | {"type":"string","enum":["true"]} Set to true to require an AUTHENTICATION template before persistence. This stricter mode is part of idempotency identity; use the same header when replaying a request. |
Request
curl --fail-with-body --request POST 'https://api.waaru.app/v1/messages' \
--header "Authorization: Bearer $WAARU_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonSave this illustrative JSON as request.json. The body is required.
{
"messaging_product": "whatsapp",
"to": "+919876543210",
"type": "text",
"text": {
"body": "Your request reached the team."
}
}Request body: complete JSON schema
Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.
{
"oneOf": [
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "object",
"properties": {
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"preview_url": {
"type": "boolean"
}
},
"required": [
"body"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"text"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "template"
},
"templateFlowLaunch": {
"type": "object",
"properties": {
"buttonIndex": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"contractHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"inputs": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 4096
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"maxLength": 4096
}
}
]
}
}
},
"required": [
"buttonIndex",
"contractHash"
],
"additionalProperties": false
},
"template": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"language": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
},
"required": [
"code"
],
"additionalProperties": false
},
"components": {
"maxItems": 100,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "carousel"
},
"cards": {
"minItems": 2,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"card_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"components": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "header"
},
"parameters": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "image"
},
"image": {
"anyOf": [
{
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048
}
},
"required": [
"link"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"id"
],
"additionalProperties": false
}
]
}
},
"required": [
"type",
"image"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "video"
},
"video": {
"anyOf": [
{
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048
}
},
"required": [
"link"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"id"
],
"additionalProperties": false
}
]
}
},
"required": [
"type",
"video"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "product"
},
"product": {
"type": "object",
"properties": {
"catalog_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"product_retailer_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"catalog_id",
"product_retailer_id"
],
"additionalProperties": false
}
},
"required": [
"type",
"product"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"type",
"parameters"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "body"
},
"parameters": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"parameter_name": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"type",
"text"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "currency"
},
"currency": {
"type": "object",
"properties": {
"fallback_value": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"code": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"amount_1000": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"fallback_value",
"code",
"amount_1000"
],
"additionalProperties": false
},
"parameter_name": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"type",
"currency"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "date_time"
},
"date_time": {
"type": "object",
"properties": {
"fallback_value": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"fallback_value"
],
"additionalProperties": false
},
"parameter_name": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"type",
"date_time"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"type",
"parameters"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "button"
},
"sub_type": {
"type": "string",
"const": "url"
},
"index": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 1
},
{
"type": "string",
"pattern": "^[01]$"
}
]
},
"parameters": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"type",
"text"
],
"additionalProperties": false
}
}
},
"required": [
"type",
"sub_type",
"index",
"parameters"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "button"
},
"sub_type": {
"type": "string",
"const": "quick_reply"
},
"index": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 1
},
{
"type": "string",
"pattern": "^[01]$"
}
]
},
"parameters": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "payload"
},
"payload": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"type",
"payload"
],
"additionalProperties": false
}
}
},
"required": [
"type",
"sub_type",
"index",
"parameters"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"card_index",
"components"
],
"additionalProperties": false
}
}
},
"required": [
"type",
"cards"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"header",
"body",
"button",
"limited_time_offer"
]
},
"sub_type": {
"type": "string",
"enum": [
"quick_reply",
"url",
"copy_code",
"flow"
]
},
"index": {
"type": "string",
"pattern": "^\\d{1,2}$"
},
"parameters": {
"maxItems": 100,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "location"
},
"location": {
"type": "object",
"properties": {
"latitude": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"pattern": "^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)$"
}
]
},
"longitude": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"pattern": "^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)$"
}
]
},
"name": {
"type": "string",
"maxLength": 1000
},
"address": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
}
},
"required": [
"type",
"location"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "limited_time_offer"
},
"limited_time_offer": {
"type": "object",
"properties": {
"expiration_time_ms": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 8640000000000000
}
},
"required": [
"expiration_time_ms"
],
"additionalProperties": false
}
},
"required": [
"type",
"limited_time_offer"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "coupon_code"
},
"coupon_code": {
"type": "string",
"minLength": 1,
"maxLength": 20
}
},
"required": [
"type",
"coupon_code"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "action"
},
"action": {
"type": "object",
"properties": {
"flow_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
}
},
"required": [
"flow_token"
],
"additionalProperties": false
}
},
"required": [
"type",
"action"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"parameter_name": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"type",
"text"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "currency"
},
"currency": {
"type": "object",
"properties": {
"fallback_value": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"code": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"amount_1000": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"fallback_value",
"code",
"amount_1000"
],
"additionalProperties": false
},
"parameter_name": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"type",
"currency"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "date_time"
},
"date_time": {
"type": "object",
"properties": {
"fallback_value": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"fallback_value"
],
"additionalProperties": false
},
"parameter_name": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"type",
"date_time"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "image"
},
"image": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"type",
"image"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "video"
},
"video": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"type",
"video"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "document"
},
"document": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"type",
"document"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"type",
"parameters"
],
"additionalProperties": false
}
]
}
},
"media_assets": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"card_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"asset_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"card_index",
"asset_id"
],
"additionalProperties": false
}
}
},
"required": [
"name",
"language"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"template"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "image"
},
"image": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"caption": {
"type": "string",
"maxLength": 1024
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"image"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "video"
},
"video": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"caption": {
"type": "string",
"maxLength": 1024
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"video"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "audio"
},
"audio": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"audio"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "document"
},
"document": {
"type": "object",
"properties": {
"link": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"caption": {
"type": "string",
"maxLength": 1024
},
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
},
"required": [
"link"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"document"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "interactive"
},
"interactive": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "button"
},
"header": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"type",
"text"
],
"additionalProperties": false
},
"body": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"text"
],
"additionalProperties": false
},
"footer": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"text"
],
"additionalProperties": false
},
"action": {
"type": "object",
"properties": {
"buttons": {
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "reply"
},
"reply": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 20
}
},
"required": [
"id",
"title"
],
"additionalProperties": false
}
},
"required": [
"type",
"reply"
],
"additionalProperties": false
}
}
},
"required": [
"buttons"
],
"additionalProperties": false
}
},
"required": [
"type",
"body",
"action"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "list"
},
"header": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text"
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"type",
"text"
],
"additionalProperties": false
},
"body": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"text"
],
"additionalProperties": false
},
"footer": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"text"
],
"additionalProperties": false
},
"action": {
"type": "object",
"properties": {
"button": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"sections": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 24
},
"rows": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"description": {
"type": "string",
"maxLength": 72
}
},
"required": [
"id",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"rows"
],
"additionalProperties": false
}
}
},
"required": [
"button",
"sections"
],
"additionalProperties": false
}
},
"required": [
"type",
"body",
"action"
],
"additionalProperties": false
}
]
}
},
"required": [
"messaging_product",
"to",
"type",
"interactive"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "location"
},
"location": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"name": {
"type": "string",
"maxLength": 1000
},
"address": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
}
},
"required": [
"messaging_product",
"to",
"type",
"location"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"messaging_product": {
"type": "string",
"const": "whatsapp"
},
"recipient_type": {
"type": "string",
"const": "individual"
},
"to": {
"type": "string"
},
"type": {
"type": "string",
"const": "contacts"
},
"contacts": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "object",
"properties": {
"formatted_name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"first_name": {
"type": "string",
"maxLength": 128
},
"last_name": {
"type": "string",
"maxLength": 128
},
"middle_name": {
"type": "string",
"maxLength": 128
},
"suffix": {
"type": "string",
"maxLength": 32
},
"prefix": {
"type": "string",
"maxLength": 32
}
},
"required": [
"formatted_name"
],
"additionalProperties": false
},
"phones": {
"maxItems": 3,
"type": "array",
"items": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"type": {
"type": "string",
"maxLength": 32
},
"wa_id": {
"type": "string",
"maxLength": 32
}
},
"required": [
"phone"
],
"additionalProperties": false
}
},
"emails": {
"maxItems": 3,
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 320,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"type": {
"type": "string",
"maxLength": 32
}
},
"required": [
"email"
],
"additionalProperties": false
}
},
"urls": {
"maxItems": 3,
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"type": {
"type": "string",
"maxLength": 32
}
},
"required": [
"url"
],
"additionalProperties": false
}
},
"org": {
"type": "object",
"properties": {
"company": {
"type": "string",
"maxLength": 256
},
"department": {
"type": "string",
"maxLength": 256
},
"title": {
"type": "string",
"maxLength": 256
}
},
"additionalProperties": false
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
},
"required": [
"messaging_product",
"to",
"type",
"contacts"
],
"additionalProperties": false
}
]
}Response: HTTP 202
{
"messaging_product": "whatsapp",
"messageId": "message_example",
"status": "queued"
}| Field | Required | Type and constraints |
|---|---|---|
messaging_product | Yes | {"const":"whatsapp"} |
messageId | Yes | {"type":"string","minLength":1,"maxLength":191} |
status | Yes | {"const":"queued"} |
Response body: complete JSON schema
Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.
{
"type": "object",
"properties": {
"messaging_product": {
"const": "whatsapp"
},
"messageId": {
"type": "string",
"minLength": 1,
"maxLength": 191
},
"status": {
"const": "queued"
}
},
"required": [
"messaging_product",
"messageId",
"status"
],
"additionalProperties": false
}Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.
API authentication
Authenticate server requests with a permanently number-bound Waaru API key, choose messaging and media scopes, and make a first read-only API call.
WhatsApp message formats
Build Waaru Developer API payloads for text, templates, linked media, interactive buttons and lists, locations, and one contact card with the supported field limits.