Skip to main content
SMS (Short Message Service) is the most universal messaging channel, reaching virtually any mobile phone without requiring an internet connection or app installation.

​
When to Use SMS

  • Verification codes: OTPs, 2FA
  • Transactional alerts: Order confirmations, shipping updates
  • Time-sensitive notifications: Appointment reminders
  • Universal reach: When you need to reach users without smartphones

​
Basic SMS Example

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+56912345678",
    "text": "Your verification code is 123456",
    "channel": "sms"
  }'

​
Using Templates

For consistent messaging, use templates: 
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+56912345678",
    "templateId": "tpl_verification",
    "data": {
      "code": "123456"
    },
    "channel": "sms"
  }'

​
SMS Best Practices

​
Message Length

SMS messages are limited to 160 characters (GSM-7 encoding) or 70 characters (Unicode). Longer messages are split into multiple segments.
EncodingSingle SMSConcatenated SMS
GSM-7160 chars153 chars/segment
Unicode70 chars67 chars/segment
Keep messages under 160 characters when possible to avoid multi-segment charges.

​
Character Encoding

GSM-7 supports basic Latin characters. Using emojis, accents, or non-Latin scripts triggers Unicode encoding: 
GSM-7:    "Your code is 123456"          (20 chars, 1 segment)
Unicode:  "Your code is 123456 ✓"         (22 chars, 1 segment)
Unicode:  "Tu código es 123456"           (19 chars, 1 segment, 'ó' triggers Unicode)

​
Sender ID

Some countries support alphanumeric sender IDs (e.g., “ZAVU” instead of a phone number). Configure this in your sender settings.
Alphanumeric sender IDs cannot receive replies. Use a phone number if you need two-way SMS.

​
Handling Delivery Status

SMS delivery is asynchronous. Check status via:

​
1. Polling

curl https://api.zavu.dev/v1/messages/msg_abc123 \
  -H "Authorization: Bearer zv_live_xxx"
Set up webhooks to receive real-time delivery updates: 
{
  "event": "message.delivered",
  "data": {
    "messageId": "msg_abc123",
    "status": "delivered",
    "timestamp": "2024-01-15T10:30:05.000Z"
  }
}
See Webhooks Guide for setup instructions.

​
Common SMS Errors

Error CodeDescriptionSolution
30003Unreachable destinationInvalid number or phone off
30004Message blockedContent filtered by carrier
30005Unknown destinationNumber doesn’t exist
30006Landline destinationCannot send SMS to landlines
30007Carrier violationMessage rejected by carrier

​
Compliance

SMS messaging is regulated. Ensure you have consent before sending messages.

​
Requirements

  • Opt-in consent: Users must explicitly agree to receive SMS
  • Opt-out mechanism: Include instructions to unsubscribe (e.g., “Reply STOP to unsubscribe”)
  • Business identification: Identify your business in the message
  • Time restrictions: Avoid sending during quiet hours (typically 9 PM - 9 AM local time)

​
Example Compliant Message

[YourBrand] Your order #12345 has shipped! Track: https://track.co/abc

Reply STOP to unsubscribe