SMS Notifications

SMS notifications provide immediate, direct alerts for critical monitoring events via text messages. This integration uses Twilio’s SMS service to ensure you receive urgent alerts even when you’re away from your computer.

Quick Setup

1. Set Up Twilio Account

   • Create a Twilio account at twilio.com
   • Verify your phone number
   • Purchase a Twilio phone number
   • Note your Account SID and Auth Token

2. Configure in 9n9s

   • Go to Organization Settings > Notification Channels
   • Click “Add Channel” → “SMS”
   • Enter your Twilio credentials and phone numbers
   • Click “Create Channel”

3. Test SMS Delivery

   • Click “Send Test SMS”
   • Verify message is received on your phone
   • Check message format and sender information

Prerequisites

Twilio Account Requirements

• Twilio Account: Free or paid Twilio account
• Phone Number: Twilio phone number for sending messages
• Verified Recipients: Phone numbers verified in Twilio (trial accounts)
• SMS Capability: Ensure your Twilio number supports SMS

9n9s Requirements

• Organization Admin: Admin role to configure notification channels
• Active Subscription: SMS notifications available on paid plans
• Rate Limits: Understand SMS costs and rate limiting

Setting Up Twilio Integration

Step 1: Configure Twilio Account

1. Create Twilio Account

   • Sign up at console.twilio.com
   • Complete phone number verification
   • Access your Twilio Console Dashboard

2. Get Account Credentials

   • Copy your Account SID from the dashboard
   • Copy your Auth Token (click to reveal)
   • Save these credentials securely

3. Purchase Phone Number

   • Go to Phone Numbers → Manage → Buy a number
   • Choose a number with SMS capabilities
   • Complete the purchase
   • Note the purchased phone number

4. Verify Recipient Numbers (Trial Accounts)

   • Go to Phone Numbers → Manage → Verified Caller IDs
   • Add and verify each phone number that will receive SMS alerts
   • Complete verification process for each number

Step 2: Add SMS Channel in 9n9s

1. Navigate to Notification Channels

   • Log into app.9n9s.com
   • Go to Organization Settings
   • Click “Notification Channels”

2. Create SMS Channel

   • Click “Add Channel” button
   • Select “SMS” from integration types
   • Enter Twilio configuration details

3. SMS Configuration

   • Channel Name: “Critical SMS Alerts” (internal reference)
   • Provider: Twilio (currently the only supported provider)
   • Account SID: Your Twilio Account SID
   • Auth Token: Your Twilio Auth Token
   • From Number: Your Twilio phone number (with country code)
   • To Numbers: Recipient phone numbers (comma-separated)

Step 3: Configure Message Settings

1. Message Format

   • Template: Choose concise, informative message template
   • Character Limit: SMS messages limited to 160 characters
   • Critical Info Only: Include only essential alert information
   • URL Shortening: Automatic shortening of monitor links

2. Delivery Options

   • Rate Limiting: Control SMS frequency to manage costs
   • Quiet Hours: Suppress non-critical SMS during specified times
   • Emergency Override: Allow critical alerts during quiet hours
   • Duplicate Prevention: Avoid sending duplicate messages

Message Format and Limitations

SMS Character Limits

SMS messages have strict character limitations:

• Standard SMS: 160 characters maximum
• Long SMS: Split into multiple messages (additional cost)
• Unicode Characters: Reduce limit to 70 characters
• Cost Consideration: Each message segment costs separately

Message Templates

Critical Alert Template (Short):

🚨 CRITICAL: {{monitor.name}} DOWN
{{incident.duration}}
{{links.short_url}}

Standard Alert Template:

⚠️ {{monitor.name}} is {{monitor.status}}
Duration: {{incident.duration}}
Env: {{tags.environment}}
View: {{links.short_url}}

Recovery Template:

✅ RESOLVED: {{monitor.name}} is UP
Downtime: {{incident.total_duration}}

Smart Message Compression

9n9s automatically optimizes SMS content:

• Abbreviations: Common terms shortened (e.g., “prod” for “production”)
• URL Shortening: Monitor links automatically shortened
• Priority Content: Most important information prioritized
• Multiple Recipients: Same message sent to all configured numbers

Advanced Configuration

Multiple Recipient Management

Configure different phone numbers for different alert types:

sms_routing:
    critical_alerts:
        numbers: ["+1234567890", "+1987654321"] # Primary and backup
        conditions: ["criticality:critical", "status:DOWN"]

    business_hours:
        numbers: ["+1234567890"] # Primary contact only
        conditions: ["time:09:00-17:00"]

    after_hours:
        numbers: ["+1987654321"] # On-call contact
        conditions: ["time:17:00-09:00", "criticality:high"]

Cost Management

SMS notifications can incur costs. Manage expenses with:

1. Rate Limiting

   • Maximum messages per hour
   • Burst protection for incident storms
   • Cost budgets and alerts

