WhatsApp Calling

Initiate outbound call

Changed on

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

Request

  • Base URL: https://zernio.com/api
  • URL: https://zernio.com/api/v1/whatsapp/calls
  • Auth: HTTP bearer

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. A request cut off mid-handler (for example by a function timeout) can leave its key in progress, answering 409 until the key expires after 24 hours.

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

Changes

  • f8c8f34fb41aRevision changes
    • warning

      added the new account enum value to the / response property for the response status

  • d556591af3f6Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status