Connect a Twilio Account and Phone Number

Connecting your Twilio account directly to Versafy lets you bring its voice-capable phone numbers into one complete calling setup. Your Voice Agents can answer inbound calls, place outbound calls, use operator and business-hours routing, collect voicemail, and keep call activity together in Versafy.

This is the recommended Twilio setup when you want Versafy to manage the number’s active voice routing. It does not require an External SIP trunk.

With a direct Twilio connection, you can:

use Twilio numbers already owned by your business;
assign a number to any eligible Inbound Call Flow, including flows with operators, schedules, announcements, and voicemail;
enable a number for individual Voice Agent calls and Campaigns, when available;
review calls in Call Logs & Recordings.

If you need to keep your own Twilio SIP trunk and routing instead, follow Connect a Twilio Number through SIP. Do not complete both methods for the same number.

Before you begin

Prepare the following:

permission to create or manage a Twilio account;
the legal name, address, and identity or business documents requested for your chosen country and number type;
a payment method and sufficient Twilio balance for production use;
permission to manage Phone Numbers and Inbound Call Flows in Versafy;
an active Voice Agent if calls will be handled by an agent;
a password manager for the Twilio Auth Token.

Use one Twilio project or subaccount throughout this guide. The credentials entered in Versafy must belong to the same project or subaccount that owns the phone number.

Setup overview

You will complete the connection in this order:

Create and verify a Twilio account.
Upgrade it for production use.
Complete any required individual or business approval.
Buy a voice-capable phone number.
Copy the live Twilio credentials.
Connect Twilio in Versafy.
Assign the number to an inbound flow and enable outbound calling when needed.
Test both call directions.

1. Create and verify a Twilio account

Creating your own Twilio account keeps number ownership, regulatory records, payments, and usage under your organization’s control.

Open Twilio sign-up and create an account using an email address controlled by your organization.
Verify the email address.
Verify a real phone number you can access.
Complete the questions about your project or intended use.
Enable multi-factor authentication and store recovery information securely.
In Twilio Console, confirm which project or subaccount you are viewing before buying a number.

Twilio accounts begin with trial restrictions. A trial is useful for initial testing, but it limits phone numbers, destinations, and who can receive calls. Review Twilio’s current trial-account guide .

2. Upgrade the Twilio account for production

Upgrading removes important trial restrictions and lets the account support normal customer calling.

In Twilio Console, select Upgrade, or open Admin → Account billing → Upgrade account.
Create the requested account profile.
Enter your real address and payment information.
Add the requested starting balance.
Confirm that the project shows a paid status before relying on it for customer calls.

Twilio charges separately for phone-number rental and calling usage. Review the prices shown for your chosen country and number before purchasing.

3. Complete individual or business approval when required

Phone-number rules differ by country and number type. Twilio may require proof of who will use the number and where that person or organization is located. Completing the correct approval protects the number from delayed activation or later disconnection.

Choose the correct end-user type

Choose the option that matches the number’s real legal user:

Business — choose this when a registered company or organization will use the number. Use the organization’s legal name and matching registration and address documents.
Individual — choose this when a person will use and own the number in their personal capacity. Use that person’s legal identity and address documents.

Do not select a type only because its document list looks easier. The submitted identity, address, intended use, and supporting documents must describe the actual number user and match one another.

Create a Regulatory Bundle if Twilio requires one

Not every number requires the same approval. Check Twilio’s country and number requirements for the country, number type, and end-user type you plan to use.

When a Regulatory Bundle is required:

In Twilio Console, open Phone Numbers → Regulatory Compliance → Bundles.
Select Create a Regulatory Bundle.
Choose the phone number’s country and type.
Choose Business or Individual as the end user.
Enter the requested identity and address information exactly as it appears on the documents.
Upload each requested supporting document.
Review the intended-use information and submit the Bundle for review.
Wait until Twilio marks the Bundle approved before assigning it to a number.

Twilio may also require an approved address. After buying the number, open its Regulatory Information section and assign the approved Bundle and address when requested. An approved Bundle is not enough if it has not been mapped to the relevant phone number.

Reviews commonly take several business days and can take longer in some regions. Do not schedule a production launch until the number itself shows a compliant or otherwise usable status. See Twilio’s Console regulatory-compliance walkthrough .

4. Buy a voice-capable Twilio number

The purchased number is what customers dial and what recipients can see on supported outbound calls.

In Twilio Console, open Products & Services → Numbers & Senders → Phone Numbers.
Select Set up a new phone number. In some Console layouts, use Phone Numbers → Manage → Buy a number.
Choose the country and number type.
Require the Voice capability in the search filters.
Review the number’s capabilities, activation requirements, recurring price, and usage conditions.
Select the number and complete the purchase.
Assign an approved Regulatory Bundle and address if Twilio requests them.
Open Phone Numbers → Manage → Active numbers and confirm that the number is active in the intended project or subaccount.

You do not need to create an Elastic SIP Trunk or manually configure an incoming voice webhook for this connection. Versafy configures the active voice routing when you assign the number to an Inbound Call Flow.

See Twilio’s current number-purchase guide if its Console labels differ.

5. Copy the live Twilio credentials

