> ## 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.

# Request call permission

> Send a WhatsApp Voice Call Request (Ask to call) to a customer

Sends the sender's approved Voice Call Request template so the customer can Allow or Decline WhatsApp calls.

This endpoint will **not** send the request if the 24-hour chat window is closed. That protects your WhatsApp quota: a request sent to a brand-new number is not delivered, but still counts as your one ask for the day.

> [!NOTE]
>
> Rate-limited to **5 requests per minute**, **20 per hour**, and **50 per day** per user. WhatsApp typically allows **1 ask per contact every 24 hours** and **2 per week**. Those WhatsApp counters reset after a connected call.

### Request Body

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

WhatsApp sender ID. Calling must already be enabled on this sender.

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

Customer phone number in E.164 format

**recipient\_name** `string`

Optional display name for the conversation (max 255 characters)

**template\_id** `integer`

Optional Voice Call Request template ID. If omitted, the sender's approved voice-call template is used.

### Response Fields

Same shape as [Get call permission](https://docs.lacy.ai/api-reference/whatsapp/get-call-permission.md), plus `success`.

### Error codes

| HTTP | `error_code` | Meaning |
| - | - | - |
| 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 on this sender |
| 422 | `TEMPLATE_NOT_FOUND` | No approved Voice Call Request template |
| 422 | `SESSION_CLOSED` | Customer has not messaged you in the last 24 hours |
| 422 | `REQUEST_LIMIT` | Already asked in the last 24 hours (and no connected call reset the counter), weekly cap reached, or they already granted |
| 422 | `REGION_NOT_SUPPORTED` | WhatsApp does not allow business-initiated calls from this sender's country (US, CA, EG, VN, NG, TR) |
| 422 | `SEND_FAILED` | WhatsApp rejected the send |
| 429 | — | API rate limit |

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

```javascript JavaScript theme={null}
const response = await fetch(
  'https://app.lacy.ai/api/user/whatsapp/voice/request',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sender_id: 12,
      recipient_phone: '+40711222333',
      recipient_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/request',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'sender_id': 12,
        'recipient_phone': '+40711222333',
        'recipient_name': 'Ana Pop',
    },
)

print(response.json())
```

```json 200 Success theme={null}
{
  "success": true,
  "sender_id": 12,
  "customer_phone": "+40711222333",
  "conversation_id": "9c2e1d4a-6b8f-4c11-9a0e-1f2d3c4b5a67",
  "status": "pending",
  "can_call": false,
  "can_request": false,
  "session_open": true,
  "expires_at": null,
  "requested_at": "2026-08-15T10:15:00+00:00"
}
```

```json 422 Session closed theme={null}
{
  "success": false,
  "error": "This contact has not messaged you in the last 24 hours. Send a regular template first and wait for their reply, then ask to call.",
  "error_code": "SESSION_CLOSED"
}
```

### Recommended flow

1. [Send a regular template](https://docs.lacy.ai/api-reference/whatsapp/send-template.md) if there is no open chat
2. Wait for the customer to reply (or poll [session status](https://docs.lacy.ai/api-reference/whatsapp/session-status.md))
3. Call this endpoint
4. Listen for `call_permission_granted` on the [voice webhook](https://docs.lacy.ai/api-reference/webhooks/whatsapp-voice-webhook.md)
5. [Place the call](https://docs.lacy.ai/api-reference/whatsapp/place-whatsapp-call.md)

See [WhatsApp Calling](https://docs.lacy.ai/whatsapp/calling.md) for the product rules behind these errors.


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