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

# Inicio rápido

> Primera llamada de voz: origina, rastrea el estado y controla la sesión en tiempo real.

<Tip>
  De **cero a su primera llamada en cola** en unos pocos pasos. Primero: un número de espacio de trabajo **ACTIVE** y saldo o créditos (facturación por minuto).
</Tip>

## En resumen

* **Contrate un número ACTIVE**, es la línea de origen (`from`).
* **Origine** con `from`, `to` y qué decir cuando respondan (`speak`, audio o `gather`).
* **Seguimiento y control** vía API o webhooks (`voice.call.*`).

Contexto: [Introducción](/es/voice-api/como-funciona/introducao). Ámbitos: [Ámbitos de clave API](/es/voice-api/como-funciona/escopos-da-api-key). Número: [Números de teléfono](/es/phone-numbers-api/como-funciona/quick-start).

## Antes de empezar

* Número **ACTIVE** en el espacio de trabajo
* Clave con **`voice:call`** (y `voice:read` / `voice:control` según sea necesario)
* **Saldo o créditos** disponibles
* Autenticación: `Authorization: Bearer sk_live_...` o `x-api-key`
* URL base: `https://api.notifique.dev`
* Destinos en **E.164 con `+`** (por ejemplo, `+5511999887766`)

***

## 1. Originar una llamada

Dos caminos, elija el que mejor se adapte a su integración:

#### 1A, a través del panel

1. Voz → **Nueva llamada**
2. Seleccione los números de **origen** y **destino**
3. Configure el mensaje (TTS o audio) y envíe

#### 1B, a través de API

`to` es un **array** (hasta **100** destinos). Alcance: **`voice:call`**.

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

```json theme={null}
{
  "from": "+5511987654321",
  "to": ["+5511999887766"],
  "type": "speak",
  "payload": {
    "text": "¡Hola! Esta es una llamada de prueba de Notifique.",
    "voice": "female-natural"
  },
  "clientState": "campana-verificacion-42"
}
```

Respuesta esperada: **202**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "clvoice1...",
    "direction": "OUTBOUND",
    "fromE164": "+5511987654321",
    "toE164": "+5511999887766",
    "status": "QUEUED",
    "clientState": "campana-verificacion-42",
    "createdAt": "2025-02-15T10:00:00.000Z"
  }
}
```

Guarde el **`id`** de la llamada para consultar y controlar.

**Otras opciones del cuerpo** (cambie `type` y `payload`):

* **`type: "play"`**, reproducir audio por URL: `payload.audioUrl`
* **`type: "gather"`**, recoger DTMF: `payload.gather` con `prompt`, `maxDigits`, `timeoutSecs`
* **`type: "template"`**, plantilla del workspace: `payload.templateId` + `variables` opcionales
* **`record: true`**, graba la llamada
* **`machineDetection: "detect"`**, detecta buzón de voz

`from` acepta el **id** del número del espacio de trabajo o **E.164**; debe estar **ACTIVE**.

***

## 2. Listar y consultar

**Listar llamadas**

Filtro opcional: `direction` (`OUTBOUND` o `INBOUND`). Ámbito: **`voice:read`**.

**Consultar una llamada**

Con `includeEvents=true`, la respuesta incluye la línea de tiempo interna de la sesión.

***

## 3. Controlar llamada activa

Mientras la llamada está en curso, ejecute acciones en `POST /v1/voice/calls/:id/actions/{action}`. Ámbito: **`voice:control`**.

Ejemplo, pronunciar texto (TTS):

| Acción                         | Uso                        |
| ------------------------------ | -------------------------- |
| `speak`                        | Pronunciar texto (TTS)     |
| `play`                         | Reproducir audio desde URL |
| `gather`                       | Recoger DTMF               |
| `transfer`                     | Transferir a otro número   |
| `record-start` / `record-stop` | Grabar segmento            |
| `dtmf`                         | Enviar tonos               |
| `hangup`                       | Finalizar llamada          |

La sesión debe estar activa (llamada contestada y en curso).

***

## 4. Descargar grabación

Cuando la grabación esté lista:

Ámbito: **`voice:read`**. También recibe **`voice.call.recording.ready`** en el webhook.

***

## 5. Llamadas entrantes

1. Configure `inboundVoiceAction` en el número: [Números de teléfono](/es/phone-numbers-api/como-funciona/quick-start)
2. Con **`WEBHOOK_CONTROL`**, recibe **`voice.call.received`** y control vía API
3. Con **`FORWARD`**, reenvía a `forwardToE164`
4. Con **`TTS_HANGUP`**, pronuncia el texto configurado y cuelga

***

## 6. Webhooks (opcional)

Configure `voice.call.initiated`, `voice.call.answered`, `voice.call.dtmf`, `voice.call.completed`, etc.

Guía: [Eventos de webhook](/es/voice-api/como-funciona/eventos-do-webhooks).

***

## Voces TTS

| Identificador       | Idioma                         |
| ------------------- | ------------------------------ |
| `female-natural`    | Portugués (BR), predeterminado |
| `male-natural`      | Portugués (BR)                 |
| `female-natural-en` | Inglés (US)                    |
| `male-natural-en`   | Inglés (US)                    |

***

## Todos los tipos de envío

En la referencia de la API (pestaña Voz), abra **Originar llamada** y elija un ejemplo en el playground: Hablar, Reproducir, Recolectar, Plantilla, Grabación.

## Próximos pasos

* [Introducción](/es/voice-api/como-funciona/introducao): cuándo usar y ciclo de vida de la llamada
* [Ámbitos](/es/voice-api/como-funciona/escopos-da-api-key): permisos de clave
* [Eventos de webhook](/es/voice-api/como-funciona/eventos-do-webhooks): estado en tiempo real
* [Facturación](/es/guides/introducao/cobranca-e-pague-pelo-uso): costo por minuto