Get Set Up: Migrate to Twilio SMS API
Step 1: Create and Configure Your Twilio Account
Before diving into migration, take a few preparatory steps to set yourself up for success:
Sign Up for a Twilio Account: Begin by creating a Twilio account (if you haven’t already).
- Business Verification & Compliance: Prepare your business details for Carrier compliance requirements. Twilio uses a centralized Trust Hub for verifying customers (Know Your Customer) and registering messaging use cases. Create a Primary Business Profile in the Trust Hub, which streamlines compliance across all channels. For ISV customers, use this guide to set up your customers for success on 10DLC numbers. For U.S. messaging, you’ll need to register your Brand and Campaign for A2P 10DLC (10-digit long codes) to comply with carrier rules. Twilio’s onboarding wizard will guide you through each step, making it as easy as possible to provide the required information. If you plan to use a Toll-Free number, be ready to submit a brief use-case description for verification.
Step 2: Install the Twilio SDK for Your Language
Twilio provides SDKs for all major programming languages using our quickstart guides.
Node.js Example:
npm install twilio
Step 3: Start Moving Your Numbers
Short Code:
Due to the carrier compliance requirements for short codes, short code numbers follow a separate migration process; please refer to the US Short Code Migration Process and FAQ
10DLC and Toll Free
For 10DLC and Toll Free: Port Your Phone Numbers to Twilio: You can bring over your existing long codes and toll-free numbers to Twilio through a porting process. Start by gathering your current provider account details (account number, PIN if applicable, and a copy of the latest bill if required for verification). In the Twilio Console, initiate a port request for each number or batch of numbers. Twilio will coordinate with your current provider and the carriers to transfer the numbers. A standard port for a small quantity of numbers typically takes about 1-2 weeks (excluding public holidays) once paperwork is submitted. Larger bulk ports (50+ numbers) may take 4–6 weeks.
Twilio will provide an estimated completion date, to avoid any business impact. During the interim, your numbers continue to work on your current provider until the moment they switch to Twilio, so there’s low to no downtime. (You can also set up a temporary Twilio number for testing while you wait.) Additionally, you can leverage our Porting API to automate port request submission for each number.
Ensure you complete the necessary compliance setup for the number types you are using.
For A2P 10DLC, complete Brand and Campaign registration. Guides are available based on your business type.
Direct customer: See Am I direct or ISV? for context)
ISV customer: Companies that resell Messaging as part of a software/service offering – see Am I direct or ISV? for context
Once your 10DLC numbers are ported-in, you may associate them to your registered Campaign by adding them to the Messaging Service you created during that process.
For Toll-Free numbers, after your port request has been fully completed, initiate your Toll-Free verification. You must complete verification even if you have already done so previously.
If you also send or receive Voice calls on your numbers, we strongly advise setting up SHAKEN/STIR and Voice Integrity as well – it’s free of cost and helps bolster your call reputation with carriers and reduce the risk of “Spam Likely” labeling.
Step 4: Replace Bandwidth Messaging Code with Twilio
BEFORE: Code Example
AFTER: Twilio Programmable Messaging
NOTE: Twilio handles message sending throughput and queuing on your behalf, so you don’t have to worry about it – if you have implemented message throttling or queueing in your existing code, you can remove that when you make the switch to Twilio.
