​
Twilio Integration

Telgea integrates with Twilio to provide SMS messaging capabilities for various user communications. This integration enables sending SMS messages for verification codes, notifications, and alerts to our users.

​
Usage Scenarios

The Twilio integration is used for the following scenarios:
  1. Individual Number Porting
    • Sending verification codes to users during the number porting process (Ensures secure verification of user identity)
  2. Top-up Verification
    • Sending verification codes for top-up transactions (Adds an extra layer of security for financial transactions)
  3. Roaming Notifications
    • Sending SMS alerts to users about roaming charges (Helps users stay informed about their usage and costs)

​
Sender ID Configuration

The integration supports two types of sender IDs:
  • Alphanumeric Sender ID: Used in countries that support this feature
  • Phone Number: Used as a fallback in countries that don’t support alphanumeric sender IDs
    • Uses a dedicated Twilio phone number

​
Environment Configuration

The following environment variables are required for the Twilio integration: 
# Twilio Configuration
TWILIO_ACCOUNT_SID="ACe72faf4080418815065b63d8bfb63508"
TWILIO_AUTH_TOKEN=""
TWILIO_PHONE_NUMBER="+13082482673"
TWILIO_ALPHANUMERIC_SENDER="Telgea"
TWILIO_CALLBACK_URI="/api/v0/integrations/twilio/sms_callback"

​
Callback Functionality

The integration includes a callback API endpoint that receives and logs SMS delivery status updates from Twilio. This helps in:
  • Tracking message delivery status
  • Monitoring failed deliveries
  • Debugging message delivery issues
The callback endpoint is configured at: /api/v0/integrations/twilio/sms_callback

​
Security Considerations

  • The Twilio authentication token should be kept secure and never exposed in client-side code
  • Environment variables should be properly configured in production environments
  • Regular rotation of authentication credentials is recommended
  • Monitor callback logs for any suspicious activity

​
Best Practices

  1. Error Handling
    • Implement proper error handling for failed SMS deliveries
    • Monitor delivery status through callbacks
    • Have fallback mechanisms for critical messages
  2. Rate Limiting
    • Be mindful of Twilio’s rate limits
    • Implement appropriate queuing for bulk messages
  3. Message Content
    • Keep messages concise and clear
    • Include necessary disclaimers where required
    • Follow local regulations regarding SMS content
  4. Testing
    • Test SMS delivery in all supported countries
    • Verify both alphanumeric and phone number sender IDs
    • Test callback functionality regularly

​
Console Access

​
Documentation