> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md
# Buy or import a number
> Buy a Ringg-provided number, connect Exotel, Twilio, Plivo or another provider, then import or add your own numbers from the Add number dialog in Numbers.
A Ringg-provided number is the quickest start; connect your own provider account when you already have numbers or a carrier contract ([compare the two](/documentation/inventory/phone-numbers/overview#ringg-provided-numbers-vs-your-own-telephony)).
In the dashboard: **Sidebar → Inventory → Numbers → All Numbers → Add number**.
## Before you start
Your workspace role needs the **Numbers** permission.
Optional: only to import or buy on your own telephony.
## How the Add number dialog works
The dialog, titled **Add Numbers**, has three parts:
1. **Provider list** (left): the [supported providers](/documentation/inventory/phone-numbers/overview#supported-telephony-providers), with Plivo selected when the dialog opens.
2. **Selectors** (top): the telephony account, then country and region (region starts at **All**). The gear, **Configure provider**, opens the provider's account settings.
3. **Tabs**, which depend on the account you pick:
| Tab | Shown when | What it does |
| - | - | - |
| **Buy new** | Any account that can list numbers for sale | Lists numbers you can buy in the chosen country and region. |
| **Import your own** | The selected account is your own provider account | Lists numbers already on your provider account so you can bring them into Ringg. |
| **Add custom** | The provider does not share its number list (SIP, Custom, and some accounts) | Lets you type numbers in. Replaces the other two tabs. |
## Connect a provider account first
Skip this if you buy a Ringg-provided number from Plivo or Vobiz. For anything else, Ringg needs your provider credentials. If the provider has no account yet, the form opens as soon as you select the provider.
In **Add Numbers**, select the provider on the left, then click the gear (**Configure provider**). The panel lists the accounts you already connected for that provider.
Click **Add**. Enter a **Name** (for example `Exotel Pune`) and the provider's fields from the table below. Secret fields have a show/hide toggle.
You see "BYOT added successfully." and the account appears in the telephony account selector.
For Plivo, Twilio, Exotel, Vobiz, Tata Tele, Maqsam and VoiceLink, Ringg tests the credentials with the provider before saving. Wrong ones show "Invalid credentials for *provider*" and nothing is saved.
Every field is required unless marked optional. Provider-side setup is in each provider's guide under [Bring your own telephony](/documentation/inventory/phone-numbers/your-own-telephony/byot-overview).
| Provider | Fields |
| - | - |
| [Exotel](/documentation/inventory/phone-numbers/your-own-telephony/exotel) | SID, API Key, API Token, App ID, Subdomain (for example `api.exotel.com`) |
| Mcube | Auth Token |
| [Ozonetel](/documentation/inventory/phone-numbers/your-own-telephony/ozonetel) | Campaign Name, User Name, API Key, SIP Number |
| [Plivo](/documentation/inventory/phone-numbers/your-own-telephony/plivo) | Auth ID, Auth Token, App ID (optional; leave it blank, Ringg creates its own app) |
| Tata Tele | API Key, Auth Token |
| InTalk | Account Name (the `acme` in `acme.apps.intalk.cc`), Base URL (the `apps.intalk.cc` part), API Token. Import only: no **Buy new** tab. |
| Maqsam | Base URL (your account host, for example `mycompany.maqsam.com`), Access Key ID, Access Secret, Campaign ID |
| [Twilio](/documentation/inventory/phone-numbers/your-own-telephony/twilio) | Account SID, Auth Token |
| Vobiz | Account ID, Auth ID, Auth Secret |
| VoiceLink | Username, Password, Client ID |
| [SIP](/documentation/inventory/phone-numbers/your-own-telephony/sip-trunking) | The **Configure SIP Trunks** form: name, direction (Inbound, Outbound, Both), inbound sources, outbound target, transport and optional authentication |
To delete a provider account, open **Configure provider** and use **Delete Account** on its row.
## Buy a new number
Select the provider. In the telephony account selector, choose **Ringg** for a Ringg-provided number (Plivo and Vobiz only), or one of your connected accounts.
Choose the country, then a region or **All**. Each provider sells in fixed countries ([provider table](/documentation/inventory/phone-numbers/overview#supported-telephony-providers)).
On the **Buy new** tab, pick a number from the list (20 per page). With the **Ringg** account, each row also shows its **Rental Rate** per billing period, for example `₹499 / 1 Month` (the **Number rental** rate on [Billing](/documentation/manage-account/billing)). Click **Buy Number** and confirm with **Buy Number**.
You see "Purchase has been completed successfully." and the number appears in **All Numbers**.
A new number joins no [number pool](/documentation/inventory/phone-numbers/number-pools); add it to one yourself. The same goes for imported and hand-added numbers.
## Import a number you already own
Select the provider and your connected account in the telephony account selector. The **Import your own** tab appears.
Open **Import your own**. It lists the numbers on your provider account; those already in Ringg show **Already Imported**. Click **Import** on a row and confirm with **Import**.
You import one number at a time. For an Exotel number that will take inbound calls, attach it to the `Ringg Inbound` applet in Exotel first ([Exotel](/documentation/inventory/phone-numbers/your-own-telephony/exotel)).
## Add a number by hand
1. Type a number with its country (for example `+91 98765 43210`) and click **Add**. Repeat for more numbers; each appears as a chip under **Numbers:**. For Maqsam, the field accepts Saudi Arabia and UAE numbers only.
2. Click **Save**.
You see "Numbers have been added successfully." A number already in the workspace is refused with "Phone number already exists."
## International numbers
India is always available. Canada, the United States, Saudi Arabia and the United Arab Emirates appear only when international calling is enabled for your workspace; without it, the country list shows India only, and Twilio and Maqsam are hidden. The same setting allows calls to numbers outside India. The dashboard has no switch for it: it turns on after your first successful payment, or contact Ringg support.
## Remove, detach and tag numbers
All three actions are on the number's row in **All Numbers**.
| Action | Button | What happens |
| - | - | - |
| Remove | **Remove Number** (trash) → **Remove** | The number leaves your Ringg workspace. A number on your own provider account stays registered with your provider. |
| Detach | **Detach Number** in **Used By** → **Detach** | The number is unlinked from its [inbound agent](/documentation/inventory/phone-numbers/inbound-agent-number#detach-a-number), stays in the workspace and joins your Default pool. |
| Tag | **Add Tags** (pencil) → **Manage Tags** | Type a tag in **Enter tag** and click **Add**. Click a tag chip to remove it. |
Detach a number from its agent and take it out of running campaigns before you remove it. Test numbers can't be removed or tagged.
## With the API
Numbers are bought, imported and added in the dashboard only. [Get Workspace Numbers](/api-reference/endpoint/numbers/get-workspace-numbers) reads the list (example in [List numbers by API](/documentation/inventory/phone-numbers/overview#list-numbers-by-api)); pass a number's `id` as `from_number_id` when you [place a call](/documentation/inventory/phone-numbers/inbound-agent-number#outbound-choose-the-caller-id).
## Troubleshooting
Each provider sells in fixed countries ([provider table](/documentation/inventory/phone-numbers/overview#supported-telephony-providers)), and countries other than India need [international calling](#international-numbers) on your workspace.
The tab shows only when the selected account is your own provider account. It does not show for the **Ringg** account or for accounts that use **Add custom**.
**Buy new** shows "No new numbers available." when the provider has none for that country and region. Set the region to **All** or try another region.
SIP appears only for enterprise workspaces and is not offered on the Saudi Arabia or UAE regional dashboards.
No. Every workspace has [test numbers](/documentation/inventory/phone-numbers/overview#test-numbers) for [test calls](/documentation/build-agents/test-and-improve/test-an-agent). You need your own number for calls to customers, campaigns and inbound agents.
## Next steps
Attach your new number to an inbound agent.
Put numbers in a pool for campaigns and API calls.
Call a contact list from your new number.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
