API Documentation

SMS API reference

Send SMS through the gateway, follow each message to the handset, and receive replies and USSD requests on your own server.

v1 Updated

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#

  1. You send POST/api/sms with one or more messages.
  2. We reply straight away that the messages were accepted.
  3. We send each message to the operator. Its status moves from QUEUED to SENDING, then SENT.
  4. When the operator reports back, the message reaches a final status such as DELIVERED or FAILED. We send you a DLR callback.

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.
bash
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

json
{
  "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.

bash
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

json
{
  "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:

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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:

  1. Take the X-Timestamp header and the raw request body, and join them as text: timestamp + body.
  2. Remove every whitespace character from that text (spaces, tabs and new lines), including spaces inside values.
  3. Compute an HMAC with SHA-256, using your signature key as the key.
  4. Encode the result as Base64 (standard alphabet, with padding).
  5. Compare it with the X-Signature header. 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:

json
{"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:

text
vcCYVyWuFfgkCSsaTcSYPBJ4RsMSDEh6NJnaCTWjunw=

Each snippet below returns that value for the example above.

Python

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)

javascript
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

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

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)

rust
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

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-Timestamp header, and compare it with X-Signature in constant time, with a function such as hmac.compare_digest in Python or MessageDigest.isEqual in Java. Reject the callback if they differ.
  • Check the timestamp. Reject callbacks whose X-Timestamp is 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 input of 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.