Timisha Solutions API Documentation

Everything you need to integrate SMS, WhatsApp, USSD and two-way shortcodes into your application, whether you write your first API call today or push a million messages a month.

Timisha Solutions is an API-first messaging platform. You can run your entire integration, from your first test message to production traffic, without ever opening the web portal, apart from one visit to create your account and API token. Everything documented here works with plain HTTP: if your language can make a POST request, it can send messages.

# Paste your token once:
export TIMISHA_TOKEN="tms_your_token_here"

curl -X POST https://api.timisha.co.ke/v1/send/message \
  -H "Authorization: Bearer $TIMISHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderID": "TIMISHA",
    "phone": "0712345678",
    "message": "Hello from the Timisha Solutions API!"
  }'

That's a real, working call. Get a token from the portal, paste your token into the first line, and the message is on its way.

Quickstart

From nothing to a delivered SMS in about five minutes. One portal visit to get credentials, then everything else happens over the API.

1. Create an account and get a token

1. Register at sms.timisha.co.ke (free, no card needed).
2. Open API Tokens in the sidebar and create a token. Copy it immediately — it is shown once.
3. Note your approved sender ID. New accounts can send with the shared TIMISHA sender while their branded name is being registered.

2. Send your first message

curl -X POST https://api.timisha.co.ke/v1/send/message \
  -H "Authorization: Bearer $TIMISHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderID": "TIMISHA",
    "phone": "0712345678",
    "message": "Hello! Your Timisha Solutions integration works."
  }'

3. Read the response

{
  "status": true,
  "responseCode": "0200",
  "message": "Accepted",
  "messageId": "3c51beb1-a674-41d0-9e45-f5581418fb56"
}

status tells you whether the request was accepted; responseCode is a stable machine-readable code. Delivery to the handset is asynchronous — track it with delivery reports.

4. Go further

• Send to thousands in one call
• A different message per recipient
• v2: your own tracking IDs and per-send cost
• WhatsApp template broadcasts

Authentication

Every API call authenticates with a Bearer token in the Authorization header.

Authorization: Bearer YOUR_TOKEN

Token types

Where the token can go

The frozen endpoints accept the credential in any of these places, so existing integrations keep working:

• Authorization: Bearer <token> — preferred
• ?api_token=<token> in the query string
• An api_token field in a form-encoded or multipart body
• An api_token key in a JSON body

Common auth failures

• 401 / responseCode 0401: missing, mistyped, expired or revoked token.
• 403: the token is valid but lacks the scope or permission for that endpoint.

Responses & Errors

All API responses use a consistent envelope shape.

Success response

{
  "status": true,
  "responseCode": "0200",
  "message": "Accepted",
  "messageId": "9b8a028b-f9bb-49f6-bc89-a5214ff1ba93"
}

Error response

{
  "status": false,
  "responseCode": "0401",
  "message": "Invalid or expired token"
}

Common response codes

SMS API

Branded SMS to every Kenyan network: Safaricom, Airtel, Telkom and Equitel. Through a REST API whose contract is frozen.

Endpoints at a glance

Send a single message

curl -X POST https://api.timisha.co.ke/v1/send/message \
  -H "Authorization: Bearer $TIMISHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderID": "TIMISHA",
    "phone": "254712345678",
    "message": "Hello from Timisha Solutions"
  }'

Send bulk SMS

curl -X POST https://api.timisha.co.ke/v1/send/bulk \
  -H "Authorization: Bearer $TIMISHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderID": "TIMISHA",
    "phones": ["254712345678", "254723456789"],
    "message": "Hello to all"
  }'

Sender IDs

The name that appears on the recipient's phone (e.g. TIMISHA, your brand). Sender IDs are registered per network. Apply over the API with your business documents; the API rejects sends from names your account doesn't own.

Message parts & billing

A single SMS carries 160 GSM-7 characters (70 for Unicode). Longer texts are split into parts of 153 (67 Unicode) and rebuilt on the handset. You are billed per part.

WhatsApp API

Broadcast approved templates to opted-in customers via the official WhatsApp Business API.

Key features

• Template-based messaging
• Media support (images, documents)
• Conversation-based billing
• Read receipts and delivery status

Send a template message

curl -X POST https://api.timisha.co.ke/api/v1/whatsapp/send \
  -H "Authorization: Bearer $TIMISHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "welcome_message",
    "language": "en",
    "phone": "254712345678"
  }'

A WhatsApp Business number and Meta-approved templates are required; we set both up with you at no extra charge.

USSD

Build interactive menu sessions that work on every phone — including feature phones with no data.

How it works

USSD sessions are real-time, session-based conversations triggered by a dial code — think *544# on Safaricom. No internet, no smartphone, no app required.

Example menu flow

User dials: *384*100#
→ Welcome to Timisha Solutions
  1. Check Balance
  2. Pay Bill
  3. Exit

Use cases

• Balance checks
• Loan applications
• Voting and surveys
• M-Pesa-style flows

Shortcodes

Run two-way SMS on a dedicated or shared shortcode. Route inbound messages by keyword, trigger auto-responses, and manage competitions via webhook or portal.

Shared shortcode

Your menu lives under a shared shortcode (e.g. *384*YOUR_CODE#). Lowest cost to get started — ideal for SMEs, NGOs, and pilots.

Dedicated shortcode

Your own shortcode (e.g. *777#). Full branding, faster session routing, and no keyword conflicts.

Inbound webhook

POST https://your-domain.com/webhook
{
  "shortcode": "1234",
  "keyword": "JOIN",
  "phone": "254712345678",
  "message": "JOIN TIMISHA"
}

Surveys

Polls, questionnaires, and feedback surveys over SMS and USSD. Responses stream into your dashboard in real time.

Key features

• Multi-channel delivery (SMS, USSD)
• Live results dashboard
• Winners per question
• Full transcripts
• CSV exports

Example survey via SMS

curl -X POST https://api.timisha.co.ke/api/v1/surveys/send \
  -H "Authorization: Bearer $TIMISHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": "svy_123",
    "phones": ["254712345678"]
  }'

Phone Formats

All of these are accepted and normalised to E.164 for you:

• 0712345678
• 254712345678
• +254712345678

Invalid numbers are rejected with a validation error rather than billed and dropped.

Webhooks

Delivery reports, inbound SMS, and USSD session events can be pushed to your server in real time.

Delivery report (DLR) payload

{
  "messageId": "9b8a028b-f9bb-49f6-bc89-a5214ff1ba93",
  "phone": "254712345678",
  "status": "delivered",
  "deliveredAt": "2026-08-10T12:00:00Z"
}

Set your webhook URL in the portal under API → Webhooks.

SDKs & Libraries

No SDK is required — plain HTTP and JSON is enough. If you prefer a library, we maintain examples for:

• PHP
• Python
• Node.js
• Go

Contact us if you need an official SDK for your language.