SMPP

Timisha Solutions exposes an SMPP v3.4 interface for high-throughput and low-latency integrations. It is the right choice for OTP delivery, real-time transactional messages, and any system that needs guaranteed sub-500 ms delivery. If you only need occasional or bulk sends, the REST messages API is simpler to integrate.

Connection details

Point your SMPP client (client library or ESME) at the host below and bind with your team credentials. The port depends on whether you want a plain TCP or TLS-encrypted session.

Host               timisha-solutions-api.salamu.co.ke
Port               2775 (plain)  /  2776 (TLS)
System ID          Your team code (e.g. ACME2024)
Password           Your API token (mbs_…)
System type        TRANSCEIVER
Interface version  0x34 (SMPP 3.4)

Binding

Use bind_transceiver to send and receive in a single session. A bind_transmitter bind is also accepted if you only need to submit messages and do not want to receive delivery receipts or inbound traffic on the same session.

bind_transceiver:
  system_id:     ACME2024
  password:      mbs_your_token_here
  system_type:   (leave empty)
  interface_ver: 0x34
  addr_ton:      0x01  (International)
  addr_npi:      0x01  (ISDN / E.164)
  address_range: (leave empty)

Sending messages

Submit each message with a submit_sm PDU. The source address is your approved sender ID (encoded as alphanumeric), and the destination is an E.164 number without the leading +. Set data_coding to 0x00 for GSM7 or 0x08 for UCS-2 (Unicode).

submit_sm:
  source_addr_ton:   0x05  (Alphanumeric)
  source_addr_npi:   0x00
  source_addr:       MYAPP              # your approved sender ID
  dest_addr_ton:     0x01  (International)
  dest_addr_npi:     0x01  (ISDN)
  destination_addr:  254712345678       # E.164 without leading +
  esm_class:         0x00
  data_coding:       0x00  (GSM7)  or  0x08  (UCS-2)
  registered_delivery: 0x01             # request DLR
  short_message:     Your OTP is 483920

Delivery receipts

Set registered_delivery = 0x01 on the submit_sm to request a delivery receipt. The server sends a deliver_sm DLR with the status string in the short_message field.

# DLR short_message format
id:MSG123 sub:001 dlvrd:001 submit date:2605110900 done date:2605110900 stat:DELIVRD err:000

# stat values
DELIVRD — delivered to handset
UNDELIV — undeliverable (inactive number or network error)
REJECTD — rejected by carrier
EXPIRED — message TTL elapsed

Unicode and long messages

For Unicode content, set data_coding = 0x08 (UCS-2). Messages longer than a single segment are split into concatenated parts using SAR TLVs. Keep sar_msg_ref_num the same across all parts and increment sar_segment_seqnum per part. A single segment holds up to 153 GSM7 or 67 UCS-2 characters.

# UCS-2 (Unicode): data_coding = 0x08
# Concatenated long message (3 parts, SAR TLVs)
submit_sm[1]:
  esm_class:          0x40  (UDH present)
  sar_msg_ref_num:    42    (same for all parts)
  sar_total_segments: 3
  sar_segment_seqnum: 1
  short_message: <part 1 — max 153 GSM7 / 67 UCS-2 chars>

Session limits

Each team is subject to the following session and throughput limits. Keep the session alive with periodic enquire_link PDUs so it is not closed on idle timeout.