Senders

API reference descriptions are provided in English to preserve the exact published contract.

List sender pools

GET /v1/accounts/{AC}/sender-pools

getV1AccountsByAcSenderPoolsPaginated200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a sender pool

POST /v1/accounts/{AC}/sender-pools

postV1AccountsByAcSenderPoolsIdempotency-Key required201

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (3 fields)

Request body
Name	Type	Required
`name`	string (max 128 chars)	yes
`senderSids`	string (WA… SID)[]	yes
`strategy`	"round_robin" \| "least_loaded" \| "sticky_contact"	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch a sender pool

GET /v1/accounts/{AC}/sender-pools/{SP}

getV1AccountsByAcSenderPoolsBySp200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`SP`	path · string (SP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update a sender pool

PATCH /v1/accounts/{AC}/sender-pools/{SP}

patchV1AccountsByAcSenderPoolsBySpIdempotency-Key required200

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`SP`	path · string (SP… SID)	yes

Request body (3 fields)

Request body
Name	Type	Required	Description
`name`	string (max 128 chars)
`senderSids`	string (WA… SID)[]
`strategy`	"round_robin" \| "least_loaded" \| "sticky_contact"

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Delete a sender pool

DELETE /v1/accounts/{AC}/sender-pools/{SP}

deleteV1AccountsByAcSenderPoolsBySp204

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`SP`	path · string (SP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List WhatsApp senders and current provider readiness

GET /v1/accounts/{AC}/senders

getV1AccountsByAcSendersPaginated200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Subscribe a WABA and register a Cloud API sender

POST /v1/accounts/{AC}/senders

postV1AccountsByAcSendersIdempotency-Key required202

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (5 fields)

Request body
Name	Type	Required
`displayName`	string (max 256 chars)	yes
`phoneNumber`	string (max 32 chars)
`providerPhoneNumberId`	string (max 128 chars)
`registration`	object	yes
`wabaSid`	string (WB… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List provider storage regions permitted by this account's residency policy

GET /v1/accounts/{AC}/senders/storage-regions

getV1AccountsByAcSendersStorageRegions200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch a WhatsApp sender

GET /v1/accounts/{AC}/senders/{WA}

getV1AccountsByAcSendersByWa200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update sender management settings

PATCH /v1/accounts/{AC}/senders/{WA}

patchV1AccountsByAcSendersByWaIdempotency-Key required200202

A display-name change creates a durable Operation. statusCallbackUrl is a local verified-endpoint binding. Calling settings fail closed until Meta publishes an exact supported versioned write contract. Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (3 fields)

Request body
Name	Type	Required	Description
`callingSettings`	object
`displayName`	string (max 256 chars)
`statusCallbackUrl`	string (uri, max 2048 chars) \| null

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Remove a sender locally without changing Meta assets

DELETE /v1/accounts/{AC}/senders/{WA}

deleteV1AccountsByAcSendersByWa204

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Block WhatsApp users

POST /v1/accounts/{AC}/senders/{WA}/block-users

postV1AccountsByAcSendersByWaBlockUsersIdempotency-Key required200

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`users`	string (max 64 chars)[]	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Unblock WhatsApp users

DELETE /v1/accounts/{AC}/senders/{WA}/block-users

deleteV1AccountsByAcSendersByWaBlockUsers200

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`users`	string (max 64 chars)[]	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Get the current reconciled WhatsApp business profile

GET /v1/accounts/{AC}/senders/{WA}/business-profile

getV1AccountsByAcSendersByWaBusinessProfile200

Required scope: `business_profiles:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`WA`	path · string (WA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create an Operation-backed WhatsApp business profile update

PATCH /v1/accounts/{AC}/senders/{WA}/business-profile

patchV1AccountsByAcSendersByWaBusinessProfileIdempotency-Key required202

Required scope: `business_profiles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`WA`	path · string (WA… SID)	yes

Request body (8 fields)

Request body
Name	Type	Required
`about`	string (max 139 chars) \| null
`address`	string (max 256 chars) \| null
`category`	string (max 128 chars) \| null
`description`	string (max 512 chars) \| null
`email`	string (email, max 320 chars) \| null
`profileImageMediaSid`	string (ME… SID) \| null
`reason`	string (max 2000 chars)	yes
`websites`	string (uri, max 2048 chars)[]

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Deregister a Cloud API sender

POST /v1/accounts/{AC}/senders/{WA}/deregister

postV1AccountsByAcSendersByWaDeregisterIdempotency-Key required200

Creates a monitored DEREGISTER Operation. Coexistence numbers cannot be deregistered.: the provider decides the final state, so the answer is 200 with `outcome: unknown` and `resolutionBy` naming the Operation to watch. Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Generate, upload and verify a sender Flow encryption key

POST /v1/accounts/{AC}/senders/{WA}/flows/keys

postV1AccountsByAcSendersByWaFlowsKeysIdempotency-Key required202

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch sender opt-out keyword configuration

GET /v1/accounts/{AC}/senders/{WA}/opt-out-config

getV1AccountsByAcSendersByWaOptOutConfig200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Replace sender opt-out keyword configuration

PUT /v1/accounts/{AC}/senders/{WA}/opt-out-config

putV1AccountsByAcSendersByWaOptOutConfigIdempotency-Key required200

Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (9 fields)

Request body
Name	Type	Required
`confirmation`	object	yes
`confirmationTexts`	object
`enabled`	boolean	yes
`excludedKeywords`	string (max 64 chars)[]
`languages`	string (max 35 chars)[]	yes
`matchMode`	"tolerant" \| "exact" \| "starts_with" \| "contains"	yes
`optInKeywords`	string (max 64 chars)[]	yes
`optOutKeywords`	string (max 64 chars)[]	yes
`scopeOnOptOut`	"marketing" \| "all"	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Rotate the sender two-step verification PIN

POST /v1/accounts/{AC}/senders/{WA}/two-step-pin

postV1AccountsByAcSendersByWaTwoStepPinIdempotency-Key required202

Creates a monitored REGISTER Operation running the SET_TWO_STEP command. The PIN is sealed through the credential broker and is never returned or logged. Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`pin`	string (pattern ^[0-9]{6}$)
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Request or submit a sender verification code

POST /v1/accounts/{AC}/senders/{WA}/verify

postV1AccountsByAcSendersByWaVerifyIdempotency-Key required202

Creates a REGISTER Operation; verification codes are stored only as short-lived encrypted envelopes. Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (3 fields)

Request body
Name	Type	Required	Description
`code`	string (pattern ^[0-9]{1,16}$)
`codeMethod`	"sms" \| "voice"
`locale`	string (pattern ^[a-z]{2,3}_[A-Z]{2}$)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Read the phone-level webhook override of a sender

GET /v1/accounts/{AC}/senders/{WA}/webhook-override

getV1AccountsByAcSendersByWaWebhookOverride200

Required scope: `senders:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Set or clear the phone-level webhook override of a sender

PATCH /v1/accounts/{AC}/senders/{WA}/webhook-override

patchV1AccountsByAcSendersByWaWebhookOverrideIdempotency-Key required202

Records the desired phone-level webhook_configuration and queues the SENDER_WEBHOOK_OVERRIDE management job that writes it to Meta. Phone-level takes precedence over the WABA-level override and the app default; the daily subscription reconcile keeps it converged. Required scope: `senders:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WA`	path · string (WA… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`overrideCallbackUri`	string (pattern ^https://, max 2048 chars) \| null	yes
`reason`	string (max 2000 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Disconnect a WABA and fence all of its senders

POST /v1/accounts/{AC}/wabas/{WB}/disconnect

postV1AccountsByAcWabasByWbDisconnectIdempotency-Key required202

Required scope: `wabas:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`WB`	path · string (WB… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`confirmDisplayName`	string (max 256 chars)	yes
`stepUpEvidence`	string (max 4096 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.