AlieSMS - Developer API Documentation

Introduction

Overview of the AlieSMS API and its metadata.

Software

AlieSMS - Bulk SMS API Documentation

Version

v2.0.0

Getting Started

AlieSMS provides a secure, fast, and scalable RESTful API to integrate bulk SMS capabilities into your applications. The API allows businesses and platforms to initiate message dispatch, check wallet balances, and manage queues.

Prerequisites

To use the API, you must first:

Create an account: Register your business profile at client.aliesms.com.
Top up your wallet: Ensure your account has sufficient funds to process your SMS campaigns.

Live API Base URL: https://developer.aliesms.com

This base URL should be prefixed to all endpoints documented below.

Global Request Headers

All requests made to the AlieSMS API must accept and send JSON. Ensure you include the following headers in your HTTP requests (in addition to your Authorization header later on):

Content-Type: application/json
                    Accept: application/json

Authentication

To access our API, you must first create an account. You will use your account credentials—email and password—to generate a token.

Endpoint: POST /api/token/generate.php

Request Body:

{
  "email": "example@email.com",
  "password": "Pass123#@26"
}

Parameter	Type	Required	Description	Example
`email`	string		Registered account email address	"example@email.com"
`password`	string		Account password	"Pass123#@26"

Response (Success):

{
  "status": "OK",
  "token": "x7K9vM3bL5pR1nQ8wP4jH2tZ6cDyF0nVb"
}

Check Balance

Retrieve the current wallet balance for your account.

Endpoint: GET /api/user/balance.php

Response (Success):

{
  "status": "Success",
  "balance": 15000,
  "currency": "UGX"
}

Create Batch

Queue messages for dispatch. The system automatically calculates cost based on SMS segments and content encoding (GSM vs Unicode/Emoji).

Endpoint: POST /api/message/batch/create.php

Request Body:

{
  "batch_name": "Campaign 001",
  "message_text": "Hello, this is a test! 😊",
  "recipients": "0701234567, 0771234567"
}

Parameter	Type	Description	Example
`batch_name`	string	Name to identify the campaign	"Campaign 001"
`message_text`	string	Content of the SMS message	"Hello, this is a test! 😊"
`recipients`	string	The recipient's phone number or a Comma-separated list of phone numbers	"0741234567" `OR` "0701234567, 0771234567"

Response (Success):

{
  "status": "OK",
  "message": "Messages successfully queued.",
  "smsCount": 1
  "total_recipients": 2
  "MTN": 1
  "AIRTEL": 1
  "duplicates_removed": 0
  "invalid_numbers": []
}

Request Queue

Fetch all messages currently in your personal queue (status = "Pending") waiting to be sent.

Endpoint: GET /api/message/request.php

Response (Success):

{
  "status": "OK",
  "message": "null",
  "details": [
    {
        "messageID": "123", 
        "messageText": "Hello, this is a test! 😊", 
        "phoneNumber": "0701234567" 
        "smsCount": "1" 
        "provider": "AIRTEL" 
    },
    {
        "messageID": "124", 
        "messageText": "Hello, this is a test! 😊", 
        "phoneNumber": "0771234567" 
        "smsCount": "1" 
        "provider": "MTN" 
    }
  ]
}

Delete Message

Cancel a pending message by marking it as Deleted. Only messages with a status of 'Pending' can be Delete.

Endpoint: POST /api/message/delivery/report.php

Request Body:

{
  "message_id": "123",
  "status": "Delete"
}

Parameter	Type	Required	Description	Example
`message_id`	string		Unique ID of the message to delete	"123"
`status`	string		Must be set to "Delete"	"Delete"

Response (Success):

{
  "status": "Success",
  "message": "Message 123 Deleted successfully"
}