> This page is for Voice Agents.

> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> Building a voice agent for customers in India? Start with Sarvam Voice Agents, a managed platform with Indian-language speech, telephony, testing, and analytics from ₹3 per minute: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Create a campaign

> Create an outbound campaign in Sarvam Voice Agents: pick the agent and numbers, map CSV columns, set schedule and retries, test dial, and launch.

From **Deploy → Campaigns**, click **Create Campaign** to open the **Schedule campaign** wizard. It has four steps — **Agent**, **Recipients**, **Schedule**, and **Review & Launch** — shown as tabs across the top, with a **Step X of 4** counter at the bottom. Move forward with **Next** and back with **Back**; your progress is kept as you move between steps.

> **Note**
>
> Closing the wizard before you launch prompts **Discard campaign?** — all progress is lost and the action can't be undone. Choose **Keep editing** to return, or **Discard** to abandon it.

> **Note**
>
> By default you can have **10 concurrent agent campaigns**. Concurrent means campaigns that are **Active** or **Scheduled**. The limit is checked when you **create** an agent campaign and when you **pause** an agent campaign. [Contact the Sarvam team](https://www.sarvam.ai/contact-us) if you need a higher limit.

#### Agent

Choose what runs the campaign and where it dials from:

* **Campaign name** — a clear name for the campaign.
* **Select agent** — the agent, plus the committed **Version** to run.
* **Connections** — pick a telephony **Connection**, then the **Phone numbers** to dial from. Toggle **By number** to choose individual numbers, or **By group** to use a whole [group](/voice-agents/deploy/telephony/groups).

Click **Next** to continue.

#### Recipients

Upload your contact list (cohort) and map its columns to the agent's variables.

* **Upload cohort** — drop in a CSV. Each row must include a phone number plus any details your agent uses during the call. Use **Download Sample** if you need the expected format.
* **Cohort name** — a name for this batch of contacts. (A [cohort](/voice-agents/deploy/campaigns/cohorts) is the batch you upload; every campaign starts with one and you can add more later.)
* **Map phone number and agent variables to columns** — match each agent field to a CSV column. **Preview sample row** shows the mapped values for one row; use **Random** / **Pick random row** to spot-check different rows.

The mapping table has a row per field:

| Column                   | What it does                                                                                              |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Field**                | The agent variable to fill (for example `Phone Number`, `developer_name`, `gender`).                      |
| **CSV column**           | The column from your file to pull the value from — search the list, or set **None** to leave it unmapped. |
| **Required**             | Marks the field as mandatory. **Phone Number** is always required.                                        |
| **Formatting functions** | An optional transform applied to the raw CSV value before the call (see below).                           |
| **Preview**              | The resulting value for the previewed row.                                                                |

#### Formatting functions

Add a transform under **Formatting functions → Add** to clean or reshape a column before it reaches the agent:

* **Indian Currency** — format a number as Indian currency.
* **Date** — normalize a date value.
* **String Replace** — find and replace within the text.
* **String Strip** — trim surrounding whitespace.
* **String Capitalize** — capitalize the value.
* **Indian State Language Map** — map an Indian state to its language.
* **Format Language Name** — normalize a language name.

#### Override default values

Expand **Override default values** to map CSV columns onto per-contact conversation defaults — **Initial message**, **Initial state**, and **Initial language**. Left as **None**, each call uses the agent's configured default; map a column to personalize it per contact.

Click **Validate** to check the file and mapping before continuing. Validation reports how many rows are **valid** versus **removed**.

#### Schedule

Set when the campaign runs and how it retries:

* **Campaign period** — **Start date time** (**Now**, or a **Custom** date and time) and **End date time** (**Today**, or **Custom**). Starting **Now** kicks off roughly two minutes after scheduling.
* **Attempts per second** — the dialing rate (calls placed each second). Defaults to `2`. Dialing too aggressively can flag your numbers as spam — start low and watch [Connectivity](/voice-agents/monitor/agent-analytics/connectivity). See [Dialing rate & concurrency](/voice-agents/deploy/campaigns/dialing-rate) for how this interacts with concurrency and your plan limits.
* **Allowed days** — the days of the week the campaign may dial.
* **Calls allowed between** — the daily time window (for example `09:00 am`–`06:00 pm`).
* **Retry configuration** — a toggle. Leave it **off** to dial each contact once; turn it **on** to retry unanswered contacts (see below).
* **Advanced → Webhook URL** — an optional endpoint that receives an event as each call finishes.
* **Advanced → Phone number rotation** — retry the same contact from a different agent number each time. See [Phone number rotation](#phone-number-rotation) below.

#### Retry configuration

With retries **on**:

* **Max retries** — `0`–`20` (default `3`).
* **Retry interval** — minutes between attempts (default `30`). Tick **Customize interval per attempt** to set a different gap for each attempt.
* **Retry on** — which outcomes trigger a retry:

| Outcome            | Notes                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Busy**           | Line was busy.                                                                                    |
| **No Answer**      | Rang but wasn't picked up.                                                                        |
| **Failed**         | The call failed to connect.                                                                       |
| **Short Duration** | Connected but ended too quickly — set the **threshold (seconds)** below which it counts as short. |
| **Provider Error** | A telephony-provider error — set its own **Max retries** and **Interval (min)**.                  |
| **Internal Error** | A system-side error — set its own **Max retries** and **Interval (min)**.                         |

#### Review & Launch

A read-only summary of every step — **Agent** (agent and version, campaign name, connection, phone numbers), **Recipients** (file, valid/removed row counts, mappings), and **Schedule** (period, allowed time, days, CPS, retries). Expand a section to double-check the details.

Optionally run a **Test dial** (below), then tick **I have reviewed this campaign and I am ready to launch** and click **Launch**.

## Test dial

On the **Review & Launch** step, **Test dial** (*optional but recommended*) places an instant outbound call to a few internal numbers so you can verify the agent works end-to-end before going live.

* Test calls dial **from this campaign's numbers**, but **don't count toward campaign metrics**.
* The agent uses the variables from **one cohort row** — the previewed row is shown, and **Pick random row** swaps it. Complete the cohort mapping first, otherwise no preview variables are available.
* Under **Test numbers**, select up to **5** numbers (or **Add a number**), then click **Place test calls**.

## Phone number rotation

When phone number rotation is enabled, every subsequent call to the same user uses a different agent number until each number in your pool has been used once for that user.

If User X gets a no-answer on +91-111, the retry to User X will not call from +91-111 again. It picks from the other numbers in the pool (for example +91-222 or +91-333). Only after all numbers have been used for User X does the pool reset and reuse begin.

Use it when a campaign has multiple outbound numbers and you want retries to the same contact to come from a fresh caller ID each time — for example, to avoid a contact learning to ignore one number.

> **Note**
>
> Rotation only applies on agent campaigns, and you need **two or more agent numbers** on the campaign (the **Agent** step) for it to have an effect.

### Enable phone number rotation

**UI** — in the campaign wizard:

1. **Agent** — select a connection and two or more phone numbers (or a group with multiple numbers).
2. **Schedule** — set campaign period, dialing rate, and retries. Expand **Advanced**.
3. Turn **Phone number rotation** on.
4. Continue to **Review & Launch**, then launch.

The **Advanced** panel also includes an optional **Webhook URL**; rotation is controlled only by the **Phone number rotation** toggle.

**API** — set `phone_rotation.agent` to `true` on `app_config` when creating or updating a campaign:

```json
{
  "phone_rotation": {
    "agent": true
  }
}
```

Full `app_config` example:

```json
{
  "app_config": {
    "app_id": "your-agent-id",
    "app_version": 1,
    "app_type": "agent",
    "attempts_per_second": 1.0,
    "connection_configs": [
      {
        "connection_id": "Exotel-Sarv-0f9a37e1-adf6",
        "phone_numbers": [
          "+918048637405",
          "+912048566401",
          "+917948229334"
        ],
        "weight": 1
      }
    ],
    "retry_config": {
      "max_retries": 3,
      "retry_interval_minutes": [5, 5, 5],
      "retry_on": {
        "busy": { "enabled": true },
        "failed": { "enabled": true },
        "no_answer": { "enabled": true }
      }
    },
    "phone_rotation": {
      "agent": true
    }
  }
}
```

| Field                                | UI equivalent                    | Description                                      |
| ------------------------------------ | -------------------------------- | ------------------------------------------------ |
| `phone_rotation.agent`               | **Phone number rotation** toggle | `true` = on; `false` (default) = off             |
| `connection_configs[].phone_numbers` | **Agent** step phone selection   | Numbers in the rotation pool — need at least two |

Create: `POST /api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns`

Update: `PATCH /api/scheduling/v1/orgs/{org_id}/workspaces/{workspace_id}/campaigns/{campaign_id}` — pass the full updated `app_config` while the campaign is **Scheduled** or **Paused**.

> **Tip**
>
> Start with a low **Attempts per second** and a small cohort, place a **Test dial** to confirm the agent behaves, then watch [Connectivity](/voice-agents/monitor/agent-analytics/connectivity) for the first hour before scaling up. See [Best practices](/voice-agents/deploy/campaigns/best-practices) for the full launch checklist.

## Where to go next

#### [Cohorts](/voice-agents/deploy/campaigns/cohorts)

Add more contact batches to a running campaign.

#### [Campaign details](/voice-agents/deploy/campaigns/campaign-details)

Track metrics, cohorts, and schedules once it's live.