DeployCampaigns

Create a campaign

View as Markdown

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.

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.

1

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.

Click Next to continue.

2

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 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:

ColumnWhat it does
FieldThe agent variable to fill (for example Phone Number, developer_name, gender).
CSV columnThe column from your file to pull the value from — search the list, or set None to leave it unmapped.
RequiredMarks the field as mandatory. Phone Number is always required.
Formatting functionsAn optional transform applied to the raw CSV value before the call (see below).
PreviewThe resulting value for the previewed row.

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.

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.

3

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. See Dialing rate & concurrency 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 below.

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:
OutcomeNotes
BusyLine was busy.
No AnswerRang but wasn’t picked up.
FailedThe call failed to connect.
Short DurationConnected but ended too quickly — set the threshold (seconds) below which it counts as short.
Provider ErrorA telephony-provider error — set its own Max retries and Interval (min).
Internal ErrorA system-side error — set its own Max retries and Interval (min).
4

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.

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:

1{
2  "phone_rotation": {
3    "agent": true
4  }
5}

Full app_config example:

1{
2  "app_config": {
3    "app_id": "your-agent-id",
4    "app_version": 1,
5    "app_type": "agent",
6    "attempts_per_second": 1.0,
7    "connection_configs": [
8      {
9        "connection_id": "Exotel-Sarv-0f9a37e1-adf6",
10        "phone_numbers": [
11          "+918048637405",
12          "+912048566401",
13          "+917948229334"
14        ],
15        "weight": 1
16      }
17    ],
18    "retry_config": {
19      "max_retries": 3,
20      "retry_interval_minutes": [5, 5, 5],
21      "retry_on": {
22        "busy": { "enabled": true },
23        "failed": { "enabled": true },
24        "no_answer": { "enabled": true }
25      }
26    },
27    "phone_rotation": {
28      "agent": true
29    }
30  }
31}
FieldUI equivalentDescription
phone_rotation.agentPhone number rotation toggletrue = on; false (default) = off
connection_configs[].phone_numbersAgent step phone selectionNumbers 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.

Start with a low Attempts per second and a small cohort, place a Test dial to confirm the agent behaves, then watch Connectivity for the first hour before scaling up. See Best practices for the full launch checklist.

Where to go next

Cohorts

Add more contact batches to a running campaign.

Campaign details

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