> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lacy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Place a WhatsApp call

> Place an outbound WhatsApp voice call after the customer has granted permission

Queues an outbound WhatsApp voice call. Your sender's assistant joins the call when the customer answers.

The customer **must** have granted call permission and that consent must still be valid. This endpoint will not call a number that never allowed calling.

> [!NOTE]
>
> Rate-limited to **5 requests per minute**, **15 per hour**, and **30 per day** per user. Also limited to **3 attempts per contact every 5 minutes** and **5 WhatsApp calls in progress** on the same sender.

### Request Body

**sender\_id** `integer` *required*

WhatsApp sender ID with calling enabled

**recipient\_phone** `string` *required*

Customer phone number in E.164 format

**variables** `object`

Optional variables passed to the assistant (max 20 keys, string values up to 500 characters). Use the same names you configured on the assistant.

### Response Fields

**success** `boolean`

The call was queued

**status** `string`

Always `queued` on success. The call is placed asynchronously.

**sender\_id** `integer`

Sender used for the call

**customer\_phone** `string`

Normalized E.164 phone number

### Error codes

| HTTP | `error_code` | Meaning |
| - | - | - |
| 402 | `INSUFFICIENT_BALANCE` | Account balance is too low |
| 403 | `ASSISTANT_BLOCKED` | Assistant is unavailable for compliance review |
| 404 | `SENDER_NOT_FOUND` | Sender missing or not yours |
| 422 | `INVALID_PHONE` | Phone is not valid E.164 |
| 422 | `VOICE_DISABLED` | Calling is not enabled |
| 422 | `NO_PERMISSION` | Customer has not granted (or consent expired) |
| 422 | `NO_ASSISTANT` | Sender has no assistant |
| 422 | `SENDER_OFFLINE` | Sender is not online |
| 422 | `REGION_NOT_SUPPORTED` | WhatsApp does not allow business-initiated calls from this sender's country |
| 422 | `FEATURE_DISABLED` | Calling is not available on this workspace |
| 429 | `CONCURRENT_LIMIT` | Too many WhatsApp calls already ringing on this sender |
| 429 | `CONTACT_RATE_LIMIT` | Too many attempts to this contact in the last 5 minutes |

```bash cURL theme={null}
curl -X POST "https://app.lacy.ai/api/user/whatsapp/voice/call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "recipient_phone": "+40711222333",
    "variables": {
      "customer_name": "Ana Pop"
    }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://app.lacy.ai/api/user/whatsapp/voice/call',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sender_id: 12,
      recipient_phone: '+40711222333',
      variables: { customer_name: 'Ana Pop' },
    }),
  }
);

console.log(await response.json());
```

```python Python theme={null}
import requests

response = requests.post(
    'https://app.lacy.ai/api/user/whatsapp/voice/call',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'sender_id': 12,
        'recipient_phone': '+40711222333',
        'variables': {'customer_name': 'Ana Pop'},
    },
)

print(response.json())
```

```json 200 Queued theme={null}
{
  "success": true,
  "status": "queued",
  "sender_id": 12,
  "customer_phone": "+40711222333"
}
```

```json 422 No permission theme={null}
{
  "success": false,
  "error": "This contact has not granted permission to receive WhatsApp calls. Send a call permission request first.",
  "error_code": "NO_PERMISSION"
}
```

### After you queue the call

* A `call_started` event is sent to the [WhatsApp voice webhook](https://docs.lacy.ai/api-reference/webhooks/whatsapp-voice-webhook.md) when the call is placed
* When the call finishes, the assistant's [post-call webhook](https://docs.lacy.ai/api-reference/webhooks/post-call-webhook.md) fires as usual (transcript, duration, extracted variables)
* The response does **not** include provider call IDs

Read [WhatsApp Calling](https://docs.lacy.ai/whatsapp/calling.md) before you automate this. Cold-calling new numbers is not possible.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.