> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Calling campaigns
> Your agent rings a list and has the conversation itself.
A calling campaign is your agent ringing people one after another and talking to
them — the same audience rules and the same consent as a
[broadcast](/whatsapp/broadcasts), on the phone instead.
## Where to find it
**Voice Campaigns** is in the main sidebar, just under Contacts — under it
because a calling campaign is made *of* a contact list. Every campaign in the
workspace is on that one page, whichever agent places the calls.
## Which agent does the calling
You choose, when you build the campaign. It matters more than it sounds: a call
goes out from **that agent's number**, opens with **that agent's first words**,
and is priced by **that agent's voice**.
If you only have one agent that can call, there is nothing to choose and you are
not asked. If you have several, the builder asks first — before the audience,
because the answer changes what the rest of the campaign is — and the list shows
which agent each campaign belongs to.
An agent can only be picked if it can actually place calls: it needs a number
pointed at it on [Phone Numbers](/channels/phone-numbers), and it has to be set
to answer on the phone rather than only on the web. The builder says which of
the two is missing rather than making you guess.
Calling campaigns used to live on each agent's own page. They moved to the
main sidebar so one workspace has one list — with three calling agents you
had three lists that could not see each other, and finding a campaign meant
remembering which agent you made it on. Old links still work.
## Who gets called
Two answers, and they are alternatives rather than a pair.
**People already in Contacts.** The same four lists a
[broadcast](/whatsapp/broadcasts) offers, each showing its count before you
commit, and the same tags to narrow within one.
**Upload a list.** A CSV, mapped and rung. This is the one most people want:
the spreadsheet already exists, and nobody wants to import it, tag it, and then
come back here.
**Numbers you must never call** belong on the do-not-contact list, on the
**Contacts** page under *Do not contact*. Paste them or upload a file — from a
regulator, a complaint, or a lawyer's letter — and no campaign will ever reach
them, on any channel.
It is not the same as somebody opting out. Opting out is about a customer you
already have; this is about numbers, most of which are not in your contacts at
all, and an import cannot undo it. It is checked at the moment each call is
placed, so a list you upload at eleven stops a campaign that is already running
by the time it reaches three.
### Uploading a list
Drop a CSV with a header row. We guess which column is the phone number, the
name and the email — "Phone", "Mobile", "WhatsApp Number" and "Contact" all
land on the same guess — and you can change any of them. Any other column can be
pointed at something your agent says: see
[saying something different to each person](#saying-something-different-to-each-person). The panel shows the
numbers **as we will actually dial them**, not as the file wrote them, because
that is where spreadsheet damage shows up.
Pick the country for numbers with no country code. A number starting `+` or
`00` keeps its own.
**Excel eats long numbers.** A phone number in a General cell can be saved as
`9.19E+11`, and those digits are genuinely gone — we refuse the row rather
than invent a number that reaches a stranger. Format the column as text and
export again.
Rows we cannot read are listed with their line numbers and the reason. Leaving
them out is a tick you have to make: a list of a thousand that quietly calls
nine hundred is worse than one that stops and tells you.
Repeats within the file are dropped and counted. The same customer twice in an
export is ordinary; ringing them twice is not.
### What an upload does to your contacts
**The people on the file become contacts.** They are in Contacts afterwards,
and the campaign is aimed at exactly them — a label we put on those rows is
what keeps this campaign to this list.
There is a tick saying these people agreed to be called. It is a claim you are
making, recorded with the date, and it decides which *later* campaigns reach
them:
| The tick | Who reaches them afterwards |
| ---------- | ----------------------------------------------------- |
| Left alone | Campaigns aimed at everybody, or at imported contacts |
| Ticked | Those, plus campaigns aimed at people who opted in |
Uploading a spreadsheet is not consent, and a phone call is not a message
somebody deletes. Calling a number on India's DND register without consent is
an offence under TCCCPR, and the complaint lands on the number you called
from.
Anybody who has asked you to stop is left out of the list even when they are in
the file. That is decided in the database rather than by the screen, so it
holds however the campaign was built.
The label stays on those contacts afterwards, so you can aim a second campaign
at the same people without uploading the file again.
## What it says
There is no message to write. A calling campaign opens with **the agent's own
first words** — the greeting on its Voice settings, the same one somebody hears
when they ring in — and talks from there.
> Hello, this is Meera from Sunrise Dental.
That is deliberate, and it is the one place a calling campaign is simpler than a
broadcast. A box here would have been a second version of what your agent
already says, and then nobody could answer the only question that matters: which
one does a customer actually hear? The builder shows the opening before you
launch, beside everything else, and links to where it is changed.
Worth reading it before a campaign goes out. A greeting written for people who
rang **you** — "Thank you for calling Sunrise Dental" — is the wrong sentence
coming from somebody who rang **them**.
It is a real conversation, not a recording. People interrupt, ask something
unrelated, and the agent answers from your knowledge like it does on any other
call — then the whole thing lands in the inbox with its transcript.
Calls go out a few at a time rather than all at once. A hundred people are not
all rung in the same minute, which is deliberate: it is what a phone line can
actually carry, and what does not look like a machine.
**Promotional calling in India needs a 140-series number.** An ordinary
business number is licensed for service and transactional calls, and using it
to promote something can get it blocked.
You mark each call campaign as **service** or **promotional**, and we refuse a
promotional one from a number that is not licensed for it — with a reason, not
a silent failure. Marking a promotional campaign as service to get past this
is the thing that gets numbers blocked.
## Saying something different to each person
Put `{{first_name}}` — or any name you like in double braces — into your
agent's greeting or its instructions, and every call fills it in from the row
that person came in on.
> Hello {{first_name}}, calling from Sunrise Dental about your appointment on
> {{appointment_day}}.
When you upload a list, the campaign shows you what your agent asked for and you
point each one at a column. Nothing to declare anywhere: we read the braces out
of your agent's own words, so the list is always what it actually says.
### What fills what
| Written in the agent | Filled from |
| ------------------------------------------------------ | -------------------------------------------- |
| `{{first_name}}`, `{{name}}`, `{{phone}}`, `{{email}}` | the contact, unless your file says otherwise |
| anything else | the column you mapped it to |
Your file wins where the two disagree — a column of preferred names beats the
name we have stored — but a **blank cell does not**. An empty column leaves the
contact's own details alone rather than wiping them for that one call.
`{{first_name}}` follows whichever name won, so a list that carries names for
people you have never spoken to still greets them properly. Map a `first_name`
column of your own if you want to control exactly what they are called — "Dr
Menon" rather than the first word of a full name.
**Keep values short.** These are words your agent says out loud, so anything
past about 150 characters is trimmed. A date, an order number, a name or a
short phrase is what belongs here; a notes column mapped by accident is not.
### What happens when it is not filled
Nothing is said. "Your order {{order_id}} is ready" with no order mapped becomes
"Your order is ready" — a sentence, spoken normally, with the stray space and
the double space cleaned up.
**Nobody ever hears the braces.** That is the one rule this feature is built
around: an unmapped, unknown or misspelled variable is left out rather than
read aloud. A cell that itself contains `{{something}}` is stripped too — you
cannot smuggle a placeholder in through a spreadsheet.
### Careful with instructions
A variable in your agent's **greeting** only affects calls it makes.
A variable in its **instructions** is part of every conversation that agent ever
has — someone ringing your number, a website chat, a WhatsApp message. None of
those came from a list, so there is nothing to fill from and it resolves to
nothing for them. The upload screen says so when it spots one, and it is worth
reading: an instruction written for one campaign quietly applies to everybody.
## When it calls, and when it stops
A campaign carries its own clock. Everything below is read in it, and it starts
as your workspace's — change it if you are setting this up from somewhere else,
and what you type is what the campaign does.
| Setting | What it means |
| --------------------- | -------------------------------------------------- |
| **It starts** | Now, or at a time you pick |
| **Hours it may call** | The same stretch of every day the campaign runs |
| **Stop after** | Anything still unanswered by then is left uncalled |
Calls outside the hours **wait** rather than being dropped. A campaign started
at midnight begins in the morning, and its row says so rather than looking
stalled.
Indian rules restrict commercial calling to daytime, and 9am to 9pm is the
window every campaign keeps unless you narrow it. Narrowing is normal — a
clinic ringing about appointments and a shop ringing about an offer do not
want the same hours.
**The hours are read where each person is.** If your list has numbers in more
than one country, "9am to 6pm" means nine in the morning *to them* — a London
number is rung at 9am London time, not at 9am yours. That is what the rules say
and what anybody being rung would expect. Nothing to set: it comes from the
number.
Two consequences worth knowing:
* A campaign spanning countries is never all callable at once, so it works
through the list in waves as each country's morning comes round. The row says
it is waiting rather than looking stalled.
* For a country that spans several time zones — the United States, Canada,
Australia, Russia, Brazil — a phone number does not say which one. We stay
inside your hours at **both ends** of the country rather than guessing, which
makes the callable stretch shorter but never rings anybody at six in the
morning. If your hours are very narrow, a list like that may not be callable at
all; the campaign says so instead of trying for ever.
## Calling from more than one number
A big campaign from a single number is the fastest way to get that number marked
as a nuisance line — and once it is, everything it does afterwards suffers,
including customers ringing you back.
If you hold spare numbers, lend them to the agent on
[Phone Numbers](/channels/phone-numbers) and the campaign spreads its calls
across them. Nothing changes in the builder and there is nothing to switch on.
Two things are worth knowing, because they are what makes it safe:
* **Whoever we ring keeps the same number.** A second attempt comes from the
number that rang them the first time, and somebody ringing back reaches the
same agent.
* **Each number has a daily limit** of 200 calls. A campaign that uses up every
number pauses with a line saying so and carries on the next morning.
## Which days, and how fast
Two things worth setting on any list longer than a few hundred.
**Days it may call.** By default a campaign calls every day it is running,
Sunday included. Pick the days in the builder and it waits for the next allowed
one. The day is read where each person is, the same as the hours.
**At most, per hour.** By default a campaign uses every line your plan gives it,
which is the fastest it can go. That is the wrong setting when somebody has to
answer the calls that connect — a team of two cannot hold thirty conversations,
and the rest of your customers hear a hold tone. A cap only ever slows a
campaign down; your plan's lines are still the ceiling.
The cap is a rolling hour, not a clock hour. "Thirty an hour" means thirty in
any sixty minutes — not thirty at 10:59 and thirty more at 11:01.
## If it reaches voicemail
Most people do not pick up. By default the call hangs up on an answering machine,
which is right when there is nothing to say — but a campaign that only reaches a
fifth of its list in person is doing a fifth of the work.
Write a message in the builder and it is left on the machine instead: we wait for
the greeting to finish and the beep, then say it, then hang up.
Writing a message is enough — you do not have to turn anything else on. It is
not available on every phone provider, and if yours is one of those you are
told when you write the message rather than after the campaign has run.
The first second or two of the agent's opening reaches the greeting before the
message takes over. That is before the beep, so it is usually not recorded —
"usually" because answering machines differ. Test it on your own number first.
Calls that left a message are counted separately from calls somebody answered.
A recording is not a conversation, and a connect rate that counted it would tell
you nothing.
## Testing two openings
Most of why somebody stays on a call or hangs up happens in the first few
seconds, so the opening is the thing worth testing.
Fill in **Test a second opening** and the campaign is created as two: "(A)" and
"(B)", each calling half the list, each with its own progress and its own
numbers. Nobody is called twice — the halves never overlap — and you compare
them by opening the two rows.
## How it went
A calling campaign shows more than how many calls went out:
| Number | What it means |
| ---------------- | ------------------------------------------------------------- |
| **Called** | The phone company accepted the call and somebody's phone rang |
| **Answered** | A person picked up, with the percentage of calls placed |
| **Average call** | How long the answered ones lasted |
| **Voicemails** | A message was left on an answering machine |
Underneath, **How the rest ended** breaks down everything that did not connect —
no answer, line busy, declined, not reachable — and each person in the list shows
how their own call ended rather than just "Called".
That breakdown is what tells you which problem you have. A lot of "Not reachable"
is a stale list. A lot of "Declined" is the wrong audience or the wrong opening.
A lot of "No answer" is usually the wrong time of day.
Declined and unreachable numbers are never called again. Busy and no-answer
are what retries are for.
## Ringing again
A person who does not pick up is not called again unless you say so. Whether a
second attempt is reasonable depends on why you rang, so it is a choice on the
campaign rather than a default.
Choose **how many times** to try again and **how long to wait** between tries.
Two retries half an hour apart means three calls at most, and the wait starts
when a call goes unanswered rather than when the campaign started — so somebody
rung late in a long run still gets the gap you asked for.
**A busy line gets its own, shorter wait.** The two are not the same thing and it
is worth setting them apart:
* **Engaged** means they are holding their phone right now. That is the most
reachable anybody ever is, so the default is five minutes.
* **No answer** means they are away from it. Ringing back five minutes later is
pestering, so the default there is half an hour.
Leave the busy wait alone and it does what it always did — the same wait for
both.
Anyone who answers is never called again, and retries keep to the calling hours
like every other call.
**And anyone who declined is never called again either.** We read what the
carrier says about how the call ended, so a retry means what you would want it
to mean:
| How it ended | Tried again |
| ----------------------------------- | ------------------------------------- |
| No answer | Yes — this is what retries are for |
| Line busy | Yes |
| They declined | **No.** Pressing decline is an answer |
| Number does not exist, or is barred | No |
You see the same words on the call in your inbox — "Declined" rather than
"Missed call" — so the reason a number was or was not tried again is on the
record rather than something to work out.
A phone ringing twice from a number somebody did not recognise the first time
is the complaint that costs a number. Space the attempts out, and keep them
few.
## Being told it started
A campaign set for nine in the morning starts with nobody watching — which is
the point of scheduling it, and also why "did it actually go?" is the question
it creates.
Pick anybody in your workspace under **email when it goes live** and they get an
email and a notification the moment it starts, with how many people it is
calling. Nobody is picked by default: a campaign that emails four people every
time it starts is a campaign whose emails get filtered.
## Cost
Calls are charged in half-minute steps, rounded up, and only for calls that
actually connect — a number that rings out costs nothing. The per-minute rate is
your agent's voice rate; the campaign builder shows it before you commit.
See [Voice](/channels/voice) for the rest of what an agent does on the phone.