Kimisms SMS Documentation

Overview

Kimisms is a corporate bulk SMS platform that enables businesses to send promotional and transactional SMS messages across Kenyan mobile networks — Safaricom, Airtel, and Telkom.

There are three ways to send SMS through Kimisms:

Message flow

SMS unit calculation

Messages are charged in units based on character length:

Account Setup

Before you can send SMS, you need to create an account and get set up on the platform.

Sender IDs

A Sender ID is the name or short code that appears as the sender when a recipient receives your SMS. Each Sender ID is tied to a specific network provider.

Types

Campaign types

Application process

1. Go to Sender ID → Applications and click Add Application
2. Fill in: organization name, provider (Safaricom/Airtel/Telkom), proposed sender name, campaign type, and purpose
3. Upload required KYC documents (business registration, letter of authorization)
4. Your application goes through review: PENDING → PROVIDER → APPROVED
5. Once approved, the Sender ID is created and linked to your account

Quick Send

Quick Send lets you send a single SMS to one phone number directly from the portal. Ideal for testing, one-off alerts, or individual notifications.

How to send

Required fields

Bulk Campaign

Bulk campaigns let you send the same message to hundreds or thousands of contacts at once. Messages are processed asynchronously in the background.

How to send a bulk campaign

How provider matching works

When you send a bulk campaign, each contact is automatically routed to the correct provider:

1. The system reads the contact's phone number prefix
2. It looks up the provider (Safaricom, Airtel, or Telkom) from the prefix table
3. It finds a matching Sender ID from your selected list for that provider
4. If no matching Sender ID is found, that contact is skipped with a FAILED status

Template Messages

Templates let you send personalized messages to each contact by inserting dynamic fields from your contact data.

How it works

When you upload contacts via CSV, additional columns beyond "number" are mapped to field1 through field6. You can reference these fields in your message template.

Example

If your CSV has columns: number, name, amount

• number → contact phone number
• name → mapped to field1
• amount → mapped to field2

Your template message:

Each contact will receive a personalized message with their actual name and amount values inserted.

Creating templates

1. Go to Contacts → Templates
2. Click Add Template and select the contact group
3. Compose your message using {field_name} placeholders
4. Save the template — it's now available when sending bulk campaigns

Contact Groups

Contact groups organize your recipients into segmented lists for targeted messaging.

Creating a group

1. Go to Contacts → Contact Groups
2. Click Upload Group
3. Enter a group name and description
4. Upload a CSV file with your contacts
5. The system processes the file in the background and assigns providers automatically based on phone number prefixes

Adding individual contacts

Within a group, click Add Contact to add a single contact manually. Enter the phone number and any custom field values.

CSV Upload Format

Upload contacts in bulk using a CSV file. The system supports up to 7 columns.

CSV requirements

Example CSV

Duplicate handling

During upload, you can check Remove Duplicates to automatically remove contacts with duplicate phone numbers. During bulk send, you can also enable deduplication to avoid sending multiple messages to the same number across groups.

Message Templates

Templates are reusable message blueprints tied to specific contact groups. They use field placeholders to personalize messages for each recipient.

Placeholder syntax

Use curly braces with the CSV column header name:

The column names from your CSV become the placeholder keys. The system maps them to field1–field6 internally, but you reference them by their original CSV header name.

Top-up Balance

To send SMS, you need sufficient float balance on your Sender IDs. Top up by purchasing SMS packages.

Top-up process

M-Pesa Payment

Kimisms integrates with Safaricom's M-Pesa Lipa Na M-Pesa (STK Push) for instant balance top-ups.

How it works

1. Select M-Pesa as your payment method during top-up
2. Enter your M-Pesa phone number in format 254XXXXXXXXX
3. The system sends an STK push to your phone
4. Enter your M-Pesa PIN to confirm payment
5. On successful payment, your float balance is automatically updated

Transaction statuses

Float & Balance

Float is your SMS credit balance. Each Sender ID maintains its own float balance. When you send a message, the required SMS units are deducted from the relevant Sender ID's float.

Viewing your balance

• Navbar — The balance dropdown in the top bar shows your total balance and breakdown by provider (Admin+ roles)
• Billing → Float — View detailed float balances per Sender ID
• Quick Send form — The Sender ID dropdown shows available balance alongside each option

Balance deduction

Balance is deducted at the time of sending, before the message reaches the network provider. The system uses atomic database operations to prevent race conditions on concurrent sends.

API Authentication

The Kimisms API uses OAuth 2.0 client credentials flow. You exchange your Client ID and Client Secret for a Bearer token.

Step 1: Generate credentials

1. Go to Developer → Credentials in the portal
2. Click Generate Credentials
3. Copy your Client ID and Client Secret — store them securely

Step 2: Get access token

Response

Use the token in subsequent API requests in the Authorization header:

Send SMS via API

Send a single SMS message programmatically using a POST request.

Endpoint

Request body

Send SMS — code example

Success response

Idempotency

To prevent duplicate sends, include an Idempotency-Key header with a unique value. Requests with the same key within 24 hours return the cached response instead of sending again.

Delivery Callbacks

If you provide a callback_url when sending via API, Kimisms will send a POST request to your URL when the delivery status changes.

Callback payload

Status values

Status progression

A message can transition to FAILED from any prior status.

Error Handling

The API returns standard HTTP status codes with JSON error bodies.

Error response format

Delivery Reports

Track the performance of your SMS campaigns with detailed delivery reports.

Accessing reports

• Reports → Blasts — View all campaigns (Quick, Bulk, API sends) with total SMS counts
• Reports → SMS Logs — Drill into individual message statuses with filters

Report metrics

SMS Logs

SMS logs provide a detailed record of every message sent through the platform.

Log fields

Filtering logs

Use the search and filter options to narrow down logs by status, provider, date range, or phone number.

Status Tracking

Each SMS has a complete status history. Click on any SMS log entry to view the full timeline of status changes.

Status log timeline

Each status change is recorded with:

• Status — The new status value
• Description — Details about the change (provider response, error message)
• Timestamp — When the status change occurred

Common failure reasons