📱 SMS API

Overview

The SMS API allows you to send text messages to any mobile number worldwide. Messages are charged based on your account's configured rate per SMS unit.

Send Single SMS

Request Body

Example Request

curl -X POST https://uconect.ulibtech.org/api/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "number": "+256700000000",
    "message": "Hello! Your verification code is 123456.",
    "senderid": "MYAPP",
    "priority": 1
  }'

const response = await fetch('https://uconect.ulibtech.org/api/sms/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    number: '+256700000000',
    message: 'Hello! Your verification code is 123456.',
    senderid: 'MYAPP',
    priority: 1
  })
});

const result = await response.json();
console.log(result);

import requests

url = 'https://uconect.ulibtech.org/api/sms/send'
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
}
data = {
    'number': '+256700000000',
    'message': 'Hello! Your verification code is 123456.',
    'senderid': 'MYAPP',
    'priority': 1
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

 '+256700000000',
    'message' => 'Hello! Your verification code is 123456.',
    'senderid' => 'MYAPP',
    'priority' => 1
);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-API-Key: your_api_key_here'
));

$result = curl_exec($ch);
curl_close($ch);

print_r(json_decode($result));
?>

Success Response

{
  "success": true,
  "message_id": "msg_1234567890",
  "cost": 0.35,
  "status": "sent",
  "response": {
    "Status": "OK",
    "MsgFollowUpUniqueCode": "msg_1234567890"
  }
}

Error Response

{
  "error": "Validation failed",
  "details": [
    "Invalid phone number format"
  ]
}

Send Bulk SMS

Request Body

Message Object Fields

Example Request

curl -X POST https://uconect.ulibtech.org/api/sms/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "sender_id": "PROMO",
    "messages": [
      {
        "number": "+256700000000",
        "message": "Special offer just for you!"
      },
      {
        "number": "+256700000001",
        "message": "Get 50% off today!",
        "senderid": "DEALS"
      },
      {
        "number": "+256700000002",
        "message": "Limited time offer - Shop now!"
      }
    ]
  }'

Success Response

{
  "success": true,
  "batch_id": "batch_1703501234567",
  "total": 3,
  "sent": 3,
  "failed": 0,
  "cost": 1.05,
  "response": {
    "Status": "OK"
  }
}

Schedule SMS

Request Body

Example Request

curl -X POST https://uconect.ulibtech.org/api/sms/schedule \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "number": "+256700000000",
    "message": "Reminder: Your appointment is tomorrow at 10 AM",
    "senderid": "CLINIC",
    "schedule_time": "2024-12-26T09:00:00Z",
    "priority": 1
  }'

Success Response

{
  "success": true,
  "message_id": "sched_1703501234_abc123",
  "scheduled_for": "2024-12-26T09:00:00.000Z",
  "cost_reserved": 0.35,
  "note": "Credits have been reserved. SMS will be sent at scheduled time."
}

View SMS Outbox

Query Parameters

Example Request

curl -X GET "https://uconect.ulibtech.org/api/sms/outbox?status=sent&limit=10" \
  -H "X-API-Key: your_api_key_here"

Response

{
  "success": true,
  "logs": [
    {
      "id": 1,
      "message_id": "msg_1234567890",
      "recipient": "+256700000000",
      "message": "Hello! Your verification code is 123456.",
      "sender_id": "MYAPP",
      "status": "sent",
      "cost": 0.35,
      "priority": 2,
      "sent_at": "2024-12-25T10:30:00Z",
      "created_at": "2024-12-25T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

View Failed SMS

Validation Rules

Phone Number

• Must include country code (e.g., +256 for Uganda)
• 10-15 digits after country code
• Format: +[country_code][number]
• Example: +256700000000

Message Content

• Minimum: 1 character
• Maximum: 1600 characters
• 160 characters = 1 SMS part
• Longer messages split into multiple parts

Sender ID

• Maximum: 11 characters
• Alphanumeric only (A-Z, 0-9, spaces)
• No special characters
• Recommended: Use your brand name

Priority Levels

• 0 - High priority (immediate delivery)
• 1 - Above normal
• 2 - Normal (default)
• 3 - Below normal
• 4 - Low priority (best effort)

Common Error Responses

Insufficient Credits

{
  "error": "Insufficient credits",
  "required": 0.35,
  "available": 0.10
}

Validation Failed

{
  "error": "Validation failed",
  "details": [
    "Recipient number is required",
    "Message cannot be empty"
  ]
}

Batch Limit Exceeded

{
  "error": "Batch limit exceeded. Maximum 100 messages allowed."
}

Invalid Schedule Time

{
  "error": "Schedule time must be in the future",
  "provided": "2024-12-24T10:00:00Z",
  "current": "2024-12-25T10:30:00Z"
}

💡 Best Practices