Messaging API

This API allows businesses send text messages to their customers across different messaging channels. The API accepts JSON request payload and returns JSON encoded responses, and uses standard HTTP response codes.

Messaging Channels/Routes

ChannelDescription
genericThis channel is used to send promotional messages and messages to phone number not on dnd
dndOn this channel all your messages deliver whether there is dnd restriction or not on the phone number
whatsappThis channel sends messages via WhatsApp

Send message

Endpoint : https://BASE_URL/api/sms/send

Request Type : POST

Body params

OptionsRequiredDescription
api_keyyesstring
Your API key (It can be found on your Termii dashboard.
toyesstring
Represents the destination phone number. Phone number must be in the international format (Example: 23490126727). You can also send to multiple numbers. To do so put numbers in an array (Example: ["23490555546", "23423490126999"]) Please note: the array takes only 100 phone numbers at a time
fromyesstring
Represents a sender ID for sms which can be Alphanumeric or Device name for Whatsapp. Alphanumeric sender ID length should be between 3 and 11 characters (Example:CompanyName)
smsyesstring
Text of a message that would be sent to the destination phone number
typeyesstring
The kind of message that is sent, which is a plain message.
channelyesstring
This is the route through which the message is sent. It is either dnd, whatsapp, or generic
medianoobject
This is a media object, it is only available for the High Volume WhatsApp. When using the media parameter, ensure you are not using the sms parameter
media.urlnostring
The url to the file resource,
media.captionnostring
The caption that should be added to the image,

Media Types

FileSupported Format
ImageJPG, JPEG, PNG
AudioMP3, OGG, AMR
DocumentsPDF
VideoMP4 (Note: WhatsApp currently does not support MP4 files without an audio)
Note: For customers sending messages to Nigeria, DND stands for Do-Not-Disturb and phone numbers with DND settings activated are blocked from receiving messages from the generic route by the Mobile Network Operators. To deliver messages to phone numbers on DND, the Termii DND route needs to be activated on your account. Kindly reach out to our support team.


Note on special Characters: 1 page = 160 characters
Special characters reduces your message count from 160 characters per message to 70 characters per message.
Here are a few of them
; // ^ { }  \ [ ~ ] | € ' ”```


{
     "to": "2347880234567",
     "from": "talert",
     "sms": "Hi there, testing Termii",
     "type": "plain",
     "channel": "generic",
     "api_key": "Your API Key",
     "media": {
      "url": "https://media.example.com/file",
      "caption": "your media file"
  }    
 }
var data = {
          "to":"2347880234567",
          "from":"talert",
          "sms":"Hi there, testing Termii",
          "type":"plain",
          "api_key":"Your API key",
          "channel":"generic",
          "media": {
            "url": "https://media.example.com/file",
            "caption": "your media file"
             }       
        };

var data = JSON.stringify(data);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
  console.log(this.responseText);
}
});

xhr.open("POST", "https://BASE_URL/api/sms/send");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
var request = require('request');
var data = {
          "to":"2347880234567",
          "from":"talert",
          "sms":"Hi there, testing Termii",
          "type":"plain",
          "api_key":"Your API key",
          "channel":"generic",
           "media": {
              "url": "https://media.example.com/file",
              "caption": "your media file"
            }   
        };
var options = {
'method': 'POST',
'url': 'https://BASE_URL/api/sms/send',
'headers': {
  'Content-Type': ['application/json', 'application/json']
},
body: JSON.stringify(data)

};
request(options, function (error, response) { 
if (error) throw new Error(error);
console.log(response.body);
});
import requests
url = "https://BASE_URL/api/sms/send"
payload = {
          "to": "2347880234567",
           "from": "talert",
           "sms": "Hi there, testing Termii ",
           "type": "plain",
           "channel": "generic",
           "api_key": "Your API Key",
             "media": {
                "url": "https://media.example.com/file",
                "caption": "your media file"
            }   
       }
headers = {
'Content-Type': 'application/json',
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)

var client = new RestClient("https://BASE_URL/api/sms/send");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\r\n \"to\":\"2347880234567\",\r\n  \"from\":\"talert\",\r\n  \"sms\":\"Hi there, testing Termii\",\r\n 
 \"type\":\"plain\",\r\n  \"api_key\":\"Your API key\",\r\n \"channel\":\"generic\",\r\n  \"media\": {\r\n \"url\": \"https://media.example.com/file\",\r\n  \"caption\": \"your media file\"\r\n }   \r\n  };", 
ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);


Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://BASE_URL/api/sms/send")
.header("Content-Type", "application/json")
.body("{\r\n \"to\":\"2347880234567\",\r\n \"from\":\"talert\",\r\n  \"sms\":\"Hi there, testing Termii\",\r\n \"type\":\"plain\",\r\n  \"api_key\":\"Your API key\",\r\n  \"channel\":\"generic\",\r\n  \"media\": {\r\n \"url\": \"https://media.example.com/file\",\r\n  \"caption\": \"your media file\"\r\n  } \r\n  };")
.asString();


