Send SMS API
SMS Balance API
Go Back

# 🧾 SMS API Documentation – Send SMS

## 📍 Step 1: API Endpoint

Use this URL to call and send an SMS.

- Method: GET
- Endpoint:

                                          https://yourdomain.com/api/send_sms.php

  🔐 Important: All parameters must be passed as query string parameters in the URL.

## 🧾 Step 2: Required Parameters

You need to provide all five parameters in the URL:

Parameter | Type | Required | Description
--- | --- | --- | ---
user_name | string | ✅ | Your account username
api_key | string | ✅ | Your sms api_key. It can be seen by clicking the key(🔑) icon on your sms page
sender_id | string | ✅ | The whitelisted sender ID linked to your account
message | string | ✅ | The message content (max 160 characters per SMS part)
phone_number | string | ✅ | The recipient's phone number(s), comma-separated

### 🧪 Example: Sending a Single SMS

#### Description

You're sending "Hello John, your package has arrived." to one phone number.

#### Sample URL

                                GET https://yourdomain.com/api/send_sms.php?user_name=john_doe&api_key=abc12345&sender_id=MyBrand&message=Hello+John,+your+package+has+arrived.&phone_number=237650000001

### 🧪 Example: Sending to Multiple Phone Numbers

You're sending the same message to two or more recipients.

                                GET https://yourdomain.com/api/send_sms.php?user_name=john_doe&api_key=abc12345&sender_id=MyBrand&message=Hello+Team,+meeting+starts+at+10AM.&phone_number=237650000001,237650000002

💡 Separate multiple phone numbers with commas (,) and no spaces.

## 🧾 Step 3: Message Segmentation

Each SMS message is calculated based on character length:

- 1 SMS part = up to 150 characters
- Messages longer than 150 characters will consume multiple SMS units

### Example:

- Message of 130 characters → 1 SMS
- Message of 300 characters → 2 SMS
- Message of 500 characters → 4 SMS

The system automatically calculates the correct number of SMS parts and deducts your balance accordingly.

## 🧾 Step 4: Response Format

After sending the SMS, your API will respond with a JSON object describing what happened. Here’s how to interpret it.

### 📤 Example Successful Response

                                {
                                "success": true,
                                "sent": 2,
                                "failed": 0,
                                "remaining_balance": 98,
                                "successful_numbers": [
                                    "237650000001",
                                    "237650000002"
                                ],
                                "failed_numbers": []
                                }

### Explanation:

Field | Type | Description
--- | --- | ---
success | boolean | Indicates if the API request was valid and processed successfully
sent | integer | Number of phone numbers the message was successfully sent to
failed | integer | Number of failed message deliveries (e.g. invalid number or API failure)
remaining_balance | integer | SMS balance left in your account after this request
successful_numbers | array | List of recipient numbers that were successful
failed_numbers | array | List of numbers that failed (can retry later)

## 🧾 Step 5: Error Handling

If the request has an issue (missing fields, wrong credentials, etc.), the API will return a clear JSON error response with an appropriate HTTP status code.

### ❌ Common Error Responses

#### 🔒 Missing Parameters

                                {
                                "error": "All URL parameters (user_name, api_key, sender_id, message, phone_number) are required."
                                }

Check that you're including all 5 required fields.

#### 🔐 Incorrect Username or api_key

                                {
                                "error": "Authentication failed. Incorrect api_key."
                                }

The username exists, but the api_key is wrong.

#### 🚫 Sender ID Mismatch

                                {
                                "error": "Sender ID not associated with this account"
                                }

The sender_id used doesn't belong to your account.

#### 💬 Insufficient SMS Balance

                                {
                                    "success": true,
                                    "sent": 1,
                                    "failed": 1,
                                    "remaining_balance": 0,
                                    "successful_numbers": ["237650000001"],
                                    "failed_numbers": ["23765000000"],
                                }

Only 1 message was sent; the other was skipped due to low balance.

#### 🔄 Wrong HTTP Method

                                {
                                "error": "Only GET requests are allowed"
                                }

Make sure you're using GET, not POST or PUT.

#### 🚫 OTP Not permitted

                                {
                                "error": "This sender_id is not whitelisted for OTP"
                                }

Make sure your user_name is OTP whitelisted.

# 📘 SMS Balance Check API Documentation

This API allows verified clients to check their remaining SMS balance securely via a simple GET request.

## 🔐 Authentication

- Clients authenticate using a combination of:
- user_name
- api_key
- API responses are in JSON format.
- All requests must use HTTPS.

## 📡 Endpoint

                        GET https://yourdomain.com/api/check_balance.php

## 📥 Request Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
user_name | string | ✅ | Your account username (case-sensitive)
api_key | string | ✅ | Your plain-text api_key (will be verified securely)

## ✅ Successful Response

                        {
                            "success": true,
                            "user_name": "john_doe",
                            "sms_balance": 250,
                        }

### Fields:

- success: Always true for valid requests.
- user_name: The username of the authenticated API client.
- sms_balance: Remaining number of SMS units on your account.

## ❌ Error Responses

HTTP Code | Error Message | Meaning
--- | --- | ---
400 | Both user_name and api_key are required | Missing one or both required query parameters
401 | Authentication failed. User not found. | The username is invalid or does not exist
401 | Authentication failed. Incorrect api_key. | api_key does not match stored credentials
405 | Only GET requests are allowed | The request method is not GET

## 🧪 Example Request – cURL

                        curl -X GET "https://yourdomain.com/api/check_balance.php?user_name=john_doe&api_key=abc12345"

## 💻 Example – JavaScript (Browser)

                        fetch ("https://yourdomain.com/api/check_balance.php?user_name=john_doe&api_key=abc12345")
                            .then(res => res.json())
                            .then(data => console.log("Balance:", data.sms_balance))
                            .then(err => console.error("Error:", err));