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

# Llamadas

> Llamar por WhatsApp, decir un aviso y colgar — desde el panel o la API, con la misma simplicidad de los otros canales.

<Tip>
  Una llamada WhatsApp en Notifique es el **aviso que hace sonar el teléfono**: marcas, dices lo necesario (código, recordatorio, confirmación) y cuelgas — sin montar IVR ni call center.
</Tip>

## En pocas palabras

* **Hoy:** conexión **no oficial** (número emparejado por QR). Marca → habla/reproduce audio → cuelga.
* **Pronto:** la misma API en la conexión **oficial** (Meta), manteniendo el mismo formato simple.
* Usa la **misma instancia** que ya usas para mensajes.
* Clave con alcance **`whatsapp:call`** (y `whatsapp:call:read` solo para consultar).

<Warning>
  En esta primera versión el flujo es **enviar y colgar**: no hay IVR, transferencia ni conversación en vivo. Sirve para **decir algo concreto** y terminar.
</Warning>

***

## Cuándo usar

| Situación                                   | ¿Usar llamadas?                         |
| ------------------------------------------- | --------------------------------------- |
| Código de verificación **hablado**          | **Sí**                                  |
| Recordatorio corto (cita, factura, entrega) | **Sí**                                  |
| Atención con conversación en vivo           | **No** — use mensajes o voz tradicional |
| Instancia **oficial** (Meta)                | Pronto; hoy use **no oficial**          |

Modos: [Modos de conexión](/es/whatsapp-api/como-funciona/modos-de-conexao).

***

## Qué puedes hacer

<CardGroup cols={2}>
  <Card title="Hacer la llamada" icon="phone">
    `POST /v1/whatsapp/calls` con `speak`, `play` o `template`.
  </Card>

  <Card title="Listar llamadas" icon="list">
    `GET /v1/whatsapp/calls` con paginación y filtro por instancia.
  </Card>

  <Card title="Consultar una llamada" icon="magnifying-glass">
    `GET /v1/whatsapp/calls/{id}` con estado, duración y eventos.
  </Card>

  <Card title="Template con voz" icon="file-audio">
    `type: "template"` usa el texto/voz del template del canal.
  </Card>

  <Card title="Webhooks de la llamada" icon="satellite-dish">
    `whatsapp.call.initiated`, `answered`, `completed`, `failed`… sin polling.
  </Card>
</CardGroup>

Rutas y campos: **referencia de la API** de WhatsApp (sección Llamadas). Eventos: [Webhooks WhatsApp](/es/whatsapp-api/como-funciona/eventos-do-webhooks#llamadas-whatsappcall).

***

## Antes de empezar

| Ítem                                    | Obligatorio |
| --------------------------------------- | ----------- |
| Instancia **no oficial** y **ACTIVE**   | Sí (hoy)    |
| Alcance **`whatsapp:call`** en la clave | Sí          |
| Texto (`speak`) o URL de audio (`play`) | Sí          |

¿Aún no emparejó? [Quick Start WhatsApp](/es/whatsapp-api/como-funciona/quick-start) (pestaña **no oficial**). Alcances: [Alcances de la API Key](/es/whatsapp-api/como-funciona/escopos-api-key).

Sustituya `sk_live_xxxxx` por su clave y `{instanceId}` por el id de la instancia. Base URL: `https://api.notifique.dev`.

<Info>
  La API Key pertenece a **un** workspace. En la v1 **no envíe** `x-workspace-id`.
</Info>

***

## 1. Hacer una llamada (hablar texto)

Marca, sintetiza la voz y cuelga automáticamente.

```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": "¡Hola! Su código de verificación es 1 2 3 4.",
    "voice": "female"
  }
}
```

**Respuesta `202`**

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

***

## 2. Reproducir un audio (`play`)

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

La URL debe ser **pública** y apuntar a un archivo de audio.

***

## 3. Template con voz

Si ya registró un template del canal de llamada (`whatsapp_call`), use `type: "template"`:

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

La API resuelve el texto (y la voz, si hay) y continúa como `speak`.

***

## 4. Listar llamadas

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

Parámetros opcionales: `page`, `limit`, `instanceId`.

***

## 5. Consultar una llamada

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

Con `includeEvents=true` ve la línea de tiempo (`QUEUED`, `INITIATED`, `COMPLETED`, `NO_ANSWER`, `FAILED`, …).

***

## Estado y cierre

Después de encolar, la llamada pasa por estados como `QUEUED` → `INITIATED` → `COMPLETED` (o `NO_ANSWER` / `FAILED` / `REJECTED`).

El campo `hangupReason` explica el fin (`completed`, `hangup`, `no_answer`, `provider_error`, …).

***

## Próximos pasos

* Ejemplos tipados en la OpenAPI (pestaña WhatsApp → **Llamadas**)
* [Modos de conexión](/es/whatsapp-api/como-funciona/modos-de-conexao)
* [Alcances de la API Key](/es/whatsapp-api/como-funciona/escopos-api-key)
* Para voz PSTN tradicional, vea la [API de Voz](/es/voice-api/como-funciona/quick-start)