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

# Calls

> Place a WhatsApp call, speak a short notice, and hang up — from the dashboard or API, with the same simplicity as other channels.

<Tip>
  A WhatsApp call in Notifique is the **notice that rings the phone**: you dial, say what you need (code, reminder, confirmation), and hang up — no IVR or call center to build.
</Tip>

## In short

* **Today:** **unofficial** connection (QR-paired number). Dial → speak/play audio → hang up.
* **Soon:** the same API on the **official** (Meta) connection, keeping the same simple shape.
* Use the **same instance** you already use for messages.
* API key scope **`whatsapp:call`** (and `whatsapp:call:read` for read-only).

<Warning>
  This first version is **send and hang up**: no IVR, transfer, or live conversation. It is meant to **say something specific** and end the call.
</Warning>

***

## When to use

| Situation                                       | Use calls?                                 |
| ----------------------------------------------- | ------------------------------------------ |
| Verification code **spoken** to the user        | **Yes**                                    |
| Short reminder (appointment, invoice, delivery) | **Yes**                                    |
| Live two-way support                            | **No** — use messages or traditional voice |
| **Official** (Meta) instance                    | Coming soon; today use **unofficial**      |

Modes: [Connection modes](/en/whatsapp-api/como-funciona/modos-de-conexao).

***

## What you can do

<CardGroup cols={2}>
  <Card title="Place the call" icon="phone">
    `POST /v1/whatsapp/calls` with `speak`, `play`, or `template`.
  </Card>

  <Card title="List calls" icon="list">
    `GET /v1/whatsapp/calls` with pagination and instance filter.
  </Card>

  <Card title="Get a call" icon="magnifying-glass">
    `GET /v1/whatsapp/calls/{id}` with status, duration, and events.
  </Card>

  <Card title="Template with voice" icon="file-audio">
    `type: "template"` uses the channel template text/voice.
  </Card>

  <Card title="Call webhooks" icon="satellite-dish">
    `whatsapp.call.initiated`, `answered`, `completed`, `failed`… no polling.
  </Card>
</CardGroup>

Routes and fields: WhatsApp **API reference** (Calls section). Events: [WhatsApp webhooks](/en/whatsapp-api/como-funciona/eventos-do-webhooks#calls-whatsappcall).

***

## Before you start

| Item                                 | Required    |
| ------------------------------------ | ----------- |
| **Unofficial** instance, **ACTIVE**  | Yes (today) |
| Scope **`whatsapp:call`** on the key | Yes         |
| Text (`speak`) or audio URL (`play`) | Yes         |

Not paired yet? [WhatsApp Quick Start](/en/whatsapp-api/como-funciona/quick-start) (**unofficial** tab). Scopes: [API Key scopes](/en/whatsapp-api/como-funciona/escopos-api-key).

Replace `sk_live_xxxxx` with your key and `{instanceId}` with the instance id. Base URL: `https://api.notifique.dev`.

<Info>
  The API Key belongs to **one** workspace. On v1 **do not send** `x-workspace-id`.
</Info>

***

## 1. Place a call (speak text)

Dials, synthesizes speech, and hangs up automatically.

```http theme={null}
POST /v1/whatsapp/calls
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json
```

```json theme={null}
{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "speak",
  "payload": {
    "text": "Hi! Your verification code is 1 2 3 4.",
    "voice": "female"
  }
}
```

**`202` response**

```json theme={null}
{
  "success": true,
  "data": {
    "messageIds": ["clxx_call..."],
    "messageId": "clxx_call...",
    "status": "QUEUED",
    "count": 1,
  }
}
```

***

## 2. Play audio (`play`)

```json theme={null}
{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "play",
  "payload": {
    "mediaUrl": "https://example.com/notice.mp3"
  }
}
```

The URL must be **public** and point to an audio file.

***

## 3. Template with voice

If you already created a call-channel template (`whatsapp_call`), use `type: "template"`:

```json theme={null}
{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "clxx_template...",
    "variables": {
      "1": "1234",
      "name": "Ana"
    }
  }
}
```

The API resolves text (and voice, if set) and continues as `speak`.

***

## 4. List calls

```http theme={null}
GET /v1/whatsapp/calls?page=1&limit=20&instanceId=clxx...
Authorization: Bearer sk_live_xxxxx
```

Optional params: `page`, `limit`, `instanceId`.

***

## 5. Get a call

```http theme={null}
GET /v1/whatsapp/calls/{id}?includeEvents=true
Authorization: Bearer sk_live_xxxxx
```

With `includeEvents=true` you get the timeline (`QUEUED`, `INITIATED`, `COMPLETED`, `NO_ANSWER`, `FAILED`, …).

***

## Status and hangup

After queueing, the call moves through statuses like `QUEUED` → `INITIATED` → `COMPLETED` (or `NO_ANSWER` / `FAILED` / `REJECTED`).

`hangupReason` explains the end (`completed`, `hangup`, `no_answer`, `provider_error`, …).

***

## Next steps

* Typed examples in OpenAPI (WhatsApp tab → **Calls**)
* [Connection modes](/en/whatsapp-api/como-funciona/modos-de-conexao)
* [API Key scopes](/en/whatsapp-api/como-funciona/escopos-api-key)
* For traditional PSTN voice, see the [Voice API](/en/voice-api/como-funciona/quick-start)