2. Smart Filtering

   • Only critical alerts via SMS
   • Use escalation (Slack → Email → SMS)
   • Deduplication to prevent spam

3. Geographic Considerations

   • International SMS costs higher
   • Local Twilio numbers reduce costs
   • Consider regional Twilio services

Twilio Configuration

Production Configuration:

{
    "account_sid": "AC1234567890abcdef1234567890abcdef",
    "auth_token": "your-auth-token",
    "from_number": "+1234567890",
    "to_numbers": ["+1987654321", "+1555123456"],
    "message_service_sid": "MG1234567890abcdef1234567890abcdef",
    "rate_limit": {
        "per_minute": 3,
        "per_hour": 10,
        "per_day": 50
    },
    "quiet_hours": {
        "enabled": true,
        "start": "22:00",
        "end": "08:00",
        "timezone": "America/New_York",
        "emergency_override": true
    }
}

International SMS

For international recipients:

1. Phone Number Format

   • Always include country code (e.g., +44 for UK)
   • Use E.164 format (+1234567890)
   • Verify numbers are SMS-capable

2. Regulatory Compliance

   • Check local SMS regulations
   • Some countries require opt-in consent
   • Consider business vs. personal numbers

3. Cost Considerations

   • International rates vary significantly
   • Consider local Twilio numbers
   • Review Twilio’s international pricing

Security and Compliance

Phone Number Protection

1. Data Security

   • Phone numbers encrypted at rest
   • Secure transmission to Twilio
   • Regular credential rotation

2. Access Control

   • Limit who can configure SMS channels
   • Audit trail for phone number changes
   • Approval process for new recipients

Privacy Considerations

1. Consent Management

   • Obtain explicit consent for SMS alerts
   • Provide opt-out mechanisms
   • Document consent for compliance

2. Data Minimization

   • Include only necessary information
   • Avoid sensitive data in SMS
   • Use monitor IDs instead of detailed info

Regulatory Compliance

1. TCPA Compliance (US)

   • Obtain prior express consent
   • Provide clear opt-out instructions
   • Maintain consent records

2. GDPR Compliance (EU)

   • Lawful basis for processing
   • Data subject rights
   • Cross-border transfer considerations

Troubleshooting

Common Issues

SMS Not Delivered:

1. Twilio Account Issues

   • Verify Account SID and Auth Token
   • Check Twilio account balance
   • Ensure phone number is active

2. Phone Number Problems

   • Verify recipient number format (+1234567890)
   • Check if number is SMS-capable
   • Verify number with carrier

3. Regulatory Blocks

   • Check if carrier blocks automated SMS
   • Verify sender number is not blacklisted
   • Review content for spam triggers

Delayed Delivery:

1. Carrier Delays

   • SMS delivery can take several minutes
   • Network congestion affects delivery
   • International messages may be slower

2. Rate Limiting

   • Check 9n9s rate limiting settings
   • Review Twilio rate limits
   • Verify message queue status

High Costs:

1. Message Optimization

   • Review message templates for length
   • Enable message compression
   • Use abbreviations and short URLs

2. Frequency Control

   • Implement proper rate limiting
   • Use escalation instead of immediate SMS
   • Monitor usage and costs regularly

Twilio Error Codes

Common Twilio error responses:

• 20003: Authentication Error - Invalid credentials
• 21211: Invalid To Number - Phone number format issue
• 21614: To number not verified - Trial account restriction
• 30001: Message Queue Full - Too many messages queued
• 30002: Account Suspended - Twilio account issue

Testing and Validation

Test your SMS integration:

# Test via Twilio API directly
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages.json" \
  --data-urlencode "From=+1234567890" \
  --data-urlencode "To=+1987654321" \
  --data-urlencode "Body=Test message from 9n9s" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN

Best Practices

Message Design

1. Concise Content

   • Lead with most important information
   • Use abbreviations where clear
   • Include only essential details

2. Actionable Information

   • Include monitor name and status
   • Add short URL for details
   • Specify urgency level

Cost Optimization

1. Strategic Use

   • Reserve SMS for critical alerts only
   • Use other channels for warnings
   • Implement escalation chains

2. Message Efficiency

   • Optimize templates for character count
   • Use URL shorteners
   • Avoid Unicode characters when possible

Reliability

1. Multiple Recipients

   • Configure backup phone numbers
   • Use different carriers if possible
   • Test delivery regularly

2. Monitoring SMS Health

   • Track delivery success rates
   • Monitor Twilio account status
   • Set up backup notification methods

Integration Patterns

1. Escalation Chain

   Monitor Failure → Slack (immediate)
                  → Email (2 minutes)
                  → SMS (5 minutes)
                  → Phone Call (10 minutes)

2. Time-Based Routing

   Business Hours: Slack + Email
   After Hours: SMS + Email
   Weekends: SMS only (critical)

---

SMS notifications ensure you receive critical alerts immediately, regardless of your location or internet connectivity. Use them strategically for the most important alerts to balance urgency with cost-effectiveness.