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

# Voice

> Manage the whole voice service from the CLI: calls, numbers, agents, contacts, call campaigns, billing, reports, and webhooks.

`jelou voice` covers your organization's whole voice service: **calls**
(lookup, recordings, stats), **phone numbers**, **voice agents** (ElevenLabs
and other providers), **contacts** and **contact lists**, **call campaigns**
(schedules), **billing**, **campaign reports**, and event **webhooks**.

<Note>
  Anything that dials a real number or spends money asks for confirmation
  first: activating a campaign, a test call, an outbound call, and every
  `delete`. Pass `--yes` in CI or non-interactive scripts.
</Note>

## Calls

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

| Flag                        | Description                                   |
| --------------------------- | --------------------------------------------- |
| `--start-date <YYYY-MM-DD>` | Range start                                   |
| `--end-date <YYYY-MM-DD>`   | Range end                                     |
| `--page <n>`                | Page (default: 1)                             |
| `--limit <n>`               | Results per page (default: 20)                |
| `--provider <name>`         | Filter by provider (for example `elevenlabs`) |
| `--direction <dir>`         | `inbound` or `outbound`                       |
| `--status <status>`         | Filter by call status                         |

Results are paginated: without `--start-date` and `--end-date` you get the last
30 days.

### Show one call

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

### Download the recording

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

Without `--out` the file is saved with a default name in the current directory.

### Stats, export and agents

```bash theme={null}
# Aggregate summary for the range (default: last 30 days)
jelou voice calls stats --start-date 2026-07-01 --end-date 2026-07-31

# Export to CSV or XLSX (--format csv|xlsx, default: csv)
jelou voice calls export --start-date 2026-07-01 --end-date 2026-07-31 --out calls.csv
jelou voice calls export --start-date 2026-07-01 --end-date 2026-07-31 --format xlsx --out calls.xlsx

# A single metric by name (v2 catalog)
jelou voice calls metrics <metric-name> --start-date 2026-07-01

# Agents that have handled calls
jelou voice calls agents
```

### Single outbound call

```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` dials a real number immediately and bills the
  account. It asks for confirmation unless you pass `--yes`.
</Warning>

## Phone numbers

```bash theme={null}
jelou voice numbers list                     # your organization's (ElevenLabs by default)
jelou voice numbers list --provider <name>   # another provider
jelou voice numbers list --all               # every number on the provider
```

| Flag                | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `--provider <name>` | Provider to query (default: `elevenlabs`)                       |
| `--all`             | List every number on the provider, not just your organization's |

## Voice agents

A voice agent is who "speaks" on the call: its prompt, voice, language, hard
duration cap, and knowledge base.

```bash theme={null}
jelou voice agents list
jelou voice agents list --all                # every agent on the provider
jelou voice agents get ag_1
jelou voice agents voices                     # voices available to assign
```

### Create and tune an agent

```bash theme={null}
jelou voice agents create \
  --name "Collections agent" \
  --language es \
  --voice-id voice_abc123 \
  --system-prompt "You are a friendly, direct collections agent." \
  --first-message "Hi, I'm calling on behalf of..."

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

| Flag (`create`/`update`)     | Description                                |
| ---------------------------- | ------------------------------------------ |
| `--name`                     | Agent name (`create` only)                 |
| `--language <code>`          | Language, e.g. `es`                        |
| `--voice-id <id>`            | Voice to use (`jelou voice agents voices`) |
| `--system-prompt`            | System prompt                              |
| `--first-message`            | Opening line                               |
| `--max-duration-seconds <n>` | Hard call-length cap (`update` only)       |

```bash theme={null}
jelou voice agents assign ag_1                # assigns the agent to the active organization
jelou voice agents delete ag_1 --yes
```

### Agent knowledge base

```bash theme={null}
jelou voice agents knowledge list ag_1
jelou voice agents knowledge upload ag_1 ./product-manual.pdf
jelou voice agents knowledge url ag_1 https://example.com/faq --name "Public FAQ"
jelou voice agents knowledge delete ag_1 doc_1 --yes
```

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

## Contacts and contact lists

Contacts are the people a campaign can call. Contact lists group contacts and
are a campaign's call target (`--contact-list-id`).

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

### Create and update contacts

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

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

Every `create` field (`--first-name`, `--last-name`, `--phone`, `--email`,
`--company`, `--position`, `--notes`) also exists on `update` as a partial
override. Phone numbers use E.164 format.

### Contact lists

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

# Create from existing contact ids
jelou voice contacts lists create --name "Overdue accounts" \
  --contact-id cnt_1 --contact-id cnt_2

# Create from a CSV/XLSX file
jelou voice contacts lists upload ./contacts.csv --name "July campaign"

jelou voice contacts lists update list_1 --name "New name" --description "Updated"
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` on `lists create` is repeatable. `lists upload` is the fastest
way to build a large list — you just need a CSV or XLSX with the contacts.