Versafy uses the credentials to verify the account, display its phone numbers, and manage the voice routing you approve.

Open the Twilio Console Dashboard.
Find Account Info or open the Workbench panel.
Copy the Account SID. A live Account SID normally begins with AC.
Reveal and copy the Auth Token.
Confirm once more that these credentials belong to the project or subaccount that owns the phone number.

Use the live Account SID and Auth Token—not test credentials, an API key, a SIP password, or credentials from a different subaccount. Twilio’s Workbench guide shows where the values appear in the current Console.

Treat the Auth Token like a password. Do not put it in documentation, chat messages, screenshots, email, or support tickets. If it may have been exposed, rotate it in Twilio and immediately update the connection in Versafy.

6. Connect Twilio in Versafy

Connecting the account makes all eligible numbers owned by that Twilio project or subaccount visible in Versafy.

Navigation: Open Phone → Phone Numbers.

Find the Connect Twilio when you’re ready banner.
Select Connect Twilio.
Paste the Account SID.
Paste the Auth Token.
Select Save.
Confirm that the page shows Twilio Connected and, when available, the correct Twilio account name.
Select the Numbers tab.
If the new number is not visible yet, select Refresh once.

Versafy supports one directly connected Twilio account per workspace. Connecting replacement credentials changes that connection; it does not add a second Twilio account.

7. Configure inbound and outbound use

Inbound and outbound calling are enabled separately so each number is used only for the customer experience you intend.

Assign the number to an inbound flow

An inbound assignment determines what happens when a customer calls the number—for example, answering with a Voice Agent, ringing operators during business hours, or recording voicemail after hours.

Open Phone → Phone Numbers → Inbound Call Flows.
Create and activate the caller journey you need. See Inbound Call Flows.
Return to the Numbers tab.
Find the Twilio number.
Under Connect to an Inbound Call Flow, select the active flow.
Wait until the number shows Inbound Call Flow Attached and the intended flow name.

Voice-routing ownership: While an inbound flow is attached, Versafy controls the number’s voice, fallback, and call-status routing in Twilio. Disconnecting the number clears that routing. If the number previously belonged to another application, record its earlier configuration before attaching it.

Unlike an External SIP number, a directly connected Twilio number can use standard flows with operators, schedules, announcements, handover paths, and voicemail, subject to your workspace permissions and plan.

Enable outbound calling

Outbound enablement makes the number selectable as the caller number for Voice Agent calls and eligible Campaigns.

Find the number under Phone → Phone Numbers → Numbers.
Select Enable outbound calling.
Wait until the row shows Outbound enabled.
If you plan to call internationally, review Twilio’s Voice geographic permissions and enable only the countries your organization needs.

8. Test both call directions

Testing confirms that the Twilio account, number, flow, and Voice Agent are connected correctly before customers depend on them.

Test inbound calls

Call the Twilio number from a separate phone.
Confirm that the correct greeting or first flow step starts.
Test each important route, including operator, schedule, handover, and voicemail branches when used.
Open Phone → Call Logs & Recordings and confirm that the call appears.

Test outbound calls

Open Phone → Voice Agents.
Find the active agent and select Make a call.
Select the connected Twilio number as the caller number.
Enter the destination in international E.164 format, including + and the country code.
Answer the call and verify two-way audio and the displayed caller number.
Check Call Logs & Recordings before retrying a failed or unclear attempt.

Manage or remove the connection

Open Phone → Phone Numbers, then select Twilio Connected in the page header to view its settings.

Use Rotate or replace credentials after changing the Auth Token or intentionally moving the workspace to another Twilio account.
Use Remove Integration only when you intend to disconnect Twilio from the workspace.

Removing the integration also removes Versafy phone-number configurations, inbound call flows, and operator groups associated with it. Voice Agents will no longer receive calls until telephony is configured again. Removing the Versafy connection does not release the phone number from your Twilio account.

Troubleshooting

Versafy rejects the credentials

Confirm that the Account SID starts with AC, the Auth Token is the current live token, and both values come from the same Twilio project or subaccount. Copy them again without leading or trailing spaces.

The Twilio number does not appear in Versafy

Confirm that the number is active in the connected project or subaccount and supports Voice. Under Phone → Phone Numbers → Numbers, select Refresh once. If it remains absent, open Twilio Connected and confirm the displayed account before replacing credentials.

Twilio will not let you buy or activate the number

Review the country, number type, end-user type, account balance, and regulatory requirements. Confirm that the correct Bundle and address are approved and assigned to the number. Use Twilio Support for a rejected or unusually delayed regulatory review.

Incoming calls do not follow the intended route

Confirm that the flow is active and the number row shows Inbound Call Flow Attached with the correct flow name. If Twilio’s number configuration was edited after assignment, reconnect the flow in Versafy and test again.

The number is unavailable for outbound calls

Confirm that it supports Voice and shows Outbound enabled. Check the Voice Agent status, destination format, Twilio balance, trial restrictions, and geographic permissions.

A trial call reaches only some destinations

Twilio trial accounts restrict calls to verified recipients and impose other country and usage limits. Upgrade the account for production and review Twilio’s current trial restrictions before troubleshooting Versafy settings.