Skip to main content
Telephony connects your agent to the real phone network. Without it, your agent has no number to call from. This page walks you through connecting a phone number so your agent can start making outbound calls.
Before you start: You need a configured agent. If you haven’t created one yet, head to Create an Agent first.

​
How Telephony Works in Vaani

When your agent makes a call, the recipient sees a phone number on their caller ID — just like a normal phone call. Vaani handles all the voice infrastructure behind the scenes (WebRTC, media servers, call routing). Your job is simply to connect a phone number. A few things to know:
  • Each agent needs at least one phone number assigned to it
  • You can assign different numbers to different agents, or share one number across multiple agents
  • You can override the caller ID on a per-call basis through the API

​
Choose Your Setup Method

There are two ways to connect a phone number. Pick the one that fits your situation:

​
Phone Number Formats

All phone numbers in Vaani must use E.164 format — the international standard for phone numbers: 
+[country code][number]
CountryFormatExample
United States+1XXXXXXXXXX+14155551234
India+91XXXXXXXXXX+919876543210
United Kingdom+44XXXXXXXXXX+442071234567
Don’t include spaces, dashes, or parentheses. +1 (415) 555-1234 won’t work — use +14155551234.

​
Overriding the Default Number Per Call

By default, every call uses the phone number assigned to the agent. But you can override this on a per-call basis by passing outbound_number in the API request: 
{
  "agent_id": "your-agent-id",
  "contact_number": "+919876543210",
  "outbound_number": "+14155559999"
}
This is useful when you want different caller IDs for different campaigns, regions, or clients — without creating separate agents for each.
The outbound_number must be a number that’s configured in your telephony settings. You can’t use an arbitrary number. For a quick refresher on all the identifiers you’ll encounter, see the identifier reference table.
Start with a provisioned number for testing. You can always switch to a SIP trunk later without changing your agent configuration or agent_id.

​
Troubleshooting

Check three things: (1) the phone number is assigned to your agent in the Telephony settings, (2) the contact_number in your API request is in E.164 format, and (3) the number you provisioned or connected is active and not suspended.
This usually means the outbound number isn’t properly configured in your telephony settings. If you’re using a SIP trunk, check that your provider has caller ID enabled and that the number is verified with them.
A SIP trunk is a virtual phone line that connects software (like Vaani) to the public phone network through an external provider. Think of it as a bridge between the internet and traditional phone calls. Providers like Twilio, Telnyx, and Vonage offer SIP trunking services. If you don’t already have one, use Vaani’s direct provisioning instead — it’s simpler.
Vaani supports phone numbers in a growing list of countries. For the most current list of supported regions, check the Telephony settings page in your dashboard or contact support.
Video walkthrough coming soon. Follow the steps above — they cover everything the video will.

​
Next Step

Generate an API Key

Create your API key to authenticate calls to the Vaani API