## Call campaigns (`jelou voice schedules`)

A campaign ("schedule") calls a whole contact list with a given agent and
caller number.

```bash theme={null}
jelou voice schedules list
jelou voice schedules get sch_1
jelou voice schedules stats                   # campaign stats across the organization
jelou voice schedules progress sch_1          # a campaign's dialling progress
jelou voice schedules calls sch_1             # calls a campaign has placed
jelou voice schedules calls sch_1 --status completed
```

### Create and activate a campaign

```bash theme={null}
jelou voice schedules create \
  --name "July collections" \
  --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                         | On `create` | On `activate` |
| ---------------------------- | :---------: | :-----------: |
| `--name`                     |      ✓      |       —       |
| `--contact-list-id`          |      ✓      |       —       |
| `--agent-id`                 |      ✓      |  ✓ (override) |
| `--from-number` (repeatable) |      ✓      |  ✓ (override) |
| `--scheduled-at <iso>`       |      ✓      |  ✓ (override) |
| `--max-retries <n>`          |      ✓      |  ✓ (override) |
| `--retry-delay-minutes <n>`  |      —      |       ✓       |
| `--retry-on-no-answer`       |      —      |       ✓       |
| `--yes`                      |      —      |       ✓       |

`create` leaves the campaign ready but inactive; `activate` is what starts
dialling. The `activate` flags let you override what `create` set without
recreating the campaign.

<Note>
  `--name` is the only flag the CLI itself requires on `create`; the API
  validates the rest once you submit the payload. In practice `--agent-id`,
  `--from-number`, and `--scheduled-at` are mandatory — without them the API
  returns a 400 with `fromNumbers/agentId/scheduledAt should not be empty`.
</Note>

### Test before activating

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

<Warning>
  `jelou voice schedules activate` starts placing real calls immediately and
  bills the account — confirm the contact count before activating. `test-call`
  also dials a real number, even if it's only one. Both ask for confirmation
  unless you pass `--yes`.
</Warning>

### Control a running campaign

```bash theme={null}
jelou voice schedules pause sch_1
jelou voice schedules resume sch_1
jelou voice schedules cancel sch_1            # queued calls are dropped
jelou voice schedules delete sch_1 --yes
```

<Warning>
  `cancel` drops calls still queued and not yet completed — it isn't reversible.
  Only `delete` a campaign that has already finished or been cancelled.
</Warning>

## Billing

```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                          | Description                                |
| ----------------------------- | ------------------------------------------ |
| `--start-date` / `--end-date` | Date range                                 |
| `--organization-id`           | Scope to one organization                  |
| `--direction`                 | `inbound` or `outbound`                    |
| `--channel`                   | Billing channel (`sip-trunk`, `twilio`, …) |
| `--page` / `--limit`          | Pagination (`details` only)                |

`summary` gives the range's total billed usage; `details` breaks it down line
by line.

## Campaign reports

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

Without `--out`, `export` saves the file with a default name in the current
directory.

## Webhooks

```bash theme={null}
jelou voice webhooks list
jelou voice webhooks get wh_1
jelou voice webhooks create --url https://my-server.com/voice-events --type call.completed
jelou voice webhooks delete wh_1 --yes
```

## Service status

Check that the voice service responds for the active profile:

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

<Tip>
  If a voice command fails, run `jelou voice status` before digging further: it
  separates a service problem from a problem with your credentials or filters.
</Tip>