Authentication

Every endpoint except a small set marked public requires an API key, sent as a standard Authorization header.

API Keys

Create non-expiring API keys from your account in the Keltap portal, not from the API itself: log in, open the API section, and click New API Key. Give it a name (defaults to "Default" if left blank) so you can tell keys apart, e.g. one per environment or integration. The raw key is shown once:

Using an API key

Send it in the Authorization header, prefixed txf_, on any protected endpoint:

API keys don't expire and aren't tied to a session, so there's no logout for them.

Per-key webhook URL

Each key can optionally carry its own webhook_url, set when you create it or changed later from the portal. Sender name and purchase status callbacks are routed to the webhook_url of whichever key was used to create that sender name request or purchase, falling back to your account's default webhook URL when that key has none set. Message delivery-status callbacks always use the account default, regardless of which key sent the message. See Webhooks for the full routing rules and payload shapes.

Authentication errors

A missing or invalid key, or a disabled/unverified account, returns 401 Unauthorized with a machine-readable error code:

Base URL

Every endpoint in this reference is relative to a single base URL:

For example, sending an SMS means making a request to https://portal.keltap.co.tz/api/v1/messages. Throughout this reference, paths are written relative to that base, e.g. POST /messages.

Versioning

/api/v1 is the current and only stable version. Breaking changes will be introduced under a new version prefix rather than changing this one in place.

Request & Response Format

Requests

All request bodies are JSON. Send Content-Type: application/json on every POST, PUT, PATCH and DELETE request that includes a body, and authenticate with a bearer token as described in Authentication unless the endpoint is marked public.

Response envelope

Every endpoint, success or failure, responds with the same JSON envelope:

success tells you which shape you got without inspecting the status code. On success, data holds the payload and error is omitted. On failure, error is a short machine-readable code you can branch on, and message is a human-readable description safe to log or, in most cases, show to a user.

Pagination

List endpoints (like GET /messages) accept these query parameters:

The paginated result is nested inside the standard envelope's data field:

HTTP status codes

SMS API

Send single or bulk SMS (or WhatsApp template messages), list your message history, and fetch a single message by id. One SMS unit is 160 characters, longer content is automatically billed as multiple parts.

Send SMS

Creates and queues one or many messages atomically. The sender name (if provided) must be approved, enabled, and owned by, assigned to, or a shared default for the caller. Unknown recipients are auto-created as contacts. Balance (or postpaid limit) is checked and deducted in the same transaction. Admins send for free.

Single message

Bulk messages

Send to many receivers in one call by adding more entries to messages:

Scheduled send

Set is_scheduled and a future scheduled_date. The message is stored with status scheduled and picked up by the background sender once due:

Response

On success the endpoint returns 201 Created with no payload. The message is queued, not returned inline. Look it up afterwards with Get Message by ID or List Messages, or subscribe to status webhooks.

Errors

Send via WhatsApp

The same POST /messages endpoint sends WhatsApp messages when channel is "whatsapp". Every WhatsApp send is a template send, freeform content isn't supported on this channel, use template_params per recipient instead.

Errors

List Messages

Paginated list of messages the caller owns (or all messages, for admins).

There's also GET /messages/search?search=…, which accepts the same pagination parameters and matches against message content and recipient.

Get Message by ID

Fetch a single message, including its joined sender name, recipient and contact name.

Message object

Errors

OTP API

Send one-time passcodes for login, signup or transaction confirmation, and verify them server-side. OTPs are single-use and expire after 30 minutes.

Send OTP

Sends a 6-digit code by SMS (and by email, if email_address is provided). Without sender_name, the code is delivered for free via the system sender. With a custom, approved sender_name, delivery is billed like a normal message from the caller's balance. This is the flow resellers integrate with to send OTPs under their own brand.

Sending over WhatsApp

Set channel to "whatsapp" and whatsapp_source to pick which registered number sends it. sender_name is ignored on this channel:

Errors

Verify OTP

