Skip to main content

​
Messaging Best Practices

Follow these best practices to maximize deliverability, stay compliant with carrier regulations, and provide the best experience for your recipients.

​
Deliverability

​
Use E.164 Phone Number Format

Always format phone numbers in E.164: +[country code][number] with no spaces, dashes, or parentheses. 
✅ +14155552671
✅ +905551234567
❌ (415) 555-2671
❌ 4155552671

​
Register for 10DLC (US)

All A2P SMS to US numbers requires 10DLC registration. Unregistered traffic will be filtered or blocked.

​
Warm Up New Numbers

When using a new number for high-volume sending, gradually increase volume over 2–4 weeks:
WeekDaily Volume
1100 messages
2500 messages
32,000 messages
4+Full volume

​
Monitor Delivery Rates

Use webhooks to track delivery status in real time. If your delivery rate drops below 95%, investigate immediately:
  • Check for opt-outs and invalid numbers
  • Review carrier feedback for content filtering
  • Verify 10DLC campaign status

​
Compliance

  • Express consent is required for transactional messages
  • Express written consent is required for marketing messages (TCPA requirement)
  • Keep records of when and how each recipient opted in

​
Honor Opt-Outs Immediately

Orbit automatically handles standard opt-out keywords (STOP, CANCEL, UNSUBSCRIBE). When a user opts out:
  1. Stop sending immediately
  2. Send a confirmation: “You have been unsubscribed. Reply START to resubscribe.”
  3. Never message the number again until they re-opt-in

​
Include Required Disclosures

Every first message to a new recipient should include:
  • Your business name
  • Message frequency description
  • “Reply STOP to unsubscribe”
  • “Msg & data rates may apply” (for US)
Acme Corp: Welcome! You'll receive order updates here.
Reply STOP to opt out. Msg & data rates may apply.

​
Follow Quiet Hours

Avoid sending marketing messages outside business hours in the recipient’s timezone:
RegionQuiet Hours
US (TCPA)9 PM – 8 AM local time
EU (GDPR)Follow local telecom regulations
Turkey8 PM – 8 AM (KVKK)

​
Content

​
Keep SMS Concise

SMS has a 160-character limit per segment (70 for Unicode). Longer messages are split into segments and cost more:
EncodingCharacters per Segment
GSM-7 (standard)160 (single) / 153 (multi-part)
Unicode (emoji, non-Latin)70 (single) / 67 (multi-part)
Cost optimization tips:
  • Remove unnecessary whitespace and formatting
  • Use URL shorteners for links
  • Avoid emoji in transactional SMS to stay in GSM-7

​
Personalize Messages

Personalized messages see 2–3x higher engagement: 
❌ "Your order has shipped."
✅ "Hi Jane, your order #12345 has shipped! ETA: March 10."

​
Use Templates for WhatsApp

WhatsApp requires pre-approved templates for business-initiated conversations. Best practices:
  • Keep templates under 1024 characters
  • Use variables for personalization: Hello {{1}}, your order {{2}} is ready.
  • Submit templates in all languages you need upfront
  • Avoid promotional language in transactional templates

​
Error Handling

​
Implement Retry Logic

Use exponential backoff for transient failures: 
const MAX_RETRIES = 3

async function sendMessage(params) {
  for (let i = 0; i < MAX_RETRIES; i++) {
    try {
      return await orbit.messages.send(params)
    } catch (error) {
      if (error.status >= 500 && i < MAX_RETRIES - 1) {
        await sleep(Math.pow(2, i) * 1000)
        continue
      }
      throw error
    }
  }
}

​
Handle Specific Error Codes

CodeAction
INVALID_PHONE_NUMBERRemove from contact list; do not retry
RECIPIENT_OPTED_OUTRemove from send list immediately
RATE_LIMIT_EXCEEDEDWait for retry_after seconds and retry
TEMPLATE_NOT_APPROVEDCheck template status in dashboard
MESSAGE_SEND_FAILEDRetry with backoff; escalate after 3 failures
CHANNEL_UNAVAILABLETry fallback channel or retry later

​
Clean Your Contact Lists

Regularly remove:
  • Invalid numbers (persistent INVALID_PHONE_NUMBER errors)
  • Opted-out numbers (RECIPIENT_OPTED_OUT)
  • Undeliverable addresses (repeated failed status)

​
Channel Selection

Choose the right channel for each use case:
Use CaseRecommended ChannelWhy
OTP / 2FASMSUniversal reach, no app required
Order updatesWhatsApp or SMSRich media on WhatsApp, fallback to SMS
Marketing campaignsWhatsApp, RCS, EmailRich content, higher engagement
Support conversationsWhatsApp, Web ChatAsync, supports media and threading
Transactional alertsEmail + SMSEmail for detail, SMS for urgency
Voice notificationsVoice APITime-sensitive alerts, confirmation

​
Implement Channel Fallback

For critical messages, configure automatic fallback: 
await orbit.messages.send({
  to: '+14155552671',
  channel: 'whatsapp',
  body: 'Your package has been delivered.',
  fallback: {
    channel: 'sms',
    after: 300, // fallback to SMS after 5 minutes if undelivered
  },
})

​
Performance

​
Use Webhooks Instead of Polling

Subscribe to delivery status webhooks rather than polling GET /v1/messages/{id}: 
curl -X POST https://orbit-api.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed"]
  }'

​
Batch Operations

For bulk sends, use campaigns instead of individual API calls: 
curl -X POST https://orbit-api.devotel.io/api/v1/campaigns \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March Newsletter",
    "channel": "sms",
    "audience": { "contact_list_id": "list_abc123" },
    "content": { "body": "Hi {{first_name}}, check out our new features!" },
    "schedule": "2026-03-10T10:00:00Z"
  }'
Need help optimizing your messaging strategy? Contact the Orbit solutions team at solutions@devotel.io.