$curl = curl_init();
$data = array("api_key" => "Your API key", "to" => "2347880234567",  "from" => "talert",
"sms" => "Hi there, testing Termii ",  "type" => "plain",  "channel" => "generic" );

$post_data = json_encode($data);

curl_setopt_array($curl, array(
CURLOPT_URL => "https://BASE_URL/api/sms/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $post_data,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json"
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


Response

   {
      "message_id": "9122821270554876574",
      "message": "Successfully Sent",
      "balance": 9,
      "user": "Peter Mcleish"
   }

Send Bulk message

Endpoint : https://BASE_URL/api/sms/send/bulk

Request Type : POST

Body params

OptionsRequiredDescription
api_keyyesstring
Your API key (It can be found on your Termii dashboard.
toyesstring
Represents the array of phone numbers you are sending to (Example: ["23490555546", "23423490126999","23490555546"]). Phone numbers must be in international format (Example: 23490126727). Please note: the array can take up to 10,000 phone numbers
fromyesstring
Represents a sender ID for sms which can be Alphanumeric or Device name for Whatsapp. Alphanumeric sender ID length should be between 3 and 11 characters (Example:CompanyName)
smsyesstring
Text of a message that would be sent to the destination phone number
typeyesstring
The type of message that is sent, which is a plain message.
channelyesstring
This is the channel through which the message is sent. It is either dnd, whatsapp, or generic


{
     "to": ["23490555546", "23423490126999","23490555546"],
     "from": "talert",
     "sms": "Hi there, testing Termii",
     "type": "plain",
     "channel": "generic",
     "api_key": "Your API Key",
 }
var data = {
          "to":["23490555546", "23423490126999","23490555546"],
          "from":"talert",
          "sms":"Hi there, testing Termii",
          "type":"plain",
          "api_key":"Your API key",
          "channel":"generic",
             
        };

var data = JSON.stringify(data);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
  console.log(this.responseText);
}
});

xhr.open("POST", "https://BASE_URL/api/sms/send/bulk");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
var request = require('request');
var data = {
          "to":["23490555546", "23423490126999","23490555546"],
          "from":"talert",
          "sms":"Hi there, testing Termii",
          "type":"plain",
          "api_key":"Your API key",
          "channel":"generic", 
        };
var options = {
'method': 'POST',
'url': 'https://BASE_URL/api/sms/send/bulk',
'headers': {
  'Content-Type': ['application/json', 'application/json']
},
body: JSON.stringify(data)

};
request(options, function (error, response) { 
if (error) throw new Error(error);
console.log(response.body);
});
import requests
url = "https://BASE_URL/api/sms/send/bulk"
payload = {
          "to": ["23490555546", "23423490126999","23490555546"],
           "from": "talert",
           "sms": "Hi there, testing Termii ",
           "type": "plain",
           "channel": "generic",
           "api_key": "Your API Key",
       }
headers = {
'Content-Type': 'application/json',
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)

var client = new RestClient("https://BASE_URL/api/sms/send/bulk");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\r\n \"to\":\["2347880234567","2347880234567"],\r\n  \"from\":\"talert\",\r\n  \"sms\":\"Hi there, testing Termii\",\r\n 
 \"type\":\"plain\",\r\n  \"api_key\":\"Your API key\",\r\n \"channel\":\"generic\",\r\n  };", 
ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);


Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://BASE_URL/api/sms/send/bulk")
.header("Content-Type", "application/json")
.body("{\r\n \"to\":\["2347880234567","2347880234567"],\r\n \"from\":\"talert\",\r\n  \"sms\":\"Hi there, testing Termii\",\r\n \"type\":\"plain\",\r\n  \"api_key\":\"Your API key\",\r\n  \"channel\":\"generic\",\r\n };")
.asString();


$curl = curl_init();
$data = array("to" => ["2347880234567","2347880234567"], "from" => "talert", 
"sms" => "Hi there, testing Termii", "type" => "plain", "channel" => "generic", "api_key" => "Your API Key" );

$post_data = json_encode($data);

curl_setopt_array($curl, array(
CURLOPT_URL => 'https://BASE_URL/api/sms/send/bulk',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>' {
          "to": "2347880234567",
           "from": "talert",
           "sms": "Hi there, testing Termii ",
           "type": "plain",
           "channel": "generic",
           "api_key": "Your API Key",
       }',
CURLOPT_HTTPHEADER => array(
  'Content-Type: application/json'
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


Response

   {
      "code": "ok",
      "message_id": "9122821270554876574",
      "message": "Successfully Sent",
      "balance": 9,
      "user": "Peter Mcleish"
   }
Updated at, Thursday, October 24, 2024