# Campaigns

Call a list of numbers with your WebSocket agent, then follow every result live.

A campaign calls a list of numbers for you. Each answered call is connected to your agent's WebSocket, the same way as a call you [place with the Call API](/docs/call-api/websocket). You follow the results live in **Campaigns**, and finished campaigns stay in **History**.

```text
Create  ->  Add numbers  ->  Play  ->  calls go out  ->  History
                              ^  |
                       Resume |  | Pause
                              |  v
                             Paused
```

## Before you start

- A live number on your account to call from. See [Numbers](/docs/console/numbers).
- An agent that accepts calls on a `wss://` WebSocket. See [WebSocket protocol](/docs/call-api/websocket).
- Credits in your [wallet](/docs/console/wallet). Every campaign call is a normal call, billed as usual.

<Callout type="warn" title="Test a new agent with one number">
  Vonyx connects your agent only after the person answers. If the agent can't be reached, the call is cut after about 25 seconds, shows as **Answered**, and is billed. Run a one-number campaign to your own phone before a large one.
</Callout>

## Agents

An agent is your WebSocket agent saved once, so every campaign can use it without typing its settings again. Open **Campaigns → Agents** and choose **New agent**.

| Setting | What to enter |
| --- | --- |
| Name | Any name, up to 80 characters. Each of your agents needs its own name. |
| Type | **Your WebSocket agent** (your server speaks the [Vonyx protocol](/docs/call-api/websocket)) or **ElevenLabs agent**. |
| WebSocket URL | Your agent's URL, starting with `wss://`. For ElevenLabs, the agent's conversation URL (a signed URL if the agent is private). |
| Noise cancellation | Cleans the caller's audio before it reaches your agent. |
| Status webhook (optional) | An `https://` URL that receives each call's [status events](/docs/call-api/status-webhooks). |

A campaign keeps its own copy of the agent's settings from the moment it is created. Editing or deleting an agent changes only campaigns created after that. **Start a campaign** on an agent's card opens a new campaign with that agent picked.

## 1. Create the campaign

Open **Campaigns** and choose **New campaign**.

| Setting | What to enter |
| --- | --- |
| Campaign name | Any name, up to 200 characters. It need not be unique. |
| Call from | One of your live numbers. It is the number people see. |
| Agent | One of your [agents](#agents), or **New agent** to add one here. A new agent is saved to your agents when the campaign is created. |
| Calls at the same time | How many numbers are called at once. See [Calls at the same time](#calls-at-the-same-time). |

A campaign's settings can't be changed once it is created. To change one, delete the campaign and create it again.

## 2. Add numbers

Drop a CSV or text file, or paste the numbers. The console picks the phone numbers out of any column, removes repeats, and shows what it will upload before it sends anything.

- **India only.** These formats are accepted, and all are saved as 10 digits: `9876543210`, `+919876543210`, `919876543210`, `00919876543210`, `09876543210`.
- Anything else is refused, including a number with spaces inside it.
- Numbers are called **in the order you upload them**.
- A number already in the campaign is skipped, so uploading the same file twice is safe.
- You can add numbers only while the campaign is a **Draft**, before it first starts.

## 3. Play, pause and delete

| Campaign is | Add numbers | Play | Pause | Delete |
| --- | --- | --- | --- | --- |
| **Draft** | Yes | Yes | No | Yes. Removed, nothing is saved |
| **Calling** | No | Already running | Yes | No. Pause first |
| **Paused** | No | Yes. Resumes from the next number | Already paused | Yes. Saved to History as deleted |
| **Finishing** | No | No | No | No |
| **Deleting** | No | No | No | Already deleting |

- **Pause** stops new calls. Calls already in progress are never cut. The campaign stays paused until you press Resume or Delete.
- **Delete** on a paused campaign lets live calls finish, then saves it to History. Numbers not called yet are marked **Not called**. A delete can't be undone.
- When every number is done, the campaign shows **Finishing** for a few seconds and then moves to History by itself.

## Results for each number

| Result | Meaning |
| --- | --- |
| Waiting | Not called yet. |
| In call | Being placed, ringing or talking. |
| Answered | The call connected. Talk time is shown next to it. |
| Not answered | Nobody took the call: no answer, busy or cancelled. |
| Failed | The call failed. The reason is shown under the number. |
| No result | The call was placed but its result never arrived (no hang-up, or ringing for over 6 hours). |
| Not called | The campaign was deleted before this number was called. Shown in History only. |

The answer rate is answered numbers out of the numbers that were rung.

## When a campaign pauses itself

If a call is refused for a reason a person has to fix, Vonyx pauses the campaign and shows why on it. The refused number keeps its place, so nobody is skipped.

| The console says | What to do |
| --- | --- |
| The caller number isn't a live number on your account | Delete the campaign and create it again with one of your live numbers. |
| Your wallet is below zero | Top up, then press Resume. A new balance can take up to 5 minutes to count. |
| Your account has no call limits set yet | Contact support to have them set, then press Resume. |
| The caller number isn't fully set up yet | Finish the number's setup, then press Resume. |
| A temporary problem on our side | Press Resume again in a moment. |
| The call couldn't be started | Fix the cause shown under it, then press Resume. |

## Calls at the same time

Your account has a fixed number of channels: calls that can be live at once. Settings shows it.

- A campaign can start only if its **calls at the same time**, plus those of your other campaigns that are calling, fit in your channels. Paused campaigns don't count.
- Direct Call API and SIP calls use the same channels. When none is free, a running campaign waits without showing a reason.
- Your campaigns also share your account's calls per second. At 1 per second, one call starts each second across all your running campaigns, taking turns.
- A campaign on a number in a [sub-account](/docs/console/sub-accounts) can also use only that sub-account's free channels. The console tells you the most a number can use when you create a campaign.

## History

A campaign moves to **History** about 5 seconds after its last call ends, or after you delete it. A small campaign can finish between two refreshes, so you may never see it in Finishing.

Open a finished campaign to see its settings, the result of every number, talk time, and the call recording where there is one.

## Good to know

- **A number can be rung twice.** If Vonyx can't confirm whether a call went out, it moves that number to the end of the list and may ring it again.
- **Wallet:** the balance is checked every 5 minutes, so calls can continue for up to 5 minutes after it falls below zero.
- **Billing:** each campaign call appears in [Call logs](/docs/console/call-logs) and is billed like any other call.
- **Status events:** with a status webhook, each call's events are sent as described in [Status webhooks](/docs/call-api/status-webhooks).
