Send a message

Code	Status	Description
`200`	Success	Message queued for delivery
`400`	Bad Request	Invalid or missing required parameters
`401`	Unauthorized	Invalid or expired API token
`403`	Access denied	The token lacks permission for this action
`404`	Connection not found	The `from` number is not a connection on your account

Authorizations

x-api-key

string

header

required

Your Clapvo API token. Pass it in the x-api-key request header.

Body

application/json

from

string

required

Sender's WhatsApp number — the number the message is sent from. Must be a WhatsApp number connected to your Clapvo account. Use international format with the country code and no leading +, spaces, or dashes (e.g. 918495632548 for +91 84956 32548).

Example:

"918495632548"

string

required

Recipient's WhatsApp number — the number the message is sent to. Use the same international format as from: country code, no leading +, spaces, or dashes.

Example:

"918965742135"

message

object

required

The message content. Its fields change with message.type: text messages use type + message, while media messages use type + a media object.

Hide child attributes

message.type

enum<string>

required

What kind of message to send. This controls the rest of the payload:

message — plain text. Put the text in message.message; no media.
image — a photo. Include a media object.
document — a file such as a PDF. Include a media object.
video — a video clip. Include a media object.
audio — an audio clip or voice note. Include a media object.

Available options:

message,

image,

document,

video,

audio

message.message

string

The text body of the message. Required for the message (text) type — this is the text the recipient receives. Not used for media types; put any visible text in the media object's caption instead.

Example:

"ok public"

message.media

object

The file to attach. Required for image, document, video, and audio types; omit it for text messages.

Hide child attributes

message.media.name

string

required

The file name shown to the recipient, including its extension (e.g. .jpg, .pdf, .mp4, .mp3). Required.

Example:

"pdf-test.pdf"

message.media.url

string<uri>

required

A publicly accessible URL Clapvo downloads the file from before sending. Must be reachable without authentication. Required.

Example:

"https://clapvo-space.nyc3.cdn.digitaloceanspaces.com/.../pdf_test_1782191111069.pdf"

message.media.caption

string

Optional text shown beneath the media (ignored for audio). Send an empty string "" for no caption.

Response

Success — message queued for delivery.

success

boolean

Whether the request succeeded.

Example:

true

code

string

Clapvo status code.

Example:

"HC-1"

name

string

Machine-readable status name.

Example:

"success_200"

data

object

Hide child attributes

data.state

string

The delivery state of the message. QUEUED means Clapvo has accepted your request and added the message to the sending queue — messages are dispatched one by one, so this confirms receipt, not final delivery. To verify whether a message was actually sent, check your API logs in Clapvo.

Example:

"QUEUED"

message

string

Human-readable status message.

Example:

"Request was successful."

Get started

Messages

Webhooks

Status codes

Authorizations

Body

Response

​Status codes

Authorizations

Body

Response

Status codes