Send Message

Send a message through a connected WhatsApp account. Messages are queued and processed asynchronously.

Authentication

Include this header in every request. The value is automatically filled when you select a device above.

Header	Description
x-device-key	Your device key (generated in device settings)

POSThttps://www.beamvia.com/api/whatsapp/message/send

Request

curl -X POST https://www.beamvia.com/api/whatsapp/message/send \
  -H "Content-Type: application/json" \
  -H "x-device-key: YOUR_DEVICE_KEY" \
  -d '{
    "to": "+6281234567890",
    "message": {
      "type": "text",
      "text": "Hello from API!"
    }
  }'

Body Parameters

tostringrequired

Recipient phone number in E.164 format (e.g. +6281234567890). Spaces and dashes are cleaned internally.

messageobjectrequired

The message payload. Must include a type field.

message.typestringrequired

Message type. One of: text, image, video, audio, document, sticker, location, contact, reaction.

Request body

{
  "to": "+6281234567890",
  "message": {
    "type": "text",
    "text": "Hello from API!"
  }
}

Message Types

All message types with the type field and their specific fields.

Type	Required Fields	Optional Fields
text	text	—
image	url	caption
video	url	caption
audio	url	ptt
document	url	filename, mimetype
sticker	url	—
location	latitude, longitude	name, address
contact	name, phone	—
reaction	messageId, emoji	—

For media types (image, video, audio, document, sticker), the url field is required and must be a publicly accessible URL. The file will be downloaded and sent automatically.

curl -X POST https://www.beamvia.com/api/whatsapp/message/send \
  -H "Content-Type: application/json" \
  -H "x-device-key: YOUR_DEVICE_KEY" \
  -d '{
    "to": "+6281234567890",
    "message": {
      "type": "text",
      "text": "Hello from API!"
    }
  }'

Response

Returns the queue entry details on success. The message is processed asynchronously by the background service.

Error Responses

Code	Description
400	Missing required header or invalid request body
401	Unauthorized: Invalid device key
500	Internal server error

{
  "status": true,
  "message": "Message queued successfully",
  "data": {
    "queueId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "status": "IDLE",
    "queuedAt": "2026-02-11T10:30:00.000Z"
  }
}

Phone Number Format

The to field must be in E.164 international format.

Format	Example	Valid
With +	+6281234567890	✅
Without +	6281234567890	✅
With spaces/dashes	+62 812-3456-7890	✅ (cleaned)
Without country code	081234567890	❌

Internal conversion

// Input
"+6281234567890"

// Converted to JID internally
"[email protected]"

Queue Processing

Messages are queued and processed asynchronously by the background service with automatic retries.

Automatic retries: Failed messages are retried up to 3 times
FIFO ordering: Messages are processed in order
Atomic processing: Each message is atomically picked up

Queue Status Flow

IDLE → PROCESSING → COMPLETED
                    ↘ FAILED → PENDING_RETRY
                              ↘ (max 3 retries)