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

# Voz

> Administra el servicio de voz completo desde el CLI: llamadas, números, agentes, contactos, campañas de llamadas, facturación, reportes y webhooks.

`jelou voice` cubre todo el servicio de voz de tu organización: **llamadas**
(consulta, grabaciones, estadísticas), **números telefónicos**, **agentes de
voz** (ElevenLabs y otros proveedores), **contactos** y **listas de
contactos**, **campañas de llamadas** (schedules), **facturación**,
**reportes de campaña** y **webhooks** de eventos.

<Note>
  Todo lo que marca o cuesta dinero pide confirmación antes de ejecutarse:
  activar una campaña, una llamada de prueba, una llamada saliente y cualquier
  `delete`. Usa `--yes` en CI o scripts no interactivos.
</Note>

## Llamadas

```bash theme={null}
jelou voice calls list                       # últimos 30 días (default)
jelou voice calls list --start-date 2026-07-01 --end-date 2026-07-17
jelou voice calls list --direction inbound --status completed
```

| Flag                        | Descripción                                     |
| --------------------------- | ----------------------------------------------- |
| `--start-date <YYYY-MM-DD>` | Inicio del rango                                |
| `--end-date <YYYY-MM-DD>`   | Fin del rango                                   |
| `--page <n>`                | Página (default: 1)                             |
| `--limit <n>`               | Resultados por página (default: 20)             |
| `--provider <nombre>`       | Filtra por proveedor (por ejemplo `elevenlabs`) |
| `--direction <dir>`         | `inbound` o `outbound`                          |
| `--status <estado>`         | Filtra por estado de la llamada                 |

El resultado está paginado: sin `--start-date` y `--end-date` obtienes los
últimos 30 días.

### Ver una llamada

```bash theme={null}
jelou voice calls get call_01h2xcejq
```

### Descargar la grabación

```bash theme={null}
jelou voice calls recording call_01h2xcejq --out llamada.mp3
```

Sin `--out` el archivo se guarda con un nombre por defecto en el directorio
actual.

### Estadísticas, exportación y agentes

```bash theme={null}
# Resumen agregado del rango (default: últimos 30 días)
jelou voice calls stats --start-date 2026-07-01 --end-date 2026-07-31

# Exportar a CSV o XLSX (--format csv|xlsx, default: csv)
jelou voice calls export --start-date 2026-07-01 --end-date 2026-07-31 --out llamadas.csv
jelou voice calls export --start-date 2026-07-01 --end-date 2026-07-31 --format xlsx --out llamadas.xlsx

# Una métrica puntual por nombre (catálogo v2)
jelou voice calls metrics <nombre-metrica> --start-date 2026-07-01

# Agentes que han atendido llamadas
jelou voice calls agents
```

### Llamada saliente puntual

```bash theme={null}
jelou voice calls outbound --phone +593999999999 --agent-id ag_1
jelou voice calls outbound --phone +593999999999 --agent-id ag_1 --phone-number-id num_1 --pbx sip-trunk
```

<Warning>
  `jelou voice calls outbound` marca un número real de inmediato y factura la
  cuenta. Pide confirmación salvo que pases `--yes`.
</Warning>

## Números telefónicos

```bash theme={null}
jelou voice numbers list                     # los de tu organización (ElevenLabs por defecto)
jelou voice numbers list --provider <nombre> # otro proveedor
jelou voice numbers list --all               # todos los números del proveedor
```

| Flag                  | Descripción                                                           |
| --------------------- | --------------------------------------------------------------------- |
| `--provider <nombre>` | Proveedor a consultar (default: `elevenlabs`)                         |
| `--all`               | Lista todos los números del proveedor, no solo los de tu organización |

## Agentes de voz

Un agente de voz es quien "habla" en la llamada: define el prompt, la voz, el
idioma, el límite de duración y su base de conocimiento.

```bash theme={null}
jelou voice agents list
jelou voice agents list --all                # todos los agentes del proveedor
jelou voice agents get ag_1
jelou voice agents voices                     # voces disponibles para asignar
```

