Introduction
Our SMS APIs are designed to seamlessly integrate with your systems and
applications, supported by our dependable bulk SMS gateway. This document serves as
a comprehensive reference for all the features accessible to you through our APIs
for sending SMS messages.
Getting Started
To be able to send SMS using our APIs, you need to have a
TextCus SMS Messaging account.
Step 1: Create a TextCus SMS Messaging account (if you don't already have one)
- Visit https://sms.textcus.com/signup
to create a new SMS account.
-
Follow the steps provided to activate your account.
Step 2: Reference your API Key
- Log in to your TextCus SMS Messaging account
-
Go to API > API Access or simply visit
https://sms.textcus.com/api/access
-
Copy your API key for future reference
HTTP API (Quick Send)
The HTTP API enables you to send SMS quickly. To send SMS, simply call the
following
URL with the relevant parameters appended to the URL, as shown below:
NB: Please remove the curly bracket in the url when testing
https://sms.textcus.com/api/send?apikey={apiKey}&destination={recipient}&source={Sender}&dlr={0}&type={0}&message={Message}
HTTP Parameters
Below is a list of parameters when issuing a HTTP Request.
Parameters |
Description |
Required |
apikey |
Your generated SMS account API Key |
Required |
type |
It indicates the type of message.
Values for "type" include:
0 : Plain text (GSM 3.38 Character encoding)
1 : Flash (GSM 3.38 Character encoding)
2 : Unicode
3 : Reserved
5 : Plain text (ISO-8859-1 Character encoding)
6 : Unicode Flash
7 : Flash (ISO-8859-1 Character encoding)
|
Required |
source |
The source address that should appear in the message.
- Max Length of 18 if numeric.
- Max Length of 11 if alphanumeric.
To prefix the plus sign (+) to the sender’s address when the message is
displayed on their mobile phone, please prefix the plus sign to your
sender’s address while submitting the message.
Note: You need to URL encode the plus sign.
The SMSC may enforce additional restrictions on this field.
|
Required |
destination |
Recipient phone number
Must be a valid MSIDSN
Must be in the international telephone number format (may or may not
include a plus [+] sign)
symbol. e.g. 233241234567 or +233241234567
Multiple mobile numbers need to be separated by a comma (,)
(the comma should be URL encoded).
|
Required |
dlr |
Indicates whether the client wants a delivery report for this
message.
The values for "dlr" include:
0 : No delivery report required
1 : Delivery report required
|
Required |
message |
The message to be sent. Must be URL encoded. |
Required |
time |
To schedule the message to be sent sometime or date in the future
Format: YYYY-MM-DD HH:MM:SS or UNIX TIMESTAMP
The Scheduled time must be at least 10 minutes ahead of the current time
in UTC
|
Optional |
Sample Codes
// Set Time Zone to ensure messages are delivered on time
date_default_timezone_set('Africa/Accra');
/**
* Function to send SMS using TextCus API
*
* @param string $apiKey Your TextCus API Key
* @param string $recipient Recipient's phone number in international format (e.g., 23324XXXXXXX)
* @param string $sender Sender's name (maximum 11 characters)
* @param string $message The message to send
* @return array API response
*/
function sendSMS($apiKey, $recipient, $sender, $message) {
// Encode the message and sender
$message = urlencode($message);
$sender = urlencode($sender);
// Construct URL parameters
$params = array(
'apikey' => $apiKey,
'destination' => $recipient,
'source' => $sender,
'dlr' => 0,
'type' => 0,
'message' => $message
);
// Prepare URL
$url = 'https://sms.textcus.com/api/send?' . http_build_query($params);
// Initialize cURL session
$curl = curl_init();
// Set cURL options
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
));
// Execute cURL request
$response = curl_exec($curl);
$err = curl_error($curl);
// Check for errors and display response
if ($err) {
$result = array('error' => $err);
} else {
$result = json_decode($response, true);
}
// Close cURL session
curl_close($curl);
return $result;
}
// Example usage
$apiKey = '9OqfypgGXyAUx7422qylPLGrJxz17Nsmq'; // Your TextCus API Key
$recipient = '23324XXXXXXX'; // Recipient's phone number
$sender = 'TextCus'; // Sender's name
$msg = 'This is just a test on TextCus!';
// Send SMS
$response = sendSMS($apiKey, $recipient, $sender, $msg);
// Display response
var_dump($response);
import java.net.*;
import java.io.*;
public class SendSMS {
public static void main(String[] args) {
try {
String API_key = "9OqfypgGXyAUx7422qylPLGrJxz17Nsmq"; // Your TextCus API Key
String message = "This is just a test on TextCus!";
String phone_number = "23324XXXXXXX"; // Recipient's phone number (International format)
String sender_id = "TextCus"; // Sender's ID (11 characters maximum)
String date_time = "2017-05-02 00:59:00";
// Prepare URL
String urlString = String.format("https://sms.textcus.com/api/send?apikey=%s&destination=%s&message=%s&source=%s&dlr=%d&type=%d&time=%s",
API_key, phone_number, URLEncoder.encode(message, "UTF-8"),
sender_id, 0, 0, URLEncoder.encode(date_time, "UTF-8"));
URL url = new URL(urlString);
// Open connection
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
// Read response
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
// Print response
System.out.println(response.toString());
} catch (Exception e) {
e.printStackTrace();
}
}
}
#!/usr/bin/env python
import requests
import urllib.parse
# Defining variables to be used inside function
api_key = '9OqfypgGXyAUx7422qylPLGrJxz17Nsmq' # Remember to put your account API Key here
phone = '23324XXXXXXX' # International format (233) excluding the (+)
message = 'This is just a test on TextCus!'
sender_id = 'TextCus' # 11 Characters maximum
def send_sms(api_key, phone, message, sender_id):
# URL encode the message and sender
msg = urllib.parse.quote(message)
sender = urllib.parse.quote(sender_id)
# Set parameters in the URL to send SMS
url = f'https://sms.textcus.com/api/send?apikey={api_key}&destination={phone}&source={sender}&dlr=0&type=0&message={msg}'
try:
# Send the HTTP request using requests library
response = requests.get(url)
# Check if the request was successful
if response.status_code == 200:
res = response.json()
if res['status'] == '0000':
return 1
else:
return 0
else:
print(f"Error: {response.status_code}")
return 0
except Exception as e:
print(f"Error: {e}")
return 0
# Calling function to send SMS
send_sms(api_key, phone, message, sender_id)
Private Function SendSMS(ByVal EmployeeID As String,
ByVal sTo As String, ' International format (233) excluding the (+)
ByVal sSender As String, ' 11 characters maximum
ByVal MsgBody As String, ByVal MsgType As Integer) As String
Dim result As String = "Sending sms message failed"
Dim SendingResult As Integer = 0
Dim responseFromServer As String = ""
Try
Dim skey As String = "9OqfypgGXyAUx7422qylPLGrJxz17Nsmq"
Dim url As String = "https://sms.textcus.com/api/send?"
Dim sTime As String = Now.ToString("yyyy-MM-dd HH:mm:00")
url &= "apikey=" & skey &
"&destination=" & sTo &
"&message=" & System.Web.HttpUtility.UrlEncode(MsgBody) &
"&source=" & System.Web.HttpUtility.UrlEncode(sSender) &
"&dlr=0" &
"&type=0" &
"&date_time=" & sTime
' VERY IMPORTANT LINE OF CODE
System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
' Create a request for the URL.
Dim request As WebRequest = WebRequest.Create(url)
' If required by the server, set the credentials.
request.Credentials = CredentialCache.DefaultCredentials
' Get the response.
Dim response As WebResponse = request.GetResponse()
' Display the status.
Console.WriteLine(CType(response, HttpWebResponse).StatusDescription)
Dim respd As String = CType(response, HttpWebResponse).StatusDescription.ToString
' Get the stream containing content returned by the server.
Dim dataStream As Stream = response.GetResponseStream()
' Open the stream using a StreamReader for easy access.
Dim reader As New StreamReader(dataStream)
' Read the content.
responseFromServer = reader.ReadToEnd()
' Clean up the streams and the response.
reader.Close()
response.Close()
If responseFromServer.IndexOf("sent successfully") > -1 Then
result = "SMS sent successfully"
SendingResult = 1
End If
' Display the content.
' Console.WriteLine(responseFromServer)
Catch ex As Exception
result &= " - Error: " & ex.Message
SendingResult = 0
End Try
' KEEP A COPY OF THE SMS IN A TABLE FOR RESEND OR RECONCILIATION
Dim sql As String = "INSERT INTO sms_notifications " &
"(Message," &
"Recepient," &
"sStatus," &
"SmsFeedback," &
"InitiatedBy_ID) " &
" VALUES (" &
"'" & MsgBody & "'," &
"'" & sTo & "'," &
"'" & SendingResult & "'," &
"'" & responseFromServer & "'," &
"@EmployeeID)"
Return result
End Function
import 'package:http/http.dart' as http;
Future sendSMS() async {
try {
final apiKey = '9OqfypgGXyAUx7422qylPLGrJxz17Nsmq'; // Remember to put your account API Key here
final recipient = '233xxxxxxxxxxx'; // International format (233) or (+233)
final sender = 'TextCus'; // 11 Characters maximum
final msg = 'This is just a test on TextCus!'; // message to send to recipient
final url = 'https://sms.textcus.com/api/send?apikey=$apiKey&destination=$recipient&source=$sender&dlr=0&type=0&message=$msg'; // append parameters to the right position in the url
final response = await http.get(Uri.parse(url)); // This is a GET HTTP request
// Get response from your request
if (response.statusCode == 200) {
// all good
print('Response is: ${response.body}');
} else {
print('There was an issue sending message: ${response.body}');
}
} catch (e) {
print('An error occurred: $e');
}
}
void main() {
sendSMS();
}
// Node HTTP Implementation
// Using axios for making HTTP requests
const axios = require("axios");
// Requiring the dotenv module for handling environment variables
require("dotenv").config();
// Remember to put your account API Key here
const smsApiKey = "9OqfypgGXyAUx7422qylPLGrJxz17Nsmq";
// 11 Characters maximum
const sender = "TextCus";
// Message to send to recipient
const sms = "This is just a test on TextCus!";
// International format (233) or (+233)
const recipient = "233543895338";
// Encode message for UTF-8 encoding
const smsEncode = encodeURI(sms);
// Encode recipient for UTF-8 encoding
const recipientEncode = encodeURI(recipient);
// Encoding sender string to UTF-8 encoding
const senderEncode = encodeURI(sender);
// Constructing the URL with template literals
const url = `https://sms.textcus.com/api/send?apikey=${smsApiKey}&destination=${recipientEncode}&source=${senderEncode}&dlr=1&type=0&message=${smsEncode}`;
// Using axios to send a GET request
axios.get(url)
.then(response => {
// Message sent successfully
console.log(response.data.message);
})
.catch(error => {
console.error("Error:", error);
});
Send Multiple SMS
$recipient = '23324XXXXXXX,233020XXXXXXX'; //International format (233) excluding the (+)
NB: Place comma(,) after every number as seen above.
Check SMS Balance
This endpoint retrieves your SMS credit balance and bonus:
NB: Please remove the curly bracket in the url when testing
https://sms.textcus.com/api/balance?apikey={apiKey}
Query Parameters
Below is a list of parameters when issuing a HTTP Request.
Parameters |
Description |
Required |
apikey |
Your generated SMS account API Key |
Required |
Retrieve Sender Names
This endpoint retrieves your approved sender names:
NB: Please remove the curly bracket in the url when testing
https://sms.textcus.com/api/sender?apikey={apiKey}
Query Parameters
Below is a list of parameters when issuing a HTTP Request.
Parameters |
Description |
Required |
apikey |
Your generated SMS account API Key |
Required |
Result Format
Result that would be obtained upon successful delivery of message.
[
{
"status": "0000",
"message": "Message sent successfully",
},
]
Parameters |
Type |
Description |
status |
int |
A four digit code which specifies a particular response
message
|
message |
string |
The interpretation of the status code |
Status Codes and
Interpretation
Status Code |
Meaning |
0000 |
Message sent successfully. |
0001 |
Unable to send a message.
Might be due to server error or another reason.
|
0002 |
Insufficient balance |
0003 |
Authentication failed! Invalid API Key. |
0004 |
Empty Message. |
0005 |
The Recipient field is empty. |
0006 |
Invalid Recipient's Phone Number, please use an international format.
e.g., 233
|
0007 |
Invalid Sender ID. Sender ID must not be more than 11
Characters. Characters include white space.
|
0008 |
The Number of contacts exceeds available credit. |
0009 |
Delivery status cannot be empty. |
0010 |
Message type cannot be empty. |
0011 |
Sender name is not registered on the dashboard, only approved
sender names can be used in the API.
Contact Support!
|
Was this page helpful?
Yes
No