Consumes a code, each OTP can only be verified once. This endpoint is public, so it can be called directly from a client app during signup or login flows, without an API key.

Errors

Sender Names

Request your own branded sender name instead of sending under the shared system sender, manage who on your account can use it, and track its review status.

Request a Sender Name

Errors

List Sender Names

Returns sender names you created, are assigned to, or that are the shared default, plus your customers' if you're a reseller.

GET /sender-names/search?search=… accepts the same filters plus a search term matched against name and status. GET /sender-names/{id} fetches one by id.

Sender name object

Every response includes these fields, regardless of whose sender name it is:

Update a Sender Name

You can update a sender name you own; a reseller can also update their customers'.

Assign Users

Replaces the full list of user ids allowed to send with this sender name, send the complete list each time, not just additions.

Delete a Sender Name

DELETE /sender-names/bulk takes { "ids": ["…", "…"] } to delete several at once.

Credits

Buy SMS credit programmatically instead of through the portal's checkout: browse the bundle prices available to your account, create a purchase, and track it to payment.

Check Balance

Returns the SMS and WhatsApp wallet balance available to your account, so you can check you have enough credit before sending instead of reacting to a failed send.

sms_balance is your remaining SMS credit count, whatsapp_balance is your remaining WhatsApp wallet balance in USD. withdraw_balance and balance_threshold only apply to reseller accounts and to the low-balance alert set in the portal, respectively.

Browse Bundles

Lists the price tiers available for your account to buy against. The tier your amount is checked against on Buy Credit is resolved the same way: a bundle assigned to you, else one created for your account type, else the platform default.

items is a list of { from, to, price } tiers, price is the per-SMS retail price for a purchase whose quantity falls in that from–to range. The paginated GET /bundles?condition=buy accepts the same filter.

Buy Credit

Creates a pending purchase. Give a customer_phone_number and a mobile-money USSD prompt is sent to that number; without one, arrange payment and confirm it with Check Purchase Status once it's done.

Errors

Check Purchase Status

Manually re-checks a pending purchase with the payment gateway, useful if you'd rather poll than rely on the webhook. A background job also does this automatically roughly every 30 seconds for recent pending purchases.

Returns 200 OK once the gateway confirms payment (the purchase is now paid). Anything else, still pending, or a gateway-reported failure, comes back as 400; check back later or via the webhook rather than retrying immediately.

List Purchases

Paginated list of purchases you own.

GET /purchases/search?search=… accepts the same filters. GET /purchases/{id} fetches one by id.

Webhooks

Register a webhook URL to get pushed status updates instead of polling for them. Every callback shares the same envelope shape, with an entity field telling you which kind of update it is.

Registering a webhook URL

Webhook URLs are account configuration, not an API call, there's no endpoint to set or change one programmatically. Set them from your account in the Keltap portal (the API section):

