Skip to main content
POST
cURL
Refer to Authentication for information on how to obtain a bearer token.This endpoint requires the message.whatsapp.send API client authorization scope to send WhatsApp messages.You can configure scopes on the API Clients page.

Rate Limit

This endpoint is rate limited to 400 messages per second.

Request Modes

The type field selects how recipients share template parameters. Only approved, sendable templates can be sent. See WhatsApp templates. Both modes accept at most 10 recipients per request.

Template Parameters

Templates fill placeholders in the body, header, buttons, OTP, offers, carousel cards, media, and location components when the message is sent.

Parameter Types

Example

Success Response

A successful send returns HTTP 200. Queued recipients are counted in addresses. Recipients the API could not reserve are listed in skipped.
Numbers in skipped are E.164, for example +2348031234567.

Skipped recipients

Unit billing applies on sandbox teams and on Belio-managed WhatsApp services. When it applies, the API reserves bundle units from the template’s pricing category before it queues messages. Remaining units per category are available from List Bundles with productType=WHATSAPP. Every recipient in a request uses that one category. See Pricing categories. If that category reserves 0, nothing is queued. The API returns HTTP 400 instead of a partial skipped list. See When every category reserves zero. On HTTP 200, skipped is empty when every valid recipient was queued. Malformed numbers return HTTP 400 with Invalid phone number(s): .... They do not appear in skipped.

When every category reserves zero

If billing applies and every requested category reserves 0 units, nothing is queued. The API returns HTTP 400 with Insufficient units for N unit(s) requested. skipped is not returned on that response. The API also returns HTTP 400 when reservation fails for the whole request. desc is then the team balance error.

When billing does not apply

The send does not reserve WhatsApp bundle units when the team is not a sandbox team and the service is not Belio-managed. In that case units is {}, skipped is [], and addresses equals the number of valid recipients.

Integration guidance

Treat HTTP 200 as acceptance of the request, not confirmation of delivery. Read skipped on every success response. It is empty when every recipient was queued.
  • Use addresses and units for what was queued and reserved on this request.
  • If skipped is not empty, retry those numbers after topping up that category, or send them on a service that has units.
  • Use requestId to match delivery receipts for queued recipients only.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

serviceId
string
required

Unique identifier of the WhatsApp service

Body

application/json

WhatsApp template message send request

type
enum<string>
required

Must be "TemplateSendToMany"

Available options:
TemplateSendToMany
phoneNumberId
string
required

Phone number ID of the WABA sender. Must match a number registered on the service

templateId
string
required

ID of the approved WhatsApp template to send

addresses
string[]
required

Recipient phone numbers. Maximum 10 per request

Maximum array length: 10
params
object[]
required

Tagged template parameter used to fill body, header, button, OTP, offer, carousel, media, or location placeholders.

receiptRequest
object

Delivery receipt callback configuration. When provided, both fields are required.

Response

Successful send request accepted and queued

result
object
required