---
title: "Place a WhatsApp call"
method: POST
path: "/v1/whatsapp/calls"
tags: ["WhatsApp"]
---

# Place a WhatsApp call

`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`

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.

## Headers

- `Idempotency-Key` string, required

## Request body

- WhatsAppCallCreateRequest
  - `number_id` string, required
  - `to` string, required: The user's WhatsApp number (E.164).
  - `agent_id` string, nullable: Defaults to the number's agent.

## Response `201`

Call placed (ringing)

- WhatsAppCall
  - `object` string
  - `id` string
  - `number_id` string
  - `wa_call_id` string, nullable: Meta's call id (wacid...).
  - `direction` 'inbound' | 'outbound'
  - `user` string
  - `agent_id` string, nullable
  - `status` 'ringing' | 'accepted' | 'connected' | 'completed' | 'failed' | 'rejected' | 'no_answer' | 'terminated'
  - `failure_reason` string, nullable
  - `started_at` integer, nullable: Unix ms.
  - `connected_at` integer, nullable: Unix ms.
  - `ended_at` integer, nullable: Unix ms.
  - `duration_seconds` integer, nullable
  - `created_at` integer
  - `updated_at` integer

## Other responses

- `400`: Invalid request (bad field, unsupported value)
- `401`: Missing or invalid API key (`code: unauthorized`)
- `403`: No live call permission from the user (`code: call_permission_required`).
- `404`: Resource not found (`code: not_found`)
- `409`: Calling is disabled on the number (`code: calling_disabled`) or the Idempotency-Key was reused with different input.
- `502`: Meta refused the call or the media edge was unavailable.

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)