The gateway delivers your SMS through the mobile operators. You send a message with one request. We tell you what happened to it by callback, and you can also ask for its status at any time.
Important
Sending is asynchronous. A success response means we accepted the message, not that the customer received it. The result arrives later as a delivery report (DLR callback), or you can fetch it with a GET request.
How it works#
- You send
POST/api/smswith one or more messages. - We reply straight away that the messages were accepted.
- We send each message to the operator. Its status moves from
QUEUEDtoSENDING, thenSENT. - When the operator reports back, the message reaches a final status such as
DELIVEREDorFAILED. We send you aDLRcallback.
Two more things can reach your server, if they are set up for your account:
- MO callback. A customer sends an SMS to your short code, and we pass it to you.
- USSD callback. A customer dials your USSD code, and we ask you what to show on their screen.
Before you start#
You receive these during onboarding:
| Item | Where you use it |
|---|---|
| Base URL | The address of the gateway. Every path below is added to it. |
X-Client-Id |
Sent as a header on every request. Identifies your account. |
X-Client-Secret |
Sent as a header on every request. |
| Signature key | Used to check the X-Signature on callbacks. Never sent. It only lives on your server. |
| Sender names | The names your messages can come from, such as MYSHOP. |
| Our IP addresses | The addresses we send callbacks from. Whitelist them on your firewall. |
| Callback URLs | Where we send DLR, MO and USSD callbacks. |
All communication uses HTTPS. Requests and responses are JSON (application/json, UTF-8).
Warning
Keep the client secret and the signature key on your server. Never put them in a mobile app, in browser code or in a public repository.
Send SMS#
POST/api/sms
Sends one or more messages. Put every message in the messages list.
Headers
| Header | Required | Description |
|---|---|---|
X-Client-Id |
Yes | Your client ID. |
X-Client-Secret |
Yes | Your client secret. |
Content-Type |
Yes | application/json |
Body
The body has one field, messages, a list. Each item in the list is one SMS:
| Field | Type | Description |
|---|---|---|
message |
string | The text to send. |
destination |
string | The customer's phone number in international format, without +, such as 255710000000. |
reference |
string | Your own ID for this message. You use it to look the message up later, so keep it unique. |
sender_name |
string | The name the customer sees as the sender. |
flash |
boolean | true sends a flash SMS, which shows on the screen at once and is not saved in the inbox. Use false for a normal SMS. |
coding |
string | How the text is encoded. GSM7 is the standard set of letters, digits and common symbols. |
curl -X POST "https://GATEWAY_URL/api/sms" \
-H "accept: application/json" \
-H "X-Client-Id: $CLIENT_ID" \
-H "X-Client-Secret: $CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"message": "Your code is 4821",
"destination": "255710000000",
"flash": false,
"reference": "order-10045-sms-1",
"sender_name": "MYSHOP",
"coding": "GSM7"
}
]
}'
Response
{
"status": true,
"message": "Message accepted",
"data": null
}
The messages are now in our queue. Follow them with a DLR callback or by fetching the message.
Message length and parts#
A long message is split into parts, and each part is one SMS on the operator's network. You are billed per part.
| Coding | One part (single SMS) | Each part of a long message |
|---|---|---|
GSM7 |
up to 160 characters | up to 153 characters |
UCS2 |
up to 140 characters | up to 134 characters |
For example, a 300-character GSM7 message becomes 2 parts.
Other responses
| HTTP status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request body. | Fix the request. Do not retry it as it is. |
| 403 | The request came from an address that is not whitelisted, or your credentials are disabled. | Check that you call us from a whitelisted address, then contact support. |
| 404 | Credentials not found. | Check X-Client-Id and X-Client-Secret. |
Error responses use the same shape as the success response, with "status": false and a message that explains the problem.
Get an SMS#
GET/api/sms/{reference}
Returns the latest status of a message. {reference} is the reference you sent when you created it.
Use it when a callback does not arrive. Do not poll in a tight loop, because callbacks are the main way to learn the result.
curl "https://GATEWAY_URL/api/sms/order-10045-sms-1" \
-H "accept: application/json" \
-H "X-Client-Id: $CLIENT_ID" \
-H "X-Client-Secret: $CLIENT_SECRET"
Response 200 OK
{
"status": true,
"message": "SMS found",
"data": {
"reference": "order-10045-sms-1",
"system_reference": "3759570112968740",
"status": "DELIVERED",
"description": "Delivered",
"created_at": "2026-11-02T10:22:24.482549Z",
"sent_at": "2026-11-02T10:22:24.547187Z",
"completed_at": "2026-11-02T10:22:29.668049Z"
}
}
| Field | Type | Description |
|---|---|---|
reference |
string | Your own reference, as you sent it. |
system_reference |
string | Our unique ID for the message. Quote it when you contact support. |
status |
string | The current status. See Statuses. |
description |
string | A short readable explanation of the status. |
created_at |
string | When we accepted the message. ISO 8601, in UTC. |
sent_at |
string | When we handed the message to the operator. |
completed_at |
string | When the message reached its final status. It is empty until then. |
Other responses
| HTTP status | Meaning |
|---|---|
| 403 | The request came from an address that is not whitelisted, or your credentials are disabled. |
| 404 | Credentials not found, or no message with that reference. |
Statuses#
A message moves through these statuses. Once it reaches a final status it does not change again.
| Status | Final | Meaning |
|---|---|---|
QUEUED |
No | We accepted the message and it is waiting to be sent. |
SENDING |
No | We are handing the message to the operator. |
SENT |
No | The operator has the message. We are waiting for its delivery report. |
DELIVERED |
Yes | The message reached the customer's phone. |
FAILED |
Yes | The message could not be delivered. |
REJECTED |
Yes | The message was refused and never sent. |
EXPIRED |
Yes | The message was not delivered before it expired, for example because the phone stayed off. |
Tip
Treat QUEUED, SENDING and SENT as "still in progress". Wait for the DLR callback before you mark a message as failed.
Callbacks#
We send callbacks as POST requests with a JSON body to the URLs set up for your account.
| Callback | When we send it | What you do |
|---|---|---|
DLR |
A message reaches a final status. | Save the result. |
MO |
A customer sends an SMS to your short code. | Save or process the message. |
USSD |
A customer dials your USSD code or answers a menu. | Reply with what to show on their screen. |
Every callback has these headers:
| Header | Description |
|---|---|
X-Signature |
The signature. Verify it. See Verifying callbacks. |
X-Timestamp |
The time we sent the callback, in Unix seconds. |
Content-Type |
application/json |
Your response#
Answer DLR and MO callbacks with HTTP 200 and this body:
{
"status": true,
"message": "Success"
}
USSD callbacks are different. Your answer decides what the customer sees. See USSD session.
Tip
Callbacks can arrive more than once. Use the reference and status to spot a callback you have already handled, and answer with success without processing it again.
Respond quickly. Save the result, and do slow work such as sending emails after you have replied.
DLR (delivery report)#
Sent when a message reaches a final status.
{
"type": "DLR",
"data": {
"reference": "order-10045-sms-1",
"system_reference": "3937188632692582",
"status": "DELIVERED",
"description": "Delivered",
"created_at": "2026-11-06T07:44:48.805376Z",
"sent_at": "2026-11-06T07:44:48.858096Z",
"completed_at": "2026-11-06T07:44:58.010122Z"
}
}
The fields in data are the same as in Get an SMS. Use reference to find the message in your own system.
MO (incoming SMS)#
Sent when a customer sends an SMS to your short code.
{
"date": "2026-11-06T11:18:21.234724+03:00",
"message": "Service rate 10/10",
"msisdn": "255710000000",
"operator": "Yas",
"short_code": "15009"
}
| Field | Type | Description |
|---|---|---|
date |
string | When the customer sent the message. ISO 8601, with the time zone offset. |
message |
string | The text the customer sent. |
msisdn |
string | The customer's phone number in international format, without +. |
operator |
string | The customer's mobile operator. |
short_code |
string | The short code the customer sent the message to. |
USSD session#
Sent when a customer dials your USSD code, and again each time they answer a menu.
{
"input": "*150*09#",
"msisdn": "255710000000",
"operator": "Yas",
"session_id": "1793953101234",
"short_code": "15009"
}
| Field | Type | Description |
|---|---|---|
input |
string | What the customer entered. This is the dialled code at the start, then their answers. |
msisdn |
string | The customer's phone number in international format, without +. |
operator |
string | The customer's mobile operator. |
session_id |
string | The ID of this USSD session. It stays the same for the whole conversation. |
short_code |
string | The USSD code the customer is using. |
Your response decides what happens next. Reply with a status and a message:
status |
What happens | message |
|---|---|---|
true |
The session continues. The customer can answer. | Shown on the customer's phone as the next menu or question. |
false |
The session ends. | Shown on the customer's phone as the last screen. |
Example: the customer dials the code, and you show a menu.
{
"status": true,
"message": "Welcome to MyShop\n1. Check balance\n2. Talk to us"
}
The customer answers 1. We send you another callback with the same session_id and "input": "1". You reply with the balance and close the session.
{
"status": false,
"message": "Your balance is TZS 12,500. Thank you."
}
Note
Keep your answer short, because USSD screens are small, and reply fast. The operator closes a session that waits too long.
Verifying callbacks#
Every callback is signed, so you can be sure it came from us and was not changed on the way. Check the signature before you trust the content.
To compute the signature of a callback:
- Take the
X-Timestampheader and the raw request body, and join them as text:timestamp + body. - Remove every whitespace character from that text (spaces, tabs and new lines), including spaces inside values.
- Compute an HMAC with SHA-256, using your signature key as the key.
- Encode the result as Base64 (standard alphabet, with padding).
- Compare it with the
X-Signatureheader. Reject the callback if they differ.
Note
Sign the raw body exactly as it arrives. If your framework parses the JSON and writes it out again, the text can change and the signature will not match. Read the raw body first.
Use this example to test your code. With the signature key sk_test_example_key, timestamp 1793951098 and this body:
{"data":{"completed_at":"2026-11-06T07:44:58.010122Z","created_at":"2026-11-06T07:44:48.805376Z","description":"Delivered","reference":"23456789-217892","sent_at":"2026-11-06T07:44:48.858096Z","status":"DELIVERED","system_reference":"3937188632692582"},"type":"DLR"}
the signature is:
vcCYVyWuFfgkCSsaTcSYPBJ4RsMSDEh6NJnaCTWjunw=
Each snippet below returns that value for the example above.
Python
import base64, hashlib, hmac, re
def sign(timestamp: str, payload: str, secret: str) -> str:
data = re.sub(r"\s+", "", timestamp + payload)
digest = hmac.new(secret.encode("utf-8"), data.encode("utf-8"), hashlib.sha256).digest()
return base64.b64encode(digest).decode("ascii")
JavaScript (Node.js)
const crypto = require("node:crypto");
function sign(timestamp, payload, secret) {
const data = (timestamp + payload).replace(/\s+/g, "");
return crypto.createHmac("sha256", secret).update(data, "utf8").digest("base64");
}
PHP
function sign(string $timestamp, string $payload, string $secret): string {
$data = preg_replace('/\s+/', '', $timestamp . $payload);
return base64_encode(hash_hmac('sha256', $data, $secret, true));
}
Go
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"regexp"
)
var whitespace = regexp.MustCompile(`\s+`)
func sign(timestamp, payload, secret string) string {
data := whitespace.ReplaceAllString(timestamp+payload, "")
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(data))
return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}
Rust (crates hmac, sha2 and base64)
use base64::{engine::general_purpose::STANDARD, Engine};
use hmac::{Hmac, KeyInit, Mac};
use sha2::Sha256;
fn sign(timestamp: &str, payload: &str, secret: &str) -> String {
let data: String = format!("{timestamp}{payload}")
.chars()
.filter(|c| !c.is_whitespace())
.collect();
let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("any key length works");
mac.update(data.as_bytes());
STANDARD.encode(mac.finalize().into_bytes())
}
Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
static String sign(String timestamp, String payload, String secret) throws Exception {
String data = (timestamp + payload).replaceAll("\\s+", "");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
return Base64.getEncoder().encodeToString(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));
}
SMPP#
If you send a lot of traffic, you can also connect to the gateway over SMPP. SMPP is the standard protocol that SMS systems use to talk to each other. You keep one connection open and send messages through it, instead of making an HTTP request for each batch.
You receive the connection details during onboarding:
| Item | Description |
|---|---|
| Host and port | The address of our SMPP server. |
| System ID and password | Your login for the connection. |
| Allowed IP addresses | The addresses you connect from. Others are refused. |
Security checklist#
Caution
Callbacks that are not checked can be forged. Anyone who knows your callback URL can send a fake "delivered" message, or a fake customer reply.
- Whitelist our IP addresses. Accept callbacks only from the addresses we gave you. Requests to the gateway from other addresses are refused with
403. - Use HTTPS. Your callback URLs must use HTTPS in production.
- Verify the signature on every callback. Compute it from the raw body and the
X-Timestampheader, and compare it withX-Signaturein constant time, with a function such ashmac.compare_digestin Python orMessageDigest.isEqualin Java. Reject the callback if they differ. - Check the timestamp. Reject callbacks whose
X-Timestampis far from your clock, for example by more than 5 minutes. This stops someone from replaying an old message. - Ignore repeats. The same callback can arrive more than once.
- Do not trust customer input. The text of an MO message and the
inputof a USSD callback come from a customer. Check it before you use it. - Protect your secrets. Keep the client secret and the signature key in a secrets manager or environment variables. Do not log them, and tell us at once if you think they leaked.
Getting help#
If you contact support, include the system_reference and your own reference. With these two we can trace the message from your request to the operator and back.