WhatsApp Send Message API — Text, Media & Template Messages
Send WhatsApp messages via the Vobiz REST API - text, images, video, audio, documents, stickers, and Meta-approved templates over a single endpoint.
curl --request POST \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Message/ \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"to": "+919876543210",
"type": "text",
"text": {
"body": "Hello from Vobiz!"
}
}
'{
"id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"contact_id": "4f9c2a18-3e6b-4d2f-8b1a-9e7c5d3f1a02",
"conversation_id": "c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04",
"direction": "outbound",
"type": "text",
"status": "pending",
"content": "{\"channel_id\":\"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1\",\"waba_id\":\"\",\"to\":\"+919876543210\",\"type\":\"text\",\"text\":{\"body\":\"Hello from Vobiz!\"}}",
"meta_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQzVGNkE3QjhDOUQwRTFGMkEzAA==",
"meta_error_code": null,
"meta_error_description": null,
"created_at": "2026-10-16T21:23:51Z"
}X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. Send Content-Type: application/json.
text, template, image, video, audio, document, and sticker. Set the type field to one of these and include the matching object (text, template, or media).Endpoint
POST https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Message/
Request body
| Property | Type | Required | Description |
|---|---|---|---|
channel_id | string (UUID) | One of channel_id or waba_id | The WhatsApp channel to send from. If you send both, channel_id wins. |
waba_id | string | One of channel_id or waba_id | The WhatsApp Business Account ID of the channel to send from. Used only when you don’t send channel_id. |
to | string | Required | Recipient phone number in E.164 format (e.g. +919876543210). A missing leading + is added. |
type | string | Required | One of text, template, image, video, audio, document, sticker |
text | object | When type=text | Text message body |
media | object | For media types | Shared media object for image, video, audio, document, sticker |
template | object | When type=template | Template message payload |
Sending text messages
Send plain text messages to your customers. Provide thetext object with a body field. You can send text only while a conversation with the recipient is open (see The 24-hour conversation window).
| Property | Type | Description |
|---|---|---|
text.body | string | Message content. Required and can’t be empty. |
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Message/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"type": "text",
"text": { "body": "Hello from Vobiz!" }
}'
Sending media messages
Send images, video, audio, documents, or stickers. All media types share a singlemedia object. Supply either a public link (HTTPS URL) or a media id. Like text, media needs an open conversation with the recipient.
Media object properties
| Property | Type | Description |
|---|---|---|
link | string | Public HTTPS URL of the media file |
id | string | A media ID from POST /api/v1/Account/{auth_id}/WhatsApp/Media/ (alternative to link) |
caption | string | Optional caption (for image, video, document) |
filename | string | Optional file name shown to the recipient (for document) |
id or link. To get a media id, upload the file as multipart/form-data with a channel_id field and a file field (up to 16 MB):
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Media/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-F "channel_id=0a8f3feb-9598-47f2-8a6c-df1aeb306ae1" \
-F "file=@/path/to/invoice.pdf;type=application/pdf"
media_id, for example { "media_id": "1234567890123456", "type": "application/pdf" }.
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Message/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"type": "image",
"media": {
"link": "https://example.com/photo.jpg",
"caption": "Check this out!"
}
}'
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Message/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"type": "document",
"media": {
"link": "https://example.com/invoice.pdf",
"filename": "invoice.pdf",
"caption": "Your invoice"
}
}'
Sending template messages
Send pre-approved template messages for marketing, authentication, or utility purposes. A template can always be sent, and it opens a new conversation with the recipient.Template object properties
| Property | Type | Description |
|---|---|---|
name | string | Required. Name of an approved template on the channel’s WABA |
language | object | Required. Language object with a code field (e.g. { "code": "en_US" }) |
category | string | Optional. The template’s category: marketing, utility, authentication, or service. Case-insensitive; defaults to service. |
components | array | Optional. Template parameters in Meta’s send format, for example a body component with parameters |
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Message/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"to": "+919876543210",
"type": "template",
"template": {
"name": "order_confirmation",
"language": { "code": "en_US" },
"category": "utility",
"components": [{
"type": "body",
"parameters": [
{ "type": "text", "text": "ORD-12345" },
{ "type": "text", "text": "March 15" }
]
}]
}
}'
Response
Success response (201 Created)
A201 means Meta accepted the message. The body is the stored Message object, with status pending until delivery updates arrive.
{
"id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"contact_id": "4f9c2a18-3e6b-4d2f-8b1a-9e7c5d3f1a02",
"conversation_id": "c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04",
"direction": "outbound",
"type": "text",
"status": "pending",
"content": "{\"channel_id\":\"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1\",\"waba_id\":\"\",\"to\":\"+919876543210\",\"type\":\"text\",\"text\":{\"body\":\"Hello from Vobiz!\"}}",
"meta_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQzVGNkE3QjhDOUQwRTFGMkEzAA==",
"meta_error_code": null,
"meta_error_description": null,
"created_at": "2026-10-16T21:23:51Z"
}
Message object fields
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Vobiz message ID |
account_id | string | Your account ID (MA_…) |
channel_id | string (UUID) | Channel the message was sent from |
contact_id | string (UUID) | Contact the message was sent to. Vobiz creates the contact if it doesn’t exist. |
conversation_id | string (UUID) or null | Conversation the message belongs to |
direction | string | outbound for sent messages |
type | string | The message type you sent (text, template, image, and so on) |
status | string | One of pending, sent, delivered, read, failed. Starts as pending. |
content | string | Your whole send request, as a JSON-encoded string. Parse it to read the body and media fields. |
meta_message_id | string | The WhatsApp message ID (wamid) Meta assigned to the message |
meta_error_code | string or null | Meta’s error code when the message failed, otherwise null |
meta_error_description | string or null | Meta’s error detail when the message failed, otherwise null |
created_at | string (RFC3339 UTC) | When the message was created |
Common errors
400 Bad Request- A required field is missing (for exampleto,type,text.body, the templatenameorlanguage.code, ormedia.id/media.link), neitherchannel_idnorwaba_idwas sent, the channel was not found, no conversation is open for a text or media message, or Meta rejected the message (errorthen starts withmeta send failed).401 Unauthorized- Missing or invalid authentication credentials.403 Forbidden- The{auth_id}in the path is not the account your credentials belong to.
{ "error": "open conversation required for text messages" }
201 from Vobiz means the message was accepted, not delivered. A message can still end as failed later - watch the message.status webhook for the final state and any error reason from Meta.
When Meta reports a problem, meta_error_code and meta_error_description say what to fix. Common codes:
| Code | Meaning | What to do |
|---|---|---|
131042 | The WhatsApp Business account has a payment issue with Meta | Settle the account’s billing in Meta Business Suite, then send again |
133010 | The phone number isn’t registered with the WhatsApp Cloud API | Finish registering the number in Meta, then send again |
131026 | The message couldn’t be delivered to the recipient | Check the number uses WhatsApp, and that the recipient can receive messages from businesses |
131047 | More than 24 hours have passed since the customer’s last reply | Send an approved template to start a new conversation |
132001 | The template doesn’t exist in that language | Check the template name and language.code against your approved templates |
The 24-hour conversation window
WhatsApp lets you send free-form messages (text and media) only while a conversation with the contact is open. A conversation opens when the contact messages you, or when you send them a template, and it stays open for 24 hours from when it started.
- Conversation open: any
typeworks. - No open conversation: send
type: "template". Vobiz rejects a text or media send right away with400andopen conversation required for <type> messages, so no message goes out. - Open a new conversation: send an approved template. It opens a new 24-hour conversation, and you can follow up with text and media inside it.
Correlating delivery updates
- The response
idis the Vobiz message UUID. The Meta ID (wamid) is inmeta_message_idin the same201response. - Correlate later
message.statuswebhooks back to the send using thewamid(thestatuses[].idin the webhook equalsmeta_message_id).
Related topics
Authorizations
Path Parameters
Body
- Text
- Template
- Media
A free-form text message. You can send it only while a conversation with the recipient is open, that is one started by their message or by your template within the last 24 hours.
Response
Meta accepted the message. The body is the stored message, pending until status updates arrive.
The message as a JSON-encoded string. For outbound messages it is the send request you made; for inbound messages it is the WhatsApp message object. Parse it to read the body and media fields.
"{\"channel_id\":\"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1\",\"waba_id\":\"\",\"to\":\"+919876543210\",\"type\":\"text\",\"text\":{\"body\":\"Hello from Vobiz!\"}}"
Was this page helpful?
curl --request POST \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Message/ \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"to": "+919876543210",
"type": "text",
"text": {
"body": "Hello from Vobiz!"
}
}
'{
"id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"contact_id": "4f9c2a18-3e6b-4d2f-8b1a-9e7c5d3f1a02",
"conversation_id": "c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04",
"direction": "outbound",
"type": "text",
"status": "pending",
"content": "{\"channel_id\":\"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1\",\"waba_id\":\"\",\"to\":\"+919876543210\",\"type\":\"text\",\"text\":{\"body\":\"Hello from Vobiz!\"}}",
"meta_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQzVGNkE3QjhDOUQwRTFGMkEzAA==",
"meta_error_code": null,
"meta_error_description": null,
"created_at": "2026-10-16T21:23:51Z"
}