Skip to main content
POST
Authentication: every request needs the 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.
This endpoint sends these WhatsApp message types: 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).
This endpoint sends a real message to a real person and can be charged to your account. Use your own credentials and confirm the recipient before you send.

Endpoint

Request body

Sending text messages

Send plain text messages to your customers. Provide the text object with a body field. You can send text only while a conversation with the recipient is open (see The 24-hour conversation window).
cURL

Sending media messages

Send images, video, audio, documents, or stickers. All media types share a single media 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

Send 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 - upload media
The response carries the ID as media_id, for example { "media_id": "1234567890123456", "type": "application/pdf" }.
cURL - image example
cURL - document example

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

Templates must be approved by Meta before you can send them. See our Templates Guide and the Templates API for details.
cURL - template example

Response

Success response (201 Created)

A 201 means Meta accepted the message. The body is the stored Message object, with status pending until delivery updates arrive.

Message object fields

Common errors

  • 400 Bad Request - A required field is missing (for example to, type, text.body, the template name or language.code, or media.id / media.link), neither channel_id nor waba_id was sent, the channel was not found, no conversation is open for a text or media message, or Meta rejected the message (error then starts with meta 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.
400 - no open conversation
A 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: For the full list, see Meta’s Cloud API error codes.

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 type works.
  • No open conversation: send type: "template". Vobiz rejects a text or media send right away with 400 and open 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.
If you are unsure whether a conversation is open, send an approved template. Templates are always allowed.

Correlating delivery updates

  • The response id is the Vobiz message UUID. The Meta ID (wamid) is in meta_message_id in the same 201 response.
  • Correlate later message.status webhooks back to the send using the wamid (the statuses[].id in the webhook equals meta_message_id).

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token
string
header
required

Your Vobiz account Auth Token.

Path Parameters

auth_id
string
required

Your account Auth ID. It must match the X-Auth-ID header.

Example:

"MA_XXXXXXXX"

Body

application/json

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.

to
string
required

Recipient phone number in E.164 format. A missing leading + is added.

Example:

"+919876543210"

type
enum<string>
required

The message type. It selects which of text, template or media you send.

Available options:
text
text
object
required
channel_id
string<uuid>

The channel to send from. Required unless you send waba_id.

Example:

"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1"

waba_id
string

The WhatsApp Business Account ID of the channel to send from. Used only when channel_id is not sent.

Example:

"123456789012345"

Response

Meta accepted the message. The body is the stored message, pending until status updates arrive.

id
string<uuid>
required

Vobiz message ID.

Example:

"9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01"

account_id
string
required
Example:

"MA_XXXXXXXX"

channel_id
string<uuid>
required
Example:

"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1"

contact_id
string<uuid>
required
Example:

"4f9c2a18-3e6b-4d2f-8b1a-9e7c5d3f1a02"

conversation_id
string<uuid> | null
required

The conversation the message belongs to.

Example:

"c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04"

direction
enum<string>
required
Available options:
inbound,
outbound
Example:

"outbound"

type
string
required

Message type, for example text, template, image or document. Inbound messages can also be interactive, location, contacts and other WhatsApp types.

Example:

"text"

status
enum<string>
required

Delivery state. Outbound messages start as pending; inbound messages are delivered.

Available options:
pending,
sent,
delivered,
read,
failed
Example:

"pending"

content
string
required

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.

Example:

"{\"channel_id\":\"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1\",\"waba_id\":\"\",\"to\":\"+919876543210\",\"type\":\"text\",\"text\":{\"body\":\"Hello from Vobiz!\"}}"

meta_error_code
string | null
required

Meta's error code when the message failed, otherwise null.

Example:

null

meta_error_description
string | null
required

Meta's error detail when the message failed, otherwise null.

Example:

null

created_at
string<date-time>
required
Example:

"2026-10-16T21:23:51Z"

meta_message_id
string

The WhatsApp message ID (wamid). Status webhooks for this message carry it as statuses[].id.

Example:

"wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQzVGNkE3QjhDOUQwRTFGMkEzAA=="