> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/calls/initiate-an-outgoing-whatsapp-call.md).

# Initiate an Outgoing WhatsApp Call

This method is designed to attract the recipient’s attention. No audio is transmitted: the call is automatically ended after the specified duration.

### Requirements

Before using this method, make sure that:

* The channel is authorized;
* Outgoing calls are enabled in [channel settings](/help-desk/account-and-whapi-channels/channel-settings-overview.md): `outgoing_calls_enabled: true`;

### Send an outgoing call

Use: `POST https://gate.whapi.cloud/calls/outgoing`

The request includes the authorization header: `Authorization: Bearer <CHANNEL_TOKEN>`

Example request:

```bash
curl -X POST "https://gate.whapi.cloud/calls/outgoing" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919984351847",
    "duration": 15
  }'
```

### Request body

```json
{
  "to": "919984351847",
  "duration": 15
}
```

#### Parameters

* `to` — required string. WhatsApp number in international format or a private chat ID.
* `duration` — optional integer from `0` to `30`. Defines when the call should be ended automatically after the WhatsApp server confirms the offer. Default value: `5`.

If `duration` is set to `0`, the call is ended immediately.

### Successful response

A successful request returns `200 OK`:

```json
{
  "call_id": "00208DBDC3A2F961BC5F8163C0951FE1",
  "status": "initiated",
  "duration": 15
}
```

`200 OK` means that WhatsApp accepted the call initiation signal. It does not guarantee that the recipient answered the call.

### Possible errors

| Status | Description                                                                |
| ------ | -------------------------------------------------------------------------- |
| `400`  | Invalid phone number, duration, or other request parameters.               |
| `401`  | The channel is not authorized.                                             |
| `402`  | Trial channel limit has been reached.                                      |
| `404`  | Contact or compatible device was not found.                                |
| `409`  | Another outgoing call is already being processed on this channel.          |
| `500`  | Internal service error.                                                    |
| `502`  | WhatsApp rejected the offer or a signaling error occurred.                 |
| `503`  | Outgoing calls are disabled, unavailable, or the channel is not ready yet. |

Example `503` response:

```json
{
  "error": {
    "code": 503,
    "message": "Outgoing calls MVP is disabled"
  }
}
```

Use the method to change the [channel settings](/help-desk/account-and-whapi-channels/channel-settings-overview.md) to enable the ability to initiate calls. Here's how to do it via the API:

```bash
curl --request PATCH \
     --url https://gate.whapi.cloud/settings \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "outgoing_calls_enabled": true
}
'
```