← Back to Documentation

SMS Provider (BYOK)

Bring your own Twilio or Telnyx account to send outbound SMS through your A2P 10DLC-registered numbers. No need to buy numbers from Ringback.

Twilio & TelnyxA2P 10DLC ReadyAES-256-GCM Encrypted

📱 What is BYOK?

Bring Your Own Key (BYOK) lets you connect your own Twilio or Telnyx account credentials to Ringback. Instead of buying phone numbers through the platform, you use the numbers you already have registered and 10DLC-compliant. All outbound SMS is sent through your provider account with your branding.

✅ Benefits

  • ✓ Use your existing A2P 10DLC registered numbers
  • ✓ Messages appear from your verified sender ID
  • ✓ Full control over compliance and registration
  • ✓ Use short codes for high-throughput messaging

⚠️ Requirements

  • • A2P 10DLC registration completed (US numbers)
  • • Twilio Account SID + Auth Token, or Telnyx API Key
  • • An SMS-capable phone number or provisioned short code
  • • Active Twilio/Telnyx account with sufficient balance

How to Connect

1

Navigate to SMS Provider Settings

Go to SMS Provider in the sidebar, or visit Settings → SMS Provider.

2

Select Your Provider

Choose Twilio or Telnyx from the provider selector.

3

Enter Your Credentials

Fill in the form with your provider credentials:

For Twilio

  • Account SID — starts with "AC", found in Twilio Console
  • Auth Token — from the same page (encrypted at rest)
  • Phone Number — E.164 format (e.g., +15551234567) or 5-6 digit short code

For Telnyx

  • API Key — from Telnyx Mission Control Portal
  • Phone Number — E.164 format or short code provisioned for SMS
4

Verify & Save

Click Verify & Save. Ringback makes a lightweight API call to your provider to confirm the credentials are valid and the phone number belongs to your account. If successful, the credentials are encrypted with AES-256-GCM and stored securely.

The page shows a "Connected" badge with the verification date once complete. Your outbound SMS will now route through your provider account.

Short Codes vs Long Codes

10DLC Long Code

Standard 10-digit phone number (e.g., +15551234567). Good for moderate volumes, conversational messaging.

  • • Good for local presence
  • • Supports voice + SMS
  • • Requires A2P 10DLC registration
  • • Throughput: ~1 msg/sec (varies by carrier and trust score)

Short Code

5-6 digit shared numbers (e.g., 12345). High throughput, carrier-approved for marketing.

  • • Instant message delivery
  • • Up to 100+ msg/sec throughput
  • • SMS-only (no voice capability)
  • • Also requires A2P registration
  • Note: Short codes are managed at the Twilio/Telnyx level and provisioned to your account there.

Delivery Status Webhooks

Ringback automatically listens for delivery status updates from your provider to track whether messages are sent, delivered, or failed. The webhook URL is:

https://your-domain.com/api/v1/integrations/twilio/webhook

Set this as your messaging webhook URL in the Twilio Console or Telnyx Portal. Ringback verifies request signatures to prevent spoofing.

Common A2P 10DLC Error Codes

When messages fail due to 10DLC restrictions or carrier issues, Ringback surfaces the error code and a recovery suggestion in the message status.

30034

Unregistered A2P Brand/Campaign

Cause: Your number has not completed A2P 10DLC brand or campaign registration.

Fix: Complete brand and campaign registration at console.twilio.com. This is required for all US A2P traffic.

30008

Unknown Destination / Blocked

Cause: The recipient's carrier blocked the message or the number is unreachable.

Fix: Verify the destination number is correct and not a landline. Some carriers block A2P from unregistered numbers.

30007

Message Filtered by Carrier

Cause: The message content triggered spam filtering by the carrier.

Fix: Try rephrasing. Avoid ALL CAPS, excessive punctuation, and URL shorteners.

30005

Unknown Destination Handset

Cause: The destination number may be a landline that cannot receive SMS.

Fix: Confirm the number is a mobile device capable of receiving SMS.

21610

Invalid Sender Number

Cause: The phone number or short code is not provisioned for SMS in your Twilio account.

Fix: Ensure the number is SMS-capable and purchased/verified in your Twilio console.

21211

Invalid Recipient Number

Cause: The 'To' phone number is not in a valid format.

Fix: Ensure the destination number uses E.164 format (+1XXXXXXXXXX).

Disconnecting

You can disconnect your provider at any time from the SMS Provider settings page. This sets your configuration to inactive — credentials are retained but not used. Outbound SMS falls back to the platform default provider.

Go to SMS Provider Settings →