Complete Bandwidth SMS Cheat Sheet

Introduction to Bandwidth SMS

Bandwidth is a Communications Platform as a Service (CPaaS) provider that offers programmable SMS messaging capabilities through its API. Bandwidth SMS enables businesses to:

• Send and receive SMS/MMS messages programmatically
• Provision and manage phone numbers
• Build automated messaging workflows
• Implement two-factor authentication
• Create customer notification systems
• Deploy messaging at scale with carrier-grade reliability

Unlike many SMS providers, Bandwidth owns and operates its own nationwide network, giving direct access to carriers with improved reliability and competitive pricing.

Core Bandwidth SMS Concepts

Key Components

Message Types

• SMS (Short Message Service): Text-only messages up to 160 characters per segment
• MMS (Multimedia Messaging Service): Messages with media attachments (images, audio, video)
• Group Messages: Messages sent to multiple recipients
• Long Messages: SMS messages that exceed 160 characters (automatically segmented)

Number Types

Getting Started with Bandwidth SMS

Account Setup Process

1. Sign up for a Bandwidth account (requires business verification)
2. Create a messaging application in the Bandwidth Dashboard
3. Configure callback URLs for message events
4. Order and provision phone numbers
5. Associate numbers with your messaging application
6. Generate API credentials (token, secret, account ID)
7. Implement API calls in your application

Basic API Authentication

Authorization: Basic {Base64Encoded(username:password)}

Send SMS Message (Basic Example)

// POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages

{
  "from": "+15551234567",
  "to": ["+15557654321"],
  "text": "Hello world!",
  "applicationId": "93de2206-9669-4e07-948d-329f4b722ee2"
}

Receive SMS Callbacks

// Example callback received at your callback URL
{
  "type": "message-received",
  "time": "2023-02-15T16:33:10.220Z",
  "description": "Incoming message received",
  "to": "+15551234567",
  "message": {
    "id": "1589228737852541894",
    "owner": "+15551234567",
    "time": "2023-02-15T16:33:10.220Z",
    "direction": "in",
    "from": "+15557654321",
    "text": "Hello back!",
    "applicationId": "93de2206-9669-4e07-948d-329f4b722ee2"
  }
}

Advanced SMS Features

Rich Messaging Capabilities

Group Messaging Options

• Multiple Recipients: Send to up to 10 recipients per API call
• Group Reply Settings: Configure how replies from group messages are handled
  • Individual replies (default)
  • Group replies (all recipients see all responses)

Delivery Receipt Status Codes

API Reference

Endpoint Structure

• Base URL: https://messaging.bandwidth.com/api/v2/users/{accountId}/
• Message Endpoint: messages
• Media Endpoint: media

Common Request Parameters

Media Handling

1. Upload Media:

   PUT /api/v2/users/{accountId}/media/{mediaName}
   Content-Type: [appropriate MIME type]
   

2. Reference in Message:

   {
     "from": "+15551234567",
     "to": ["+15557654321"],
     "text": "Check out this image",
     "media": ["https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{mediaName}"]
   }
   

3. Supported Media Types:

   • Images: JPEG, PNG, GIF
   • Audio: MP3, WAV
   • Video: MP4
   • Documents: PDF

Compliance and Regulations

Messaging Regulations

10DLC Registration Requirements

1. Brand Registration: Company details, use cases, sample messages
2. Campaign Registration: Campaign details, message volume, opt-in processes
3. Trust Score: Affects throughput and deliverability
4. Compliance Monitoring: Ongoing monitoring of spam complaints and opt-out rates

Opt-Out Handling

• Standard Keywords: STOP, CANCEL, UNSUBSCRIBE, QUIT, END
• Automatic Processing: Bandwidth automatically handles standard opt-out keywords
• Custom Implementation: Implement custom opt-out logic using callbacks

Common Challenges and Solutions

Best Practices and Optimization Tips

Message Content Optimization

• Keep messages concise (under 160 characters when possible)
• Avoid URL shorteners that aren’t well-known
• Limit use of ALL CAPS and excessive punctuation (!!!!)
• Personalize messages when appropriate
• Include clear sender identification
• Provide value in every message

Technical Implementation Tips

• Implement Idempotency: Use message IDs to prevent duplicates
• Handle Delivery Receipts: Process DLRs to confirm delivery
• Implement Queuing: Buffer messages during rate limiting
• Error Handling: Gracefully handle API errors and retries
• Log Management: Track messages for troubleshooting
• Monitoring: Set up alerts for delivery failures or unusual patterns

Security Best Practices

• Use HTTPS for all API communications
• Rotate API credentials periodically
• Implement IP restrictions for API access
• Validate and sanitize all user inputs
• Store phone numbers securely (encrypt sensitive data)
• Use webhook signatures to verify callback authenticity

Performance Optimization

Throughput Maximization

Handling Rate Limiting

• HTTP 429 Response: Indicates rate limiting
• Retry Strategy: Implement exponential backoff
• Batching: Group messages to similar recipients
• Time-of-Day Optimization: Spread non-urgent messages across off-peak hours

Resources for Further Learning

Official Documentation

• Bandwidth Messaging API Docs
• Bandwidth Developer Guides

Code Libraries

• Bandwidth Node SDK
• Bandwidth Python SDK
• Bandwidth Java SDK
• Bandwidth C# SDK
• Bandwidth Ruby SDK

Community Resources

• Bandwidth Developer Forums
• GitHub Examples Repository
• Bandwidth Status Page
• Support Knowledge Base

Contact Support

• Developer Support: support@bandwidth.com
• API Status: status.bandwidth.com
• Sales Inquiries: 855-864-7776

Note: This cheatsheet is for reference purposes only. Always refer to the official Bandwidth documentation for the most up-to-date information, as APIs and features may change.