WA Gateway

Send one message or one grouped media album from the session.

Use type in the body to select a supported payload (text, poll, location, contact).

Default mode is synchronous and returns 200. Set async=true for queued async sends that return 202. Idempotency is enabled with Idempotency-Key.

Errors: validation_error, not_found, rate_limited, and not_implemented for unsupported types.

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token>. The token can be a login JWT from the frontend or an api-key for a script. JWT access comes from the person's organization role. Api-key access comes from the permissions saved on the key.

In: header

Path Parameters

session*string

WhatsApp session id that sends the message. Must be owned and connected.

Example"01HZX..."

Query Parameters

async?boolean

Set true to queue the send and return 202. False (default) waits for WhatsApp and returns 200.

Examplefalse

Header Parameters

Idempotency-Key?string

Optional idempotency token. Reusing the key returns the first send result and does not send again.

Example"2f1c9b6e-7a3d-4c2e-9f8a-1b2c3d4e5f60"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

caption?string

Optional single caption for an album. WhatsApp renders it with the grouped album.

Example"Trip photos"

contact?

The contact card to share. Required for type contact.

latitude?number

Latitude of the shared location in decimal degrees. Required for type location.

Formatdouble

Example-6.2

longitude?number

Longitude of the shared location in decimal degrees. Required for type location.

Formatdouble

Example106.816666

media?

The media file to send. Required for the media types (image/video/audio/document/sticker); provide exactly one of media.data (base64) or media.url (HTTP(S)). Caption, replyTo, and mentions apply.

medias?array<>|

The ordered album items. Required for type album; 2–10 image/video items, each with exactly one of data or url.

mentions?array<string>|

JIDs to @-mention in the message. Optional.

Example

[  "6289876543210@s.whatsapp.net"]

name?string

For a poll, the poll question; for a location, the place label. Required for poll; optional for location.

Example"Lunch on Friday?"

options?array<string>|

The poll's answer options. Required for type poll.

Example

[  "Yes",  "No",  "Maybe"]

pollEndTime?integer

Optional poll closing time as epoch milliseconds. Used for type poll when WhatsApp supports poll end times.

Formatint64

Example1719662400000

pollHideVotes?boolean

When true, ask WhatsApp to hide participant names in the poll vote list. Used for type poll.

Exampletrue

replyTo?string

Id of the message this one quotes/replies to (a wa_message_id). Optional.

Example"3EB0C431C26A1916E001"

selectableCount?integer

How many options a voter may pick in the poll (1 = single choice). Used for type poll.

Formatint64

Example1

text?string

The message text. Required for type text; ignored otherwise.

Example"Hello there!"

to*string

The recipient's JID: a user JID for a direct message (e.g. 6281234567890@s.whatsapp.net) or a group JID for a group (e.g. 120363021234567890@g.us). Required.

Example"6281234567890@s.whatsapp.net"

type*string

Which kind of message to send. The media types use media; album uses medias with 2–10 images/videos and an optional shared caption. Each media source may independently be base64 data or an HTTP(S) URL.

Example"text"

Value in

"text"
"poll"
"location"
"contact"
"image"
"video"
"audio"
"document"
"sticker"
"album"

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/sessions/01HZX.../messages" \  -H "Content-Type: application/json" \  -d '{    "to": "6281234567890@s.whatsapp.net",    "type": "text"  }'

{  "mode": "string",  "outboxId": "string",  "replayed": true,  "status": "string",  "timestamp": 0,  "waMessageId": "string"}

{  "error": {    "code": "not_found",    "details": {      "property1": null,      "property2": null    },    "message": "session not found"  }}

Send a message

Authorization

Path Parameters

Query Parameters

Header Parameters

Request Body

Response Body

200application/json

defaultapplication/json

`application/json`

`application/json`