WhatsApp

Place a WhatsApp call

Business-initiated WhatsApp call from number_id to to, answered by agent_id (defaults to the number's agent). Fails with 403 call_permission_required unless the user has a live call permission. Not available in every country (Meta blocks business-initiated calls in the US, Canada, Egypt, Vietnam and Nigeria at the time of writing). Requires an Idempotency-Key and the telephony:manage scope.

post/v1/whatsapp/calls

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/whatsapp/calls
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Headers

Idempotency-Keystring required

Safe retry key. Reusing it with the same input replays the original call; different input returns 409 idempotency_conflict.

Request body

number_idstring required
tostring required

The user's WhatsApp number (E.164).

agent_idstring nullable

Defaults to the number's agent.

Example request

{
  "to": "+919876543210"
}

Response

Call placed (ringing)

objectstring
idstring
number_idstring
wa_call_idstring nullable

Meta's call id (wacid...).

direction'inbound' | 'outbound'
userstring
agent_idstring nullable
status'ringing' | 'accepted' | 'connected' | 'completed' | 'failed' | 'rejected' | 'no_answer' | 'terminated'
failure_reasonstring nullable
started_atinteger nullable

Unix ms.

connected_atinteger nullable

Unix ms.

ended_atinteger nullable

Unix ms.

duration_secondsinteger nullable
created_atinteger
updated_atinteger

Example response

{
  "object": "whatsapp.call",
  "id": "wac_...",
  "user": "+919876543210"
}

Changes

No recorded changes to this operation across all 1 revision of this API.