Send Message API
Send WhatsApp messages programmatically including text, images, videos, documents, and template messages through the Vobiz API.
Message Types Supported
This endpoint supports all WhatsApp message types: text, image, video, audio, document, location, contacts, and template messages.
Endpoint
/v1/messaging/sendBase URL
https://api.vobiz.com/v1/messaging/sendRequest Parameters
Request Body Parameters
| Parameter | Type | Description |
|---|---|---|
channel_idrequired | string | ID of the WhatsApp channel to send from |
torequired | string | Recipient phone number in E.164 format (e.g., +1234567890) |
typerequired | string | Message type: text, image, video, document, template |
textoptional | object | Text message content (required if type is "text") |
imageoptional | object | Image message content (required if type is "image") |
videooptional | object | Video message content (required if type is "video") |
documentoptional | object | Document message content (required if type is "document") |
templateoptional | object | Template message content (required if type is "template") |
Sending Text Messages
Send plain text messages to your customers. Text messages can be up to 4096 characters long.
curl -X POST https://api.vobiz.com/v1/messaging/send \
-H "X-Auth-ID: your_auth_id" \
-H "X-Auth-Token: your_auth_token" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "ch_abc123",
"to": "+1234567890",
"type": "text",
"text": {
"body": "Hello! Thanks for contacting us. How can we help you today?"
}
}'Text Object Properties
| Property | Type | Description |
|---|---|---|
| body | string | Message content (max 4096 characters) |
| preview_url | boolean | Show URL preview if message contains links (optional, default: false) |
Sending Media Messages
Send images, videos, or documents with optional captions.
Image Message Example
curl -X POST https://api.vobiz.com/v1/messaging/send \
-H "X-Auth-ID: your_auth_id" \
-H "X-Auth-Token: your_auth_token" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "ch_abc123",
"to": "+1234567890",
"type": "image",
"image": {
"url": "https://example.com/product-image.jpg",
"caption": "Check out our new product!"
}
}'Media Object Properties
For Image/Video/Document:
| Property | Type | Description |
|---|---|---|
| url | string | Public URL of the media file |
| caption | string | Optional caption (max 1024 characters) |
| filename | string | Optional filename (for documents) |
⚠️ Media File Requirements
- • Images: JPG, PNG - Max 5MB
- • Videos: MP4, 3GPP - Max 16MB
- • Documents: PDF, DOC, XLSX, etc. - Max 100MB
- • Media must be publicly accessible via HTTPS URL
Sending Template Messages
Send pre-approved template messages for marketing, authentication, or utility purposes.
curl -X POST https://api.vobiz.com/v1/messaging/send \
-H "X-Auth-ID: your_auth_id" \
-H "X-Auth-Token: your_auth_token" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "ch_abc123",
"to": "+1234567890",
"type": "template",
"template": {
"name": "order_confirmation",
"language": "en",
"parameters": [
{
"type": "text",
"text": "John Doe"
},
{
"type": "text",
"text": "ORD-12345"
},
{
"type": "text",
"text": "$99.99"
}
]
}
}'Template Object Properties
| Property | Type | Description |
|---|---|---|
| name | string | Template name from Meta Business Manager |
| language | string | Language code (e.g., "en", "es", "pt_BR") |
| parameters | array | Array of parameter objects for template variables |
💡 Template Requirements
Templates must be created and approved in Meta Business Manager before you can use them. See our Templates Guide for details.
Response
Success Response (200 OK)
{
"success": true,
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MAA=",
"status": "sent",
"to": "+1234567890",
"timestamp": "2024-03-19T10:30:00Z"
}
}Response Fields
| Parameter | Type | Description |
|---|---|---|
message_idoptional | string | Unique identifier for the sent message |
statusoptional | string | Message status: "sent", "queued" |
tooptional | string | Recipient phone number |
timestampoptional | string | ISO 8601 timestamp when message was sent |
Error Response (4xx/5xx)
{
"success": false,
"error": {
"code": "INVALID_NUMBER",
"message": "The recipient phone number is invalid",
"details": "Phone number must be in E.164 format with country code"
}
}Common Error Codes
INVALID_NUMBER
Phone number format is invalid or not on WhatsApp
INVALID_CHANNEL
Channel ID doesn't exist or isn't active
TEMPLATE_NOT_FOUND
Template doesn't exist or isn't approved
RATE_LIMIT_EXCEEDED
Too many messages sent, retry after cooldown