Skip to main content
POST
Authenticate with a key generated on this campaign’s API Keys tab, not an organization key. Run Validate a campaign call first to check a request without paying for it. See the Webhook campaigns API overview for keys, contract locking, and lifecycle.
string
required
The webhook campaign ID. The Contract tab on the campaign page shows the full URL for your campaign.
string
required
Recipient phone number in international format with the leading + and country code, for example +15551234567. Any other format fails with 422 invalid_params and an errors entry of { "field": "to", "code": "invalid_e164" }. The recipient is matched to an existing end user by phone, with or without the leading +, before a new end user is created.
object
Template parameters as string values, keyed by parameter name. Required when the campaign’s template has parameters.
object
{ "url": "…" }. Required when the template has a media header. Tars fetches the URL and checks it against the header’s media type.

Response

string
"sent" means WhatsApp accepted the message, not that it was delivered. Delivery confirmations arrive from the provider later, and some outcomes can stay unconfirmed.
number
The cost charged for this call, in USD. It is 0 when the WhatsApp number is in Staging mode.
number
The campaign wallet balance after the charge.
string
The tars_… request ID, for support and log correlation.
string
The provider’s message ID for the accepted message.

Errors

Two campaign-status codes matter most for client logic.
retryable
The campaign is not active. Retryable, because the campaign can become active again. This response carries no Retry-After header, so resume the campaign and retry on your own schedule.
terminal
The campaign is cancelled or failed. Terminal, so stop calling the endpoint for this campaign.
All failures use RFC 9457 problem details with a retryable flag. Branch on retryable, not on the status number. See the full error catalog.

Authorizations

Authorization
string
header
required

API key sent as Authorization: Bearer YOUR_API_KEY. Campaign endpoints use campaign-scoped keys; the rest use organization or agent keys with the matching permission.

Path Parameters

campaignId
string
required

The campaign's ID. The campaign page's Contract tab shows the full URL for your campaign.

Body

application/json

One webhook campaign send.

to
string
required

Recipient phone number in international format

params
object

Template parameters keyed by slot name

media
object

Media for the template's media slot. Sending it to a template with no media slot returns unknown_param on media.url.

Response

Message sent and charged

status
string
required

Always sent on a successful call. The message was accepted and the wallet was charged.

Allowed value: "sent"
quoted_usd
number
required

What this send cost in US dollars, charged to the campaign wallet.

tars_request_id
string
required

The tars_… request ID. Quote it when contacting support about this send.

balance
number

The campaign wallet balance in US dollars after the charge.

external_message_id
string

The provider's message ID, when the provider returned one.