Developer Integration Guide

Overview

The Taifa Mobile SMS Gateway is an SMS intermediary. You submit messages to the platform; the platform routes them to the correct mobile network operator in Kenya.

Authentication

Every account has an API key (64-character hex string). Pass it in the h_api_key HTTP header on every REST request.

h_api_key: YOUR_64_CHARACTER_API_KEY

Mobile Number Formats

All three formats are accepted and normalised to 254xxxxxxxxx internally.

SMPP v3.4 is a persistent TCP protocol designed for high-volume SMS delivery. Once bound, a single connection can submit thousands of messages per second without the overhead of a new HTTP request per message.

Setup Steps

1. Set SMPP credentials

   Use your REST API key to register a short username and password via the REST API.

   curl -X POST https://api.taifamobile.co.ke/v2/sms/smpp-credentials \
     -H "h_api_key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"smpp_username": "myuser", "smpp_password": "myPass8c"}'

   Save the response — use these as system_id and password at bind.

2. Verify port connectivity

   # Linux / Mac
   nc -zv api.taifamobile.co.ke 2775
   
   # Windows PowerShell
   Test-NetConnection -ComputerName api.taifamobile.co.ke -Port 2775

   Expected: Connection succeeded

3. Connect and bind

   Open a TCP connection to port 2775 and send a bind_transmitter PDU.

   SMPP field	Value
   system_id	Your smpp_username
   password	Your smpp_password
   system_type	(leave empty)
   interface_version	0x34 (SMPP v3.4)

   A successful bind returns bind_transmitter_resp with command_status = 0x00000000.

4. Submit messages

   Send submit_sm PDUs. The server responds with submit_sm_resp containing your internal message_id on success.

   Field	Value
   source_addr_ton	5 alphanumeric / 1 numeric
   source_addr_npi	0 alphanumeric / 1 numeric
   source_addr	Registered sender ID e.g. MYSENDER
   dest_addr_ton	1
   dest_addr_npi	1
   destination_addr	Mobile in 254xxxxxxxxx format
   data_coding	0 GSM7/Latin  |  8 UCS2/Unicode

5. Keep the connection alive

   Send an enquire_link PDU every 30–60 seconds. The server responds with enquire_link_resp. Connections idle for more than 300 seconds will be closed.

Python Example

pip install smpplib

Send a single message

import smpplib.client
import smpplib.consts

HOST     = "api.taifamobile.co.ke"
PORT     = 2775
USERNAME = "myuser"     # smpp_username
PASSWORD = "myPass8c"   # smpp_password

client = smpplib.client.Client(HOST, PORT)
client.connect()
client.bind_transmitter(system_id=USERNAME, password=PASSWORD)

pdu = client.send_message(
    source_addr_ton  = smpplib.consts.SMPP_TON_ALNUM,
    source_addr_npi  = smpplib.consts.SMPP_NPI_UNK,
    source_addr      = "MYSENDER",
    dest_addr_ton    = smpplib.consts.SMPP_TON_INTL,
    dest_addr_npi    = smpplib.consts.SMPP_NPI_ISDN,
    destination_addr = "254702739804",
    short_message    = b"Hello from Taifa Mobile",
)
print("Sent — sequence:", pdu.sequence)

client.unbind()
client.disconnect()

Persistent connection with keep-alive

import smpplib.client
import smpplib.consts
import threading
import time

HOST     = "api.taifamobile.co.ke"
PORT     = 2775
USERNAME = "myuser"
PASSWORD = "myPass8c"

client = smpplib.client.Client(HOST, PORT)
client.connect()
client.bind_transmitter(system_id=USERNAME, password=PASSWORD)

def keep_alive():
    while True:
        time.sleep(30)
        try:
            client.enquire_link()
        except Exception:
            break

threading.Thread(target=keep_alive, daemon=True).start()

messages = [
    ("254702739804", "First message"),
    ("254725497524", "Second message"),
]
for mobile, text in messages:
    pdu = client.send_message(
        source_addr_ton  = smpplib.consts.SMPP_TON_ALNUM,
        source_addr_npi  = smpplib.consts.SMPP_NPI_UNK,
        source_addr      = "MYSENDER",
        dest_addr_ton    = smpplib.consts.SMPP_TON_INTL,
        dest_addr_npi    = smpplib.consts.SMPP_NPI_ISDN,
        destination_addr = mobile,
        short_message    = text.encode(),
    )
    print(f"Queued {mobile} — seq {pdu.sequence}")

client.unbind()
client.disconnect()

PHP Example

composer require onlinecity/php-smpp

<?php
require 'vendor/autoload.php';

use SMPP\Client\SmppClient;
use SMPP\Transport\SocketTransport;

$transport = new SocketTransport(['api.taifamobile.co.ke'], 2775);
$transport->setRecvTimeout(10000);
$smpp = new SmppClient($transport);

$transport->open();
$smpp->bindTransmitter("myuser", "myPass8c");

$from  = new SMPP\SMPP\Address("MYSENDER", SMPP\SMPP\SMPP::TON_ALPHANUMERIC);
$to    = new SMPP\SMPP\Address("254702739804", SMPP\SMPP\SMPP::TON_INTERNATIONAL, SMPP\SMPP\SMPP::NPI_E164);
$msgid = $smpp->sendSMS($from, $to, "Hello from Taifa Mobile");
echo "Sent! message_id = $msgid\n";

$smpp->close();

SMPP Error Codes

Bind errors

Submit errors

ESME_RSUBMITFAIL — rejection reasons

Best Practices