Twilio Setup: Purchasing and Connecting a Virtual Number

To send and receive SMS through Twilio, you need a Twilio account, a phone number with the right capabilities, and a Twilio channel connected to your RapidPro.app workspace. This guide walks you through buying a number, connecting it correctly, and troubleshooting the most common Twilio delivery and compliance errors.
Reading time
7–10 min read
Category
Channels
Updated on
Updated on: 22/12/2025

Connect a Twilio number for SMS sending and receiving

If you just need the essentials, follow this quick path:

  1. Create (or sign in to) your Twilio account
  2. Buy a Twilio number with the right capabilities
  3. Add the Twilio channel in RapidPro.app (SID + Auth Token + number)
  4. Test inbound + outbound messages (and check logs)
  5. Use a Twilio Messaging Service only if you need scale/pooling

This setup is the fastest way to get “one Twilio number → one RapidPro.app channel” working reliably.

Step-by-Step Process

1
Create (or sign in to) your Twilio account

  1. Open your Twilio Console.
  2. Create an account or sign in to an existing one.
  3. Locate your Account SID and Auth Token (you’ll use these in RapidPro.app).

[CAPTURE: Twilio Console dashboard showing where Account SID and Auth Token can be found (blurred).]

⚠️
Warning: Trial accounts often restrict sending/receiving (including “To” number verification). For real testing, use a paid Twilio account and a real Twilio number.

2
Buy a Twilio number (and confirm SMS/MMS capability)

  1. In Twilio, open Phone Numbers.
  2. Go to Manage → Buy a Number.
  3. Use Advanced Search to pick the country you need.
  4. Choose the number type that fits your use case (e.g., toll-free vs local/long code).
  5. Before purchasing, confirm it supports Inbound SMS (and MMS if required).
  6. Purchase the number.

[CAPTURE: Twilio “Buy a Number” screen showing capability filters (SMS/MMS/Voice).]

💡
Tip: If MMS matters (images), verify MMS support before purchase—some number types/regions do not support it.

3
Add the Twilio channel in RapidPro.app

  1. Open Workspace Settings (gear icon).
  2. Go to Channels.
  3. Click + New Channel.
  4. Select Twilio.
  5. Enter your Account SID and Auth Token.
  6. Select the Twilio number you purchased.
  7. Save.

[CAPTURE: RapidPro.app channel setup screen showing Twilio credentials fields and a number dropdown.]

⚙️
Technical Detail: For the common “one number → one channel” setup, RapidPro.app manages the required webhook configuration on the Twilio side through the channel connection process.

⚠️
Warning: Avoid configuring extra messaging webhooks in Twilio for the same number unless you’re intentionally using a Messaging Service or a custom routing setup—misconfiguration can break inbound delivery.

4
Test outbound and inbound messaging

Validate the integration with a simple end-to-end test:

  1. Create a simple flow with a Send Message step.
  2. Start the flow for a real contact number and confirm the SMS is delivered.
  3. Reply to the SMS from the phone and confirm RapidPro.app receives the inbound message (Messages / contact history).
  4. If a send fails, open message logs and capture the Twilio error code for troubleshooting.

[CAPTURE: Messages view showing a sent SMS, a reply received, and a link to message delivery/log details.]

💡
Tip: Test with one contact first before running broadcasts—this confirms capabilities, compliance status, and routing.

5
Know when you should use a Twilio Messaging Service

A Twilio Messaging Service is optional. You typically need it only when you want to:

  • Send at scale using multiple numbers (a pool)
  • Apply shared sending policies across many numbers
  • Manage advanced sending behaviors (depending on your Twilio setup)

If you’re using a single number for one workspace, connecting that number directly is usually enough.

[CAPTURE: Twilio Messaging Service settings page (optional), shown as a separate configuration from a single phone number.]

Common Issues & Quick Fixes

Messages fail and I need details

Problem: A send fails, but the cause isn’t obvious.

Fix:

  • Open the send/message logs for the failed message and locate the Twilio error code.
  • Use the error code details to identify the exact resolution path (compliance, permissions, number type, destination format).
  • Re-test with one contact after applying the fix.
30034 — US A2P 10DLC: message from an unregistered number

Problem: US messaging compliance blocks sending from your number.

Fix:

  • Complete the required A2P 10DLC registration in your Twilio dashboard.
  • Confirm your brand/campaign status is approved (or in the required state for your use case).
  • Retry sending after registration is complete.
21608 — The “To” phone number is not verified for this account

Problem: Sending is blocked because the destination is not allowed for the account state (commonly trial accounts).

Fix:

  • Upgrade to a paid Twilio account.
  • If Twilio still requires destination verification for your account state, verify the destination number in Twilio.
  • Re-test sending.
30006 — Landline or unreachable carrier

Problem: The destination number can’t receive SMS.

Fix:

  • Confirm the contact’s number is a mobile line that supports SMS.
  • Check country code and formatting (E.164 format is recommended).
  • If you’re sending internationally, confirm your Twilio number/support covers that destination.
Inbound SMS arrives in Twilio but not in RapidPro.app

Problem: Twilio receives replies, but RapidPro.app doesn’t show them.

Fix:

  • Confirm the Twilio number is connected to the correct RapidPro.app workspace/channel.
  • Avoid conflicting webhook settings on the Twilio number (especially if you also configured a Messaging Service).
  • Send a fresh inbound test message and re-check Messages / contact history.

Related Resources
Country List: Twilio Supported Two-Way SMS
SMS Optimization: Configuring a Twilio Messaging Service
Compliance: Managing Opt-Outs (STOP, QUIT)
Quick Guide: How to Add a New Channel to Your Workspace
Channel Priority: Managing a Contact’s Preferred Channel