SMS Messaging Guide

Learn how to send SMS messages using the Zend.

Basic SMS Message

Send a simple SMS message to a single recipient:

POST /messages

{
  "to": "+233593152134",
  "body": "Hello! This is a test SMS message.",
  "preferred_channels": ["sms"]
}

Response:

{
  "id": "6884da240f0e633b7b979bff",
  "status": "pending",
  "estimated_cost": 0.02,
  "message": "Message queued for processing"
}

SMS with Sender ID

Use a specific sender ID for your messages:

{
  "to": "+233593152134",
  "body": "Your order has been confirmed!",
  "preferred_channels": ["sms"],
  "sender_id": "RODIN"
}

SMS with Fallback

Send SMS with automatic fallback to WhatsApp if SMS fails:

{
  "to": "+233593152134",
  "body": "Important notification: Your order has been shipped!",
  "preferred_channels": ["sms", "whatsapp"],
  "fallback_enabled": true,
  "delivery_priority": "reliability"
}

SMS with Priority

Set message priority for faster processing:

{
  "to": "+233593152134",
  "body": "URGENT: System maintenance in 30 minutes",
  "preferred_channels": ["sms"],
  "priority": "urgent"
}

Priority levels: low, normal, high, urgent

SMS with Scheduling

Send SMS at a specific time:

{
  "to": "+233593152134",
  "body": "Reminder: Your appointment is in 1 hour",
  "preferred_channels": ["sms"],
  "scheduled_for": "2024-01-15T13:00:00Z"
}

SMS with Webhooks

Receive delivery status updates via webhook:

{
  "to": "+233593152134",
  "body": "Your order has been shipped!",
  "preferred_channels": ["sms"],
  "webhook_url": "https://yourapp.com/webhooks/message-status"
}

SMS Cost Optimization

Optimize for lowest cost:

{
  "to": "+233593152134",
  "body": "Your monthly statement is ready",
  "preferred_channels": ["sms"],
  "delivery_priority": "cost",
  "fallback_enabled": false
}

SMS Message Limits

• Character Limit: 160 characters per SMS
• Concatenated SMS: Up to 10 parts (1600 characters)
• Rate Limit: 100 messages per minute
• Cost: $0.02 per SMS

SMS Best Practices

1. Character Count

// Check your message length
const message = "Your verification code is: 123456";
console.log(`Characters: ${message.length}`);
console.log(`SMS parts: ${Math.ceil(message.length / 160)}`);

2. Phone Number Format

Always use international format:

• ✅ +233593152134
• ✅ 233593152134
• ✅ 0593152134

3. Content Guidelines

• Keep messages concise
• Avoid special characters when possible
• Test with different carriers

4. Error Handling

try {
  const response = await fetch('/messages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+233593152134',
      body: 'Test message',
      preferred_channels: ['sms']
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('SMS failed:', error.message);
  }
} catch (error) {
  console.error('Network error:', error);
}

SMS Status Tracking

Check Message Status

GET /messages/{id}

Response:

{
  "id": "6884da240f0e633b7b979bff",
  "status": "delivered",
  "channel_used": "sms",
  "to": "+233593152134",
  "body": "Your verification code is: 123456",
  "total_cost": 0.02,
  "delivery_attempts": [
    {
      "channel": "sms",
      "status": "delivered",
      "attempted_at": "2024-01-15T10:30:00Z",
      "cost": 0.02
    }
  ],
  "created_at": "2024-01-15T10:29:55Z",
  "sent_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:05Z"
}

Retry Failed SMS

PUT /messages/{id}/retry

Common SMS Errors

Insufficient Credits

{
  "statusCode": 400,
  "message": "Insufficient credits. Required: 0.020, Available: 0.015. Please purchase more credits.",
  "error": "Bad Request"
}

Invalid Phone Number

{
  "statusCode": 400,
  "message": "Invalid phone number format. Please use international format (e.g., +233593152134)",
  "error": "Bad Request"
}

Sender ID Not Approved

{
  "statusCode": 400,
  "message": "Sender ID 'INVALID' is not approved. Please use an approved sender ID.",
  "error": "Bad Request"
}

SMS Templates

Simple SMS Template

{
  "name": "order_confirmation_sms",
  "description": "Simple order confirmation SMS",
  "category": "transactional",
  "variables": [
    {"name": "order_number", "type": "text", "required": true},
    {"name": "tracking_url", "type": "url", "required": true}
  ],
  "channel_variants": [
    {
      "channel": "sms",
      "content": "Order #{{order_number}} confirmed! Track at: {{tracking_url}}"
    }
  ]
}

Using SMS Template

{
  "to": "+233593152134",
  "body": "Order confirmation",
  "template_id": "123456789123412",
  "template_params": {
    "order_number": "ORD-2024-001",
    "tracking_url": "https://track.yourapp.com/ORD-2024-001"
  },
  "preferred_channels": ["sms"]
}