• Per API key: each of your API keys can carry its own webhook_url, set when the key is created or changed later. Sender name and purchase status callbacks are routed to the webhook_url of the key that was used to create that sender name request or purchase.
• Account default: your account also has one default webhook_url, used for every message delivery-status callback (these aren't routed per key), and as the fallback for sender name/purchase callbacks when the creating key has none set of its own, or the record was created from the portal rather than through the API.

Message Status Callback

Delivery status is checked roughly every 30 seconds. Whenever a message you own transitions to delivered or undelivered, Keltap sends an HTTP POST with a JSON body to your account's default webhook_url:

A message moves through scheduled → sending → processing → sent → delivered | undelivered | failed. Only the delivered / undelivered transitions above are pushed to your webhook; poll List Messages if you also need to observe earlier stages like sending or sent.

Sender Name Status Callback

Fired whenever an admin approves, declines, or enables/disables a sender name request you created, to the webhook_url of the API key that created it (or your account default, see Registering a webhook URL above):

Purchase Status Callback

Fired when a bundle purchase's payment is confirmed, to the webhook_url of the API key that created the purchase (or your account default):

SMPP

SMPP is the protocol most messaging platforms and gateways already speak. If your software can send over SMPP, connect it to Keltap instead of integrating the HTTP API. Messages cost the same and are billed to the same account, balance and sender names; the two ways of sending can be used side by side.

Getting Access

It is self-serve and free, like the API. Sign in to the Keltap portal and open the API section, then SMPP access:

1. Create a login. Give it a label you'll recognise, such as "Billing system", and list the IP addresses your software will connect from.
2. Copy the system_id and password the portal shows. The password is shown once; only a hash is stored, so if you lose it you reset it and get a new one.
3. Put the server, port, system_id and password into your SMPP client and bind.

Resellers and their customers get the same section for their own accounts. A sub-customer's messages are billed from their own balance and use only the sender names assigned to them. API keys can't manage SMPP logins: that is done from the portal while signed in.

You can switch a login off, reset its password, change its address list or delete it at any time. Each of those closes the connections using it at once. Keltap can also suspend a login, for example if it is being abused; a suspended login can't be switched back on by its owner.

Connection Settings

Static vs Dynamic IP

A login only accepts connections from the IP addresses you listed, because an SMPP password is limited to 8 characters and can't be as strong as an API key. The list is your main protection.

• Use a static IP. Connect from a server with a fixed address, for example a cloud server with a reserved or elastic IP, or one behind a NAT gateway that has a fixed address.
• If your address changes, connections from the new one are refused (ESME_RBINDFAIL), your software keeps retrying and messages fail until you add the new address in the portal. Changing the list also ends any connection that is open, so update it at a quiet moment.
• Don't use a wide range to get around this. We accept single addresses and ranges of up to 256 addresses (IPv6: a /48), only public internet addresses, and at most 10 entries per login.
• Serverless or ever-changing environments: use the HTTP API, which works from anywhere with an API key.

Sending a Message

Send a normal submit_sm. Each one is processed by the same code as an HTTP send: the sender name is checked, the balance is checked and charged, and the message is queued. The message is billed in segments exactly as on the HTTP API.

The message_id in the submit_sm_resp is the message's id, the same one you see in the portal and in Get Message by ID. Keep it to match the delivery receipt.

In the portal's message report, messages sent this way are shown as sent via SMPP, and you can filter by it.

Delivery Receipts

Set registered_delivery to 1 and Keltap sends a deliver_sm with esm_class 0x04 when the message reaches a final state. Acknowledge each one with a deliver_sm_resp. The text uses the conventional format, and the receipted_message_id and message_state parameters are set as well:

• id is the message id from the submit_sm_resp.
• stat is DELIVRD, UNDELIV, EXPIRED or REJECTD.
• Only final results are sent. A message still being retried isn't reported as failed.
• Times are UTC.
• A receipt you didn't acknowledge is sent again after a growing delay. If you are not connected, receipts wait and are delivered when you bind again, for up to 72 hours. You need a receiving bind (transceiver or receiver) to get them.

Your account's webhook still fires for these messages as well, if you've set one.

Error Codes

Refusals come back as the command status of the bind_*_resp or submit_sm_resp.

Limits & Behaviour

• The limits above are per login and are the defaults. Ask support if you need more.
• Your account must be enabled and verified, as for the API. This is checked on every submit, so disabling the account stops a connected client at once.
• Not supported: scheduled delivery, split (UDH or sar_*) messages, and incoming (mobile-originated) messages.
• If your connection drops, reconnect and bind again. Receipts for messages sent in the meantime are waiting for you.

Code Samples

The samples use the popular open-source smpplib (Python), smpp (Node.js) and onlinecity/php-smpp (PHP) packages. Check the option names against the version you install. Replace the server, port, system_id, password and sender name with your own.

Support

Need help with integration, billing, or your account? The Keltap team is reachable through any of these channels.

Before you reach out

• Check the response envelope's error code against the tables on Request & Response Format and each endpoint's reference. Most integration issues surface there directly.
• Have your account email/phone and, if relevant, the message or OTP id handy.
• For delivery problems, include the message status and, if you have it, the id from Get Message by ID.