v2

latestOpenAPI 3.1.02026-08-075421692.0 MB

WhatsApp Calling

Initiate outbound call

Initiates an outbound Business-Initiated Call. The Telnyx-side SIP leg is originated server-side (Option B: SIP-first). Telnyx INVITEs Meta directly over TLS:5061 with the SIP digest credentials we captured at calling-enablement time). No client-side SDP is required; pass only accountId and to.

To send the consumer the call-consent prompt instead of placing a call, pass action: "send_call_permission_request" (+ optional bodyText). The consumer must tap Allow in WhatsApp before start_call is permitted; Meta limits the prompt to 1 per consumer per 24h (2 per 7 days) and requires an open 24h service window.

Idempotency: send an Idempotency-Key header to make retries safe; same key + same body replays the original response instead of dialing (and billing) a second call.

post/v1/whatsapp/calls

Headers

Idempotency-Keystring

Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.

Request body

accountIdstring required

tostring required

Consumer wa_id (E.164, leading + optional)

action'send_call_permission_request'

Omit to place a call. Set to send the consent prompt instead.

bodyTextstring

Body text shown with the consent prompt (send_call_permission_request only).

forwardTostring

Per-call destination override. Same accepted shape as the number's stored forwardTo (tel:+E164, sip:..., wss://...).

recordOverrideboolean

biz_opaque_callback_datastring

Accepted for forward compatibility. Not currently echoed back in webhook payloads (SIP-first flow does not pass through Meta's Graph API where Meta would echo this).

Response

Call originated; lifecycle continues asynchronously via webhooks.

successboolean

callIdstring

Internal Call doc ID

telnyxCallControlIdstring

Telnyx call_control_id of the outbound leg

status'dialing'

direction'outbound'

tostring

forwardTostring nullable

recordingEnabledboolean