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));