WhatsApp Gateway
API referenceMessages

Send a message

POST
/api/v1/sessions/{session}/messages

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, buttons, list).

Buttons use native-flow quick replies; lists use legacy ListMessage. Both are experimental, including for group JIDs. A send acknowledgement does not guarantee client rendering. WhatsApp may reject a list with 405; this returns not_implemented and is not retried.

Default mode is synchronous and returns 200 after a validated send. Set async=true for queued sends that return 202. A terminal replay also returns 200, including status=unknown when a remote effect may have committed. Idempotency is enabled with Idempotency-Key; replay returns the current durable result in the original session. Optional expiresAt is an absolute UTC epoch millisecond frozen by the first accepted row. No new WhatsApp dispatch starts at or after that deadline.

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 organization-scoped token. Reusing the key in its original session returns the current durable outbox result without sending again.

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

buttons?array<>|

Native-flow buttons (at most three): reply, url, or copy. Reply IDs must be unique.

Itemsitems <= 3
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.

expiresAt?integer

Optional absolute expiry as a UTC Unix epoch millisecond. No new WhatsApp dispatch starts at or after this instant. The first accepted value remains fixed for idempotent replays.

Formatint64
Example1791158400000
footer?string

Optional footer for buttons or list.

headerImage?

Optional image header for type buttons. Provide exactly one of data or url.

latitude?number

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

Formatdouble
Example-6.2
list?

Selection menu for type list. Client rendering is experimental.

longitude?number

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

Formatdouble
Example106.816666
media?

Optional image header for type buttons. Provide exactly one of data or url.

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 text, buttons, and list.

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

  • "buttons"
  • "list"
  • "text"
  • "poll"
  • "location"
  • "contact"
  • "image"
  • "video"
  • "audio"
  • "document"
  • "sticker"
  • "album"

Response Body

application/json

application/json

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,  "reservedMessageIds": [    "string"  ],  "status": "string",  "timestamp": 0,  "waMessageId": "string"}
{  "mode": "string",  "outboxId": "string",  "replayed": true,  "reservedMessageIds": [    "string"  ],  "status": "string",  "timestamp": 0,  "waMessageId": "string"}
{  "error": {    "code": "not_found",    "details": {      "property1": null,      "property2": null    },    "message": "session not found"  }}

Join a group by invite POST

Previous Page

Edit a sent text message PATCH

Next Page