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:

Week	Daily Volume
1	100 messages
2	500 messages
3	2,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:

Stop sending immediately
Send a confirmation: “You have been unsubscribed. Reply START to resubscribe.”
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:

Region	Quiet Hours
US (TCPA)	9 PM – 8 AM local time
EU (GDPR)	Follow local telecom regulations
Turkey	8 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:

Encoding	Characters 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

Code	Action
`INVALID_PHONE_NUMBER`	Remove from contact list; do not retry
`RECIPIENT_OPTED_OUT`	Remove from send list immediately
`RATE_LIMITED`	Wait for `retry_after` seconds and retry
`TEMPLATE_NOT_APPROVED`	Check template status in dashboard
`MESSAGE_SEND_FAILED`	Retry with backoff; escalate after 3 failures
`CHANNEL_UNAVAILABLE`	Try 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 Case	Recommended Channel	Why
OTP / 2FA	SMS	Universal reach, no app required
Order updates	WhatsApp or SMS	Rich media on WhatsApp, fallback to SMS
Marketing campaigns	WhatsApp, RCS, Email	Rich content, higher engagement
Support conversations	WhatsApp, Web Chat	Async, supports media and threading
Transactional alerts	Email + SMS	Email for detail, SMS for urgency
Voice notifications	Voice API	Time-sensitive alerts, confirmation

Implement Channel Fallback

For critical messages, configure cross-channel fallback at the organization level rather than per-request. Once configured, every send on the primary channel transparently retries the next channel in the chain when the primary delivery fails — no per-call flag required.

Open Settings → Channels → Cross-Channel Fallback on the dashboard.
Add a rule, e.g. Primary: WhatsApp → Fallback: SMS. Chains of 2+ channels are supported (RCS → WhatsApp → SMS); each fallback fires only when the previous one exhausts its retries or returns a hard, non-retryable error.
Save. The fallback takes effect on the next send.

// The send body itself does NOT carry a `fallback` field — fallback
// behaviour is driven by the org-level cross_channel_fallback configuration.
await orbit.messages.send({
  to: '+14155552671',
  channel: 'whatsapp',
  body: 'Your package has been delivered.',
})

When the primary channel chain (WhatsApp providers) exhausts its retries and returns a non-retryable failure, the router advances to SMS automatically and applies the recipient’s opt-out + DNC checks against the new channel before delivery.

Performance

Use Webhooks Instead of Polling

Subscribe to delivery status webhooks rather than polling GET /api/v1/messages/{id}:

curl -X POST https://api.orbit.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://api.orbit.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.

​Messaging Best Practices

​Deliverability

​Use E.164 Phone Number Format

​Register for 10DLC (US)

​Warm Up New Numbers

​Monitor Delivery Rates

​Compliance

​Always Get Consent

​Honor Opt-Outs Immediately

​Include Required Disclosures

​Follow Quiet Hours

​Content

​Keep SMS Concise

​Personalize Messages

​Use Templates for WhatsApp

​Error Handling

​Implement Retry Logic

​Handle Specific Error Codes

​Clean Your Contact Lists

​Channel Selection

​Implement Channel Fallback

​Performance

​Use Webhooks Instead of Polling

​Batch Operations

Messaging Best Practices

Deliverability

Use E.164 Phone Number Format

Register for 10DLC (US)

Warm Up New Numbers

Monitor Delivery Rates

Compliance

Always Get Consent

Honor Opt-Outs Immediately

Include Required Disclosures

Follow Quiet Hours

Content

Keep SMS Concise

Personalize Messages

Use Templates for WhatsApp

Error Handling

Implement Retry Logic

Handle Specific Error Codes

Clean Your Contact Lists

Channel Selection

Implement Channel Fallback

Performance

Use Webhooks Instead of Polling

Batch Operations