Send a WhatsApp message

POST /v1/whatsapp/messages

Scope: whatsapp:send
Tier: Tier 1
Data: Personal data
Idempotency: Idempotency-Key: required

Not available yet. This operation is not available for any account yet: it answers 403 tier_not_enabled whatever the account's scopes and switches say, and nothing is sent. It is documented so that its shape is known.

Sends a text, or one of the account's approved WhatsApp templates with its values, from the account's own WhatsApp number. Every message carries your own client_reference: a second message with the same reference answers 409 duplicate_client_reference and nothing is sent again. A free text outside the customer's 24-hour service window can be refused by WhatsApp; use a template there. 202 means accepted: status is sent, pending, failed or blocked (the account cannot send WhatsApp now). Not available yet: this operation answers 403 tier_not_enabled for every account until DialerBee announces it.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	yes	Your unique value for this logical operation (a UUID is fine). Scoped to your API client, kept 24 hours. (min length 1; max length 255)
`X-Correlation-ID`	header	string	no	Your own trace value, logged with the request. Metadata only, never identity. (min length 1; max length 128)

Request body

The message.

JSON: WhatsAppSendRequest

Response

202: Accepted for sending.

Header	Meaning
`X-Request-ID`	The DialerBee request id. Quote it to support. Every response carries X-Request-ID: req_<ULID>, or edge_<32 hex> when the edge answered before the request reached the API.
`Cache-Control`	Always `no-store`.
`Idempotency-Replayed`	`true` when this answer is the stored answer of an earlier request with the same `Idempotency-Key`.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "to": "+12125550101",
  "template": {
    "name": "appointment_reminder",
    "params": {
      "1": "Thursday 10:00"
    }
  },
  "client_reference": "order-1001-reminder"
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.whatsapp.send(
    to="+12125550101",
    template={"name": "appointment_reminder", "params": {"1": "Thursday 10:00"}},
    client_reference="order-1001-reminder",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

202

{
  "id": "msg_0f8fad5b-d9cb-469f-a165-70867728950e",
  "to": "+12125550101",
  "status": "sent",
  "client_reference": "order-1001-reminder",
  "created_at": "2026-09-29T12:00:00Z"
}

Error examples

422 blocked_country

{
  "type": "https://docs.dialerbee.com/errors/blocked-country",
  "title": "Destination country blocked",
  "status": 422,
  "detail": "The platform does not contact numbers in this country.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "blocked_country",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

409 duplicate_client_reference

{
  "type": "https://docs.dialerbee.com/errors/duplicate-client-reference",
  "title": "Duplicate client reference",
  "status": 409,
  "detail": "A message with this client_reference was already accepted for this API client.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "duplicate_client_reference",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

403 insufficient_scope

{
  "type": "https://docs.dialerbee.com/errors/insufficient-scope",
  "title": "Not permitted",
  "status": 403,
  "detail": "The API client does not hold the scope this operation requires.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "insufficient_scope",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Status	Code	Title
401	`invalid_api_key`	Invalid API key
403	`api_access_disabled`	API access disabled
403	`ip_not_allowed`	IP address not allowed
403	`insufficient_scope`	Not permitted
400	`credential_in_url`	Credential in URL
400	`credential_in_body`	Credential in body
400, 422	`validation_failed`	Invalid request
413	`payload_too_large`	Payload too large
415	`unsupported_media_type`	Unsupported media type
400	`idempotency_key_required`	Idempotency-Key required
403	`tier_not_enabled`	Capability not enabled
422	`blocked_country`	Destination country blocked
409	`duplicate_client_reference`	Duplicate client reference
409	`conflict`	Request in progress
409	`idempotency_conflict`	Idempotency key reused
409	`outcome_unknown`	Outcome unknown
429	`rate_limit_exceeded`	Too many requests
503	`temporarily_unavailable`	Temporarily unavailable
503	`upstream_unavailable`	Temporarily unavailable
502	`upstream_invalid_response`	Upstream error
500	`internal_error`	Internal error

Objects

WhatsAppSendRequest

Send exactly one of text or template.

Field	Type	Required	Description
`to`	string (E.164 phone)	yes	A phone number in E.164 form.
`text`	string	no	(min length 1; max length 4096)
`template`	WhatsAppTemplate	no
`client_reference`	string	yes	Your unique reference for this message; a duplicate is refused. (min length 1; max length 64)

WhatsAppMessage

Field	Type	Required	Description
`id`	string (SmsMessageId)	yes	An outbound message (SMS or WhatsApp). `msg_` + a lower-case UUID.
`to`	string	yes
`status`	string	yes
`client_reference`	string	yes
`created_at`	string (date-time)	yes

WhatsAppTemplate

Field	Type	Required	Description
`name`	string	yes	The approved template's name.
`params`	object	no	The template's values by variable name (or 1, 2, ... for positional variables). (max keys 20)