Skip to main content

SMS API

Send SMS messages to 54+ African countries with enterprise-grade reliability, local sender IDs, Unicode support, and real-time delivery tracking.

🚀 Quick Start​

curl -X POST https://api.afriroute.ai/api/v1/sms/send \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+251911234567",
    "from": "AfriRoute",
    "message": "Hello from AfriRoute!"
  }'

📡 Endpoints​

Send SMS​

POST /v1/sms/send

Parameters​

FieldTypeRequiredDescription
tostring/arrayYesRecipient phone number(s) in E.164 format
fromstringYesSender ID (alphanumeric, 3-11 chars)
messagestringYesMessage content (max 1530 chars)
callback_urlstringNoWebhook URL for delivery reports
scheduled_atstringNoISO 8601 timestamp for scheduling

Example Request​

const response = await fetch('https://api.afriroute.ai/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+251911234567',
    from: 'MyBrand',
    message: 'Your OTP is: 123456. Valid for 5 minutes.'
  })
});

const data = await response.json();
console.log(data.message_id); // msg_abc123
import requests

response = requests.post(
    'https://api.afriroute.ai/api/v1/sms/send',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'to': '+251911234567',
        'from': 'MyBrand',
        'message': 'Your OTP is: 123456'
    }
)
print(response.json()['message_id'])

Check Status​

GET /v1/sms/:message_id

Response​

{
  "message_id": "msg_abc123",
  "status": "delivered",
  "to": "+251911234567",
  "from": "MyBrand",
  "sent_at": "2024-03-15T10:30:00Z",
  "delivered_at": "2024-03-15T10:30:05Z"
}

Bulk Send​

POST /v1/sms/bulk
{
  "from": "MyBrand",
  "messages": [
    {"to": "+251911111111", "message": "Hi Alice, your order #123 shipped!"},
    {"to": "+251922222222", "message": "Hi Bob, your payment was received!"}
  ]
}

📊 Response Format​

{
  "status": "success",
  "message_id": "msg_7K8L9M0N",
  "to": "+251911234567",
  "from": "MyBrand",
  "segments": 1,
  "cost": 0.05,
  "currency": "USD",
  "timestamp": "2024-03-15T10:30:00Z"
}

🌍 Coverage​

54+ African countries with tier-1 carrier connections:

  • 🇪🇹 Ethiopia, 🇰🇪 Kenya, 🇳🇬 Nigeria, 🇿🇦 South Africa
  • 🇹🇿 Tanzania, 🇺🇬 Uganda, 🇬🇭 Ghana, 🇷🇼 Rwanda
  • View full coverage →

🔔 Delivery Webhooks​

app.post('/webhooks/sms', (req, res) => {
  const { message_id, status, to, delivered_at } = req.body;

  console.log(`Message ${message_id} to ${to}: ${status}`);

  // Update your database
  await updateMessageStatus(message_id, status);

  res.sendStatus(200);
});

💡 Best Practices​

  • Use registered sender IDs for better deliverability (90%+ vs 60%)
  • Keep messages under 160 characters to avoid multi-part SMS charges
  • Include opt-out instructions for marketing (required in most countries)
  • Handle delivery webhooks for accurate status tracking
  • Use Unicode carefully - reduces character limit to 70 per segment
  • Schedule during business hours for better open rates
  • Validate phone numbers before sending to reduce costs

⚠️ Error Handling​

try {
  const response = await sendSMS({
    to: '+251911234567',
    from: 'MyBrand',
    message: 'Hello!'
  });
} catch (error) {
  if (error.code === 'INVALID_PHONE') {
    console.error('Invalid phone number format');
  } else if (error.code === 'INSUFFICIENT_BALANCE') {
    console.error('Please top up your account');
  }
}

🔒 Security​

  • All API calls use HTTPS encryption
  • Rate limiting: 100 requests/second
  • API keys can be scoped and rotated
  • GDPR compliant data handling

💰 Pricing​

TierPrice/SMSVolume
Standard$0.050-10K
Pro$0.0410K-100K
EnterpriseCustom100K+

View detailed pricing →

📚 Related Resources​

Need help? Contact Support → | View Code Examples →