### Crear y ajustar un agente

```bash theme={null}
jelou voice agents create \
  --name "Agente de cobranza" \
  --language es \
  --voice-id voice_abc123 \
  --system-prompt "Eres un agente de cobranza amable y directo." \
  --first-message "Hola, te llamo de parte de..."

jelou voice agents update ag_1 \
  --system-prompt "Prompt actualizado" \
  --max-duration-seconds 300
```

| Flag (`create`/`update`)     | Descripción                                           |
| ---------------------------- | ----------------------------------------------------- |
| `--name`                     | Nombre del agente (solo `create`)                     |
| `--language <código>`        | Idioma, por ejemplo `es`                              |
| `--voice-id <id>`            | Voz a usar (`jelou voice agents voices`)              |
| `--system-prompt`            | Prompt del sistema                                    |
| `--first-message`            | Frase de apertura                                     |
| `--max-duration-seconds <n>` | Límite duro de duración de la llamada (solo `update`) |

```bash theme={null}
jelou voice agents assign ag_1                # asigna el agente a la organización activa
jelou voice agents delete ag_1 --yes
```

### Base de conocimiento del agente

```bash theme={null}
jelou voice agents knowledge list ag_1
jelou voice agents knowledge upload ag_1 ./manual-producto.pdf
jelou voice agents knowledge url ag_1 https://ejemplo.com/faq --name "FAQ pública"
jelou voice agents knowledge delete ag_1 doc_1 --yes
```

<Warning>
  `jelou voice agents delete` es irreversible.
</Warning>

## Contactos y listas de contactos

Los contactos son las personas que una campaña puede llamar. Las listas
agrupan contactos y son el objetivo (`--contact-list-id`) de una campaña.

```bash theme={null}
jelou voice contacts list
jelou voice contacts get cnt_1
```

### Crear y actualizar contactos

```bash theme={null}
jelou voice contacts create \
  --first-name Ana --last-name Torres \
  --phone +593999999999 --email ana@ejemplo.com \
  --company Acme --position Gerente --notes "Cliente VIP"

jelou voice contacts update cnt_1 --phone +593988888888
jelou voice contacts delete cnt_1 --yes
```

Todos los campos de `create` (`--first-name`, `--last-name`, `--phone`,
`--email`, `--company`, `--position`, `--notes`) también existen en `update`
como overrides parciales. El teléfono va en formato E.164.

### Listas de contactos

```bash theme={null}
jelou voice contacts lists list
jelou voice contacts lists get list_1

# Crear desde ids existentes
jelou voice contacts lists create --name "Cartera vencida" \
  --contact-id cnt_1 --contact-id cnt_2

# Crear desde un archivo CSV/XLSX
jelou voice contacts lists upload ./contactos.csv --name "Campaña julio"

jelou voice contacts lists update list_1 --name "Nuevo nombre" --description "Actualizada"
jelou voice contacts lists add list_1 cnt_3
jelou voice contacts lists remove list_1 cnt_3
jelou voice contacts lists delete list_1 --yes
```

`--contact-id` en `lists create` es repetible. `lists upload` es la forma más
rápida de armar una lista grande: solo necesitas un CSV o XLSX con los
contactos.

## Campañas de llamadas (`jelou voice schedules`)

Una campaña ("schedule") llama a toda una lista de contactos con un agente y
un número de origen determinados.

```bash theme={null}
jelou voice schedules list
jelou voice schedules get sch_1
jelou voice schedules stats                   # estadísticas de campañas en toda la organización
jelou voice schedules progress sch_1          # avance de marcado de una campaña
jelou voice schedules calls sch_1             # llamadas hechas por una campaña
jelou voice schedules calls sch_1 --status completed
```

### Crear y activar una campaña

```bash theme={null}
jelou voice schedules create \
  --name "Cobranza julio" \
  --contact-list-id list_1 \
  --agent-id ag_1 \
  --from-number +593222222222 \
  --scheduled-at "2026-07-20T09:00:00-05:00" \
  --max-retries 2

jelou voice schedules activate sch_1 --agent-id ag_1 \
  --retry-on-no-answer --max-retries 2 --retry-delay-minutes 30
```

| Flag                        | En `create` | En `activate` |
| --------------------------- | :---------: | :-----------: |
| `--name`                    |      ✓      |       —       |
| `--contact-list-id`         |      ✓      |       —       |
| `--agent-id`                |      ✓      |  ✓ (override) |
| `--from-number` (repetible) |      ✓      |  ✓ (override) |
| `--scheduled-at <iso>`      |      ✓      |  ✓ (override) |
| `--max-retries <n>`         |      ✓      |  ✓ (override) |
| `--retry-delay-minutes <n>` |      —      |       ✓       |
| `--retry-on-no-answer`      |      —      |       ✓       |
| `--yes`                     |      —      |       ✓       |

`create` deja la campaña lista pero inactiva; `activate` es lo que empieza a
marcar. Los flags de `activate` sirven para pisar lo definido en `create` sin
tener que recrear la campaña.

<Note>
  `--name` es el único flag que exige el CLI en `create`; el resto lo valida la
  API al enviar el payload. En la práctica, `--agent-id`, `--from-number` y
  `--scheduled-at` son obligatorios — sin ellos la API responde 400 con
  `fromNumbers/agentId/scheduledAt should not be empty`.
</Note>

### Probar antes de activar

```bash theme={null}
jelou voice schedules test-call sch_1 --contact-id cnt_1 --agent-id ag_1
```

<Warning>
  `jelou voice schedules activate` empieza a marcar llamadas reales de inmediato
  y factura la cuenta — confirma el conteo de contactos antes de activar.
  `test-call` también marca un número real, aunque sea uno solo. Ambos piden
  confirmación salvo `--yes`.
</Warning>

### Controlar una campaña en curso

```bash theme={null}
jelou voice schedules pause sch_1
jelou voice schedules resume sch_1
jelou voice schedules cancel sch_1            # las llamadas en cola se descartan
jelou voice schedules delete sch_1 --yes
```

<Warning>
  `cancel` descarta las llamadas que seguían en cola sin completarse — no es
  reversible. `delete` solo debería usarse sobre campañas que ya terminaron o se
  cancelaron.
</Warning>

## Facturación

```bash theme={null}
jelou voice billing summary --start-date 2026-07-01 --end-date 2026-07-31
jelou voice billing details --start-date 2026-07-01 --end-date 2026-07-31 \
  --direction outbound --channel sip-trunk
```

| Flag                          | Descripción                                     |
| ----------------------------- | ----------------------------------------------- |
| `--start-date` / `--end-date` | Rango de fechas                                 |
| `--organization-id`           | Limita a una organización puntual               |
| `--direction`                 | `inbound` o `outbound`                          |
| `--channel`                   | Canal de facturación (`sip-trunk`, `twilio`, …) |
| `--page` / `--limit`          | Paginación (solo `details`)                     |

`summary` da el total facturado del rango; `details` lo desglosa línea por
línea.

## Reportes de campaña

```bash theme={null}
jelou voice reports list
jelou voice reports get rep_1
jelou voice reports export rep_1 --out reporte-julio.xlsx
```

Sin `--out`, `export` guarda el archivo con un nombre por defecto en el
directorio actual.

## Webhooks

```bash theme={null}
jelou voice webhooks list
jelou voice webhooks get wh_1
jelou voice webhooks create --url https://mi-servidor.com/eventos-voz --type call.completed
jelou voice webhooks delete wh_1 --yes
```

## Estado del servicio

Verifica que el servicio de voz responda para el perfil activo:

```bash theme={null}
jelou voice status
```

<Tip>
  Si un comando de voz falla, corre `jelou voice status` antes de investigar más:
  distingue un problema del servicio de un problema de tus credenciales o filtros.
</Tip>