> ## 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.
# Phone numbers
> Get a number your customers ring, or point one you already own at your agent.
Your agent answers on a phone number. You can get one from us — searched,
bought and ready on the same screen — or use a number you already own.
Numbers belong to the **workspace**, not to one agent. They live on the **Phone
Numbers** page in the main sidebar, which lists every number you hold, where it
came from, which agent answers it, which agent *calls out* on it, and whether it
can place calls as well as answer them. You can search the list and move any
number to another agent.
You do not need a number to try voice. The website call button works without
one, on any plan, and it is the same agent with the same voice. A number is
what lets somebody ring you from a phone — and if you already own one, you can
point it at your agent on any plan, free included.
## Getting a number from us
In the main sidebar choose **Phone Numbers**, then **Buy / Import number**.
Pick a country, and a city if you want a local code. You will see the
numbers available now, each with what it costs a month.
Choose a number and confirm. It is yours from that moment, and there is
nothing to configure with a phone company and no settings to copy anywhere.
A new number is not pointed anywhere yet. On the **Phone Numbers** page,
choose the agent beside it. That agent starts answering immediately.
Call the number. You should hear your greeting, then the agent.
### What it costs
Each number has a monthly price, shown before you take it, and it repeats every
month until you give the number up. Your plan may include one — if it does, the
page says so before you choose.
**Buying a number needs a paid plan**, because we rent it for you every month.
Pay as you go has no monthly fee of its own and can hold numbers.
**Pointing a number you already own at your agent works on every plan,
including the free one.** It costs us nothing to answer it — you are already
paying your own provider for the number — and a phone call is usually the thing
you want to hear before you decide to pay for anything. Free-plan calls come out
of the same trial minutes as calls from your website.
That covers calls in **both directions**. On the free plan your agent can answer
a number you brought and, once you have added that account's credentials, ring
people from it — your own provider bills you for the line either way. Buying a
number from us is the part that needs a paid plan.
### India needs paperwork first
An Indian number cannot be issued to anybody without an approved application in
**your** name — not ours. The Voice page walks you through it: business details,
then the documents the regulator asks for.
This is not our rule and we cannot shortcut it. Numbers in most other countries
need nothing beyond choosing one.
A number bought before your application is approved will not ring. Finish the
application first, then take the number.
### Marketing calls need a different number
Indian rules give every number a purpose, and it is worth knowing before you buy
one rather than after you build a campaign.
| What you are calling about | The number for it |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| Reminders, order updates, renewals, anything the customer is expecting | The numbers on this page — landlines, bought in a few clicks |
| **Marketing** — an offer, a promotion, anything selling | A **140** number, which is applied for in your business's name |
A 140 number is not sold from a list. It is issued to your business after you
register on the DLT portal, so choosing **Promotional (140)** when adding a
number shows you the steps rather than a search.
As both the *principal entity* and the *telemarketer* — the calls are yours,
so the registration is yours. Two to three working days.
Your GST certificate and both DLT registrations. We apply for the number and
hand you back the approval letter it needs.
On the same portal. Scripts are approved one at a time — a marketing call
says an approved thing, not whatever you type on the day.
Five to ten working days end to end. Get in touch and we will start it.
Check this before anything else: the telemarketer registration has to be in
**Maharashtra** or **Karnataka**. Registered anywhere else and we cannot get
you a 140 number today.
Until you hold one, a campaign marked *promotional* is refused rather than
quietly sent from a landline. That refusal is the rule working — it is the
number that carries the penalty, not us — and it names the number it is about
so you know which one to change.
## Using a number you already own
If your number is with **Plivo** or **Vobiz**, you can point it at your agent
and keep it where it is. You go on paying them for the number and we charge you
nothing for it — we only answer it.
Choose **Import**, then say which of the two carriers the number is with.
Exactly as it is dialled, including the country code.
Set the address shown as the number's **Answer URL** in your carrier's
console, with the method set to **POST**. Copy the whole thing — everything
after the question mark matters, and a shortened address will not be
recognised.
For one of the two carriers the address is the same for every number and is
shown straight away, so you can set your console up first if you prefer. For
the other it carries a key unique to the number, so it appears once the
number is added. Either way that address belongs to the number, so it keeps
working if you later move the number to a different agent.
Back on the **Phone Numbers** page, choose the agent beside it.
Until the Answer URL is set, the number rings and nothing picks up. Nothing on
this page can tell you that has happened, because the call never reaches us —
so if a test call goes unanswered, check the Answer URL first.
A number on any other carrier cannot be pointed at us. We check that each call
genuinely came from the carrier it claims to, and a call from anywhere else is
refused before it is answered.
**Call recording is not available on a number you brought yourself.** Recording
has to be asked of the carrier by whoever holds the account, and for your own
number that is you rather than us. A number taken from us records normally.
### Calling out from a number you brought
Outgoing calls go out through the account the number belongs to — and for your
own number, that account is yours, even if your carrier happens to be the same
one we buy numbers from. So there is one more step, and only if you want
outgoing calls: in the same **Import** panel, add the **Auth ID** and **Auth
token** from your carrier's console.
We check them against your carrier before saving, so a wrong pair is refused
while you are still looking at the page you copied it from rather than on a call
weeks later. The token is stored encrypted and never shown again.
You can change them later without re-adding the number: the row's menu on the
**Phone Numbers** page has **Edit credentials**. They belong to the carrier
account rather than to one number, so saving applies to every number you brought
from it.
The **Outbound** column on that page says which of your numbers can already
place calls and which are still waiting for their credentials — a number can
answer perfectly while being unable to ring anybody, and that column is where
you would see it.
Once they are saved, calling campaigns and the call API work from that number
exactly as they do from one taken from us.
Answering needs none of this. If the number only ever receives calls, the
Answer URL above is the whole setup.
A number can answer for **one agent**. Typing a number another agent already
answers is refused rather than quietly moved — that is almost always a
mistake. Moving one deliberately is a different act: choose the new agent
beside the number on the **Phone Numbers** page.
Whenever an agent is about to lose a number — moved to another agent, or set
back to no agent at all — we ask first and name the agent losing it. Pointing a
spare number at an agent for the first time takes nothing from anybody, so that
one just happens.
**Getting, moving, renaming, releasing and removing numbers need an owner or
admin.** Everyone else on the workspace sees the list and what each number is
doing, which is usually what they came to check.
An agent's **Voice** page shows which number that agent answers, and links here
to change it. Getting a number and choosing who answers it both happen on this
page, because a number belongs to the workspace rather than to one agent.
## What you can do to a number
On the **Phone Numbers** page every row has a menu:
* **Edit credentials** — for a number you brought, the API credentials of the
carrier account its outgoing calls go through. Saving applies to every number
you brought from that account.
* **Rename** — a name for your own eyes, so a list of numbers reads as
"Bengaluru showroom" rather than six strings ending in different digits.
Callers never see it.
* **Release** — only on a number you rent from us. See below; it is permanent.
* **Remove** — only on a number you brought. We forget it; you keep it.
You can also search the list, filter it by where the numbers came from, and
export what you are looking at as a spreadsheet.
## Spare numbers for calling out
A calling campaign goes out from your agent's number. That is fine for a few
hundred calls and starts to hurt at a few thousand: phone companies and phones
themselves watch for a line that makes a burst of calls, and once a number is
marked as one, **everything it does afterwards suffers** — including a customer
ringing you back and seeing a warning on their screen.
Spare numbers spread that out. Any number you hold that no agent answers on can
be lent to an agent for calling, and campaigns share their calls across the
agent's own number and its spares.
Any number on the page that is **Not attached** — one you bought and have
not pointed anywhere, or one you brought and have not used yet.
In the **Calls out for** column, choose the agent. That is the whole setup.
**What it does not do.** A spare does not become the agent's number. Nothing
about who answers changes, the number you gave your customers stays the number
they ring, and you can take a spare back at any time by choosing **Nobody**.
**Somebody ringing back reaches the right agent.** A call to a spare goes to the
agent that lent it, into the same conversation as everything else that customer
has ever sent you. This is the part that makes spares safe rather than clever,
and it needs nothing from you.
**One person always sees the same number.** Whichever of your numbers rings a
customer is the one that rings them again — including a second attempt days
later. Three attempts from three different numbers is what a nuisance call looks
like, and avoiding that is half the point, so it does not happen.
**Each number has a daily limit.** 200 calls a day, which is also the point:
without one, spreading calls over four numbers is the same burst four times
over. If a campaign uses up every number it says so, and carries on the next
morning — or sooner, if you lend it another.
A spare has to be on the same phone company as the agent's own number, and the
agent needs a number of its own first — spares spread calls, they do not make
them. A spare you brought also needs its carrier credentials saved, the same as
any number of yours that places calls. The page says which of these is missing
rather than letting you find out on a campaign.
A spare must be licensed for the same kind of calling as the campaign. In
India promotional calls need a 140-series number, so a campaign marked
promotional is refused if **any** of the numbers it would use is not one — and
it names which. It is the number that carries the penalty.
## Disconnecting, giving up, and removing
Three different things and only one of them is permanent.
**Disconnect** takes the number off the agent so it stops answering. The number
stays yours either way — your own number stays with your carrier, and one you
rent from us stays rented and still charged. It shows on the **Phone Numbers**
page as not attached, ready to point at another agent.
**Give up** hands a number you rent from us back to the phone company. The
monthly charge stops and the number goes back to the pool.
**Remove** applies only to a number you brought. It takes our record of it away,
so we stop answering it and stop listing it — the line stays yours and your
carrier keeps billing you for it exactly as before. Remember to unset its Answer
URL in your own console afterwards, or calls to it will still reach us and be
declined. Bringing it back later is the same three fields.
Releasing is permanent. The number goes back to the phone company and somebody
else can take it — we cannot get it back for you, even a minute later. If it
is printed anywhere, or anybody has it saved, keep it.
## What callers hear when nothing is set up
* **Answer calls off** — the number does not answer.
* **Answer calls on, Phone number switched off** — the number does not answer. You have
switched voice on without telling it to pick up the phone.
* **Everything on, no greeting** — the agent waits for the caller to speak
first. That is a real choice, and some lines are better that way, but it
surprises people who expected a greeting.
## Things worth knowing
Two agents cannot share a number. If you want different behaviour for
different callers — sales and support, say — that is one agent with
instructions covering both, or two agents on two numbers.
One agent can *call out* on several numbers, which is a different thing —
see **Spare numbers for calling out** above. Answering is still one to one.
The **Playground** has a **Try it on a real phone** box under the browser
call. Type your own number and press **Place call**: the agent rings you from
the number it answers on, so you hear exactly what a customer hears — a phone
line, not a browser.
It is a real call and costs the same per minute as any other. The browser
call beside it is free and instant, which is the one to use while you are
editing what the agent says; this one is for hearing how it sounds.
When your agent rings somebody, it calls from the number on this page. That
is what they see, and what they will ring back.
A normal business number is licensed for service and transactional calls.
Promotional calling in India needs a 140-series number, and using an
ordinary one for it can get the number blocked. See [Calling
campaigns](/channels/voice-campaigns).
Ring your own number and ask the hardest question you get — not "what are
your hours". The awkward one, with a condition attached, where the honest
answer is "it depends". That is the answer worth hearing out loud before a
customer does.