Twatumi Documentation
Twatumi is Namibian messaging infrastructure for modern applications. Send transactional messages, OTP codes and notifications by SMS, WhatsApp or both from your website, mobile app or backend system through one versioned REST API — you choose the channel on every call.
The customer dashboard is administrative only — you manage your wallet, API tokens, webhooks and reporting there. All sending happens through the API described below.
Quick Start
- Create your Twatumi account and verify your email.
- Generate a test token (
tw_test_) from API Tokens in your dashboard — it's free and needs no top-up. - Send your first request to
https://sms.cheleteh.com/v1/messagesand watch it appear under Messages. - When your integration works, top up your wallet (EFT or mobile wallet) and swap in a
tw_live_token.
curl -X POST https://sms.cheleteh.com/v1/messages \
-H "Authorization: Bearer tw_test_xxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to": "264811234567", "message": "Your verification code is 483921"}'
Authentication
Every request must include your API token as a Bearer token:
Authorization: Bearer tw_live_xxxxxxxxxxxxxxxxxxxxxxxxx
Twatumi never stores your raw token — only a cryptographic hash and a display prefix. Copy your token when it is generated; it cannot be shown again.
API Tokens
Tokens are environment-scoped and permission-scoped:
tw_live_...— sends real SMS and WhatsApp messages and spends your wallet balance.tw_test_...— authenticates and validates normally, creates test message logs, simulates delivery, and never spends wallet funds or contacts a real provider.
Scopes: sms:send, sms:read, balance:read, webhooks:manage. Every request is checked against the token's granted scopes. sms:send and sms:read cover every channel, WhatsApp included.
Sending SMS
POST https://sms.cheleteh.com/v1/messages
{
"to": "264811234567",
"message": "Your verification code is 483921",
"channel": "sms",
"reference": "LOGIN-48291",
"callback_url": "https://example.com/twatumi/callback"
}
channel is optional and decides how the message goes out on this call: sms (the default), whatsapp, or both. See Sending WhatsApp.
Response:
{
"success": true,
"message": "SMS accepted for delivery.",
"data": {
"message_id": "sms_01jabc123xyz",
"channel": "sms",
"status": "queued",
"to": "264811234567",
"reference": "LOGIN-48291",
"segments": 1,
"cost": 0.50,
"currency": "NAD",
"environment": "live",
"messages": [ { "message_id": "sms_01jabc123xyz", "channel": "sms", "status": "queued", … } ]
}
}
Messages are queued and delivered asynchronously — the provider is never contacted inline during the request. Send an Idempotency-Key header to safely retry a request without sending (or being charged for) the message twice. A key belongs to one channel selection — reusing it with a different channel returns IDEMPOTENCY_KEY_REUSED.
Sending WhatsApp
Use the same endpoint with "channel": "whatsapp". WhatsApp is billed per message — there are no segments.
{
"to": "264811234567",
"channel": "whatsapp",
"message": "Hi Anna, your order #4821 is ready for collection."
}
The 24-hour window and templates
WhatsApp only delivers free-form text to someone who messaged your business number in the last 24 hours. To start a conversation — an OTP, a reminder, a delivery notice — send a template pre-approved by WhatsApp instead, identified by its Twilio Content SID. Variables fill the template's {{1}}, {{2}}… placeholders. With a template, message can be left out.
{
"to": "264811234567",
"channel": "whatsapp",
"whatsapp_template": {
"content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
"variables": { "1": "483921" }
}
}
Free-form text sent outside the window fails with the reason "Outside the 24-hour WhatsApp session window" and a whatsapp.failed webhook.
Sending on both channels
"channel": "both" sends one SMS and one WhatsApp message in a single call. Each gets its own message_id (sms_… / wa_…), price, status and webhooks. The call is all-or-nothing: if your wallet can't cover both, neither is sent. When you also pass a whatsapp_template, WhatsApp uses the template and message is the SMS text.
{
"success": true,
"message": "SMS and WhatsApp messages accepted for delivery.",
"data": {
"channel": "both",
"to": "264811234567",
"reference": "LOGIN-48291",
"cost": 1.30,
"currency": "NAD",
"environment": "live",
"messages": [
{ "message_id": "sms_01jabc123xyz", "channel": "sms", "status": "queued", "segments": 1, "cost": 0.50, … },
{ "message_id": "wa_01jabc456uvw", "channel": "whatsapp", "status": "queued", "segments": 1, "cost": 0.80, … }
]
}
}
Message Status
GET https://sms.cheleteh.com/v1/messages/{message_id}
{
"success": true,
"data": {
"message_id": "sms_01jabc123xyz",
"channel": "sms",
"to": "264811234567",
"status": "delivered",
"reference": "LOGIN-48291",
"segments": 1,
"cost": 0.50,
"currency": "NAD",
"sent_on": "2026-09-16T10:20:02+02:00",
"delivered_on": "2026-09-16T10:20:06+02:00"
}
}
Status values: queued, processing, sent, delivered, failed, rejected, cancelled. A WhatsApp message that has been read also reports delivered.
Balance
GET https://sms.cheleteh.com/v1/balance
{
"success": true,
"data": { "balance": 485.72, "currency": "NAD" }
}
Webhooks
Configure an endpoint in your dashboard and subscribe to: sms.queued, sms.sent, sms.delivered, sms.failed, sms.rejected, whatsapp.queued, whatsapp.sent, whatsapp.delivered, whatsapp.failed, wallet.low_balance. Every message payload includes its channel.
Every delivery is signed with HMAC-SHA256 and includes:
X-Twatumi-Event: sms.delivered X-Twatumi-Signature: 5f9e1c... X-Twatumi-Delivery: whd_01jabc... X-Twatumi-Timestamp: 1758012345
Verify a delivery by recomputing HMAC_SHA256("{timestamp}.{raw_body}", your_webhook_secret) and comparing it to X-Twatumi-Signature. Failed deliveries retry with exponential backoff and can be retried manually from the dashboard.
Test Mode
Requests made with a tw_test_ token authenticate and validate exactly like production, create a message log clearly marked TEST, and simulate delivery — but never contact a real SMS or WhatsApp provider and never spend your wallet balance. In test mode a destination ending in 0000 is always rejected, so you can exercise your failure handling.
Error Codes
Errors follow a standard envelope:
{
"success": false,
"message": "Insufficient wallet balance: this needs N$0.50 but the wallet holds N$0.20. Top up at …",
"error": { "code": "INSUFFICIENT_BALANCE" }
}
| Code | HTTP | Meaning |
|---|---|---|
| INVALID_TOKEN | 401 | Token missing, unknown or revoked |
| TOKEN_EXPIRED | 401 | Token has passed its expiry date |
| INSUFFICIENT_SCOPE | 403 | Token lacks the required scope |
| ACCOUNT_SUSPENDED | 403 | Organisation is suspended |
| MESSAGE_NOT_FOUND | 404 | No message with that ID for your organisation |
| IDEMPOTENCY_KEY_REUSED | 409 | Idempotency-Key already used for a different channel selection |
| INVALID_DESTINATION | 400 | Destination number could not be normalised |
| INVALID_MESSAGE | 400 | Message body missing or too long |
| VALIDATION_FAILED | 422 | Request failed field validation |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
| INSUFFICIENT_BALANCE | 402 | Wallet balance too low for this send |
| MONTHLY_FEE_UNPAID | 402 | Wallet balance too low to cover this month's platform fee — top up to resume sending |
| PROVIDER_UNAVAILABLE | 503 | No healthy SMS or WhatsApp provider available |
| INTERNAL_ERROR | 500 | Unexpected server error |
Rate Limits
Limits apply per API token, per organisation and per IP address, based on your pricing plan (default 60 requests/minute). Every response includes:
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1758012400
Phone Numbers
Namibian numbers are normalised automatically: 0811234567, +264811234567 and 264811234567 are all stored and billed as 264811234567.
SMS Segments
GSM-7 messages: 160 characters in a single segment, 153 characters per segment once multipart. Unicode messages: 70 characters single segment, 67 characters per segment multipart. You are billed per segment. Segments apply to SMS only — WhatsApp is billed per message, up to 1,600 characters.
Security
- API tokens are hashed at rest and shown once at creation.
- Webhook payloads are signed with HMAC-SHA256.
- Organisation data is strictly isolated — every query is scoped to your organisation.
- Optional TOTP two-factor authentication is available for your dashboard login.
Code Examples
cURL
curl -X POST https://sms.cheleteh.com/v1/messages \
-H "Authorization: Bearer tw_live_xxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to": "264811234567", "message": "Your verification code is 483921"}'
PHP
$ch = curl_init('https://sms.cheleteh.com/v1/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer tw_live_xxxxxxxxx',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '264811234567',
'message' => 'Your verification code is 483921',
]),
]);
$response = json_decode(curl_exec($ch), true);
CodeIgniter 4
$response = service('curlrequest')->post('https://sms.cheleteh.com/v1/messages', [
'headers' => [
'Authorization' => 'Bearer ' . env('TWATUMI_API_TOKEN'),
'Content-Type' => 'application/json',
],
'json' => ['to' => '264811234567', 'message' => 'Your verification code is 483921'],
]);
$data = json_decode($response->getBody(), true);
JavaScript
const res = await fetch('https://sms.cheleteh.com/v1/messages', {
method: 'POST',
headers: {
'Authorization': 'Bearer tw_live_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '264811234567', message: 'Your verification code is 483921' }),
});
const data = await res.json();
Node.js
const https = require('https');
const body = JSON.stringify({ to: '264811234567', message: 'Your verification code is 483921' });
const req = https.request('https://sms.cheleteh.com/v1/messages', {
method: 'POST',
headers: {
'Authorization': 'Bearer tw_live_xxxxxxxxx',
'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(body),
},
}, (res) => { res.on('data', (d) => process.stdout.write(d)); });
req.write(body);
req.end();
Python
import requests
response = requests.post(
"https://sms.cheleteh.com/v1/messages",
headers={"Authorization": "Bearer tw_live_xxxxxxxxx"},
json={"to": "264811234567", "message": "Your verification code is 483921"},
)
data = response.json()
C#
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "tw_live_xxxxxxxxx");
var payload = new { to = "264811234567", message = "Your verification code is 483921" };
var response = await client.PostAsJsonAsync("https://sms.cheleteh.com/v1/messages", payload);
var data = await response.Content.ReadAsStringAsync();
Java
HttpClient client = HttpClient.newHttpClient();
String body = """
{"to": "264811234567", "message": "Your verification code is 483921"}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://sms.cheleteh.com/v1/messages"))
.header("Authorization", "Bearer tw_live_xxxxxxxxx")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
Flutter (Dart)
final response = await http.post(
Uri.parse('https://sms.cheleteh.com/v1/messages'),
headers: {
'Authorization': 'Bearer tw_live_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: jsonEncode({
'to': '264811234567',
'message': 'Your verification code is 483921',
}),
);
final data = jsonDecode(response.body);
Integrate With an AI Coding Assistant
Using Claude Code, Cursor, GitHub Copilot Chat or a similar AI coding assistant on your own codebase? Paste the prompt below into it as-is. It contains everything the assistant needs to know about the Twatumi API — it will read your codebase, follow your project's existing conventions, and wire up SMS sending for you, asking where it's unsure rather than guessing.
You are integrating the Twatumi messaging API (SMS and WhatsApp) into this codebase. Read the existing codebase first, then wire up message sending through Twatumi, matching this project's existing conventions (language, framework, HTTP client, error handling, secrets/config management, and testing style) rather than introducing new ones.
Twatumi API reference:
- Base URL: https://sms.cheleteh.com/v1 (the same URL for live and test — the environment is decided by the token prefix, not a different host)
- Auth: `Authorization: Bearer <token>` header. Token is either `tw_live_...` (sends real messages, spends wallet balance) or `tw_test_...` (authenticates and validates normally, logs a message, simulates delivery — never sends or charges).
- Send: `POST /messages`
body: {"to": "264811234567", "message": "...", "channel": "sms | whatsapp | both (default sms)", "reference": "optional-your-own-id", "callback_url": "optional https URL Twatumi POSTs a status update to"}
- `to` accepts Namibian numbers as 0811234567, +264811234567 or 264811234567 — normalised automatically. Reject/validate other formats before sending.
- `channel` picks the delivery channel per call. "both" sends one SMS and one WhatsApp message, each with its own message_id, cost and status; the call is all-or-nothing (both are charged and queued, or neither).
- WhatsApp only delivers free-form `message` text within 24 hours of the recipient last messaging the business. Outside that window send a pre-approved template instead: "whatsapp_template": {"content_sid": "HX...", "variables": {"1": "483921"}} (a Twilio Content SID). With channel "whatsapp" and a template, `message` may be omitted; with "both", `message` is the SMS text.
- Optional `Idempotency-Key` header: the same organisation + token + key can never send (or be charged for) the same message twice. Always send one whenever the call could be retried (e.g. a timeout on your side).
- Success: 201, {"success": true, "data": {"message_id", "channel", "status", "segments", "cost", "currency", "messages": [...]}}. `data.messages` always lists one entry per channel sent; for channel "both" read the per-channel message_id/status from it (there is no top-level message_id).
- Failure: {"success": false, "message": "...", "error": {"code": "..."}}. Handle at least: INSUFFICIENT_BALANCE (402), RATE_LIMIT_EXCEEDED (429 — back off using the Retry-After header), VALIDATION_FAILED (422), INVALID_DESTINATION (400), ACCOUNT_SUSPENDED (403).
- Status: `GET /messages/{message_id}` — same envelope, includes `channel`; `status` is one of queued, processing, sent, delivered, failed, rejected, cancelled.
- Balance: `GET /balance` — {"balance": 485.72, "currency": "NAD"}.
- Webhooks (only if this app needs push status updates instead of polling GET /messages/{id}): register an endpoint in the Twatumi dashboard, subscribe to sms.delivered / sms.failed (and whatsapp.delivered / whatsapp.failed if sending WhatsApp), and verify every delivery by recomputing HMAC_SHA256("{timestamp}.{raw_body}", your_webhook_secret) against the X-Twatumi-Signature header before trusting the payload — never process an unverified one.
What I need you to do:
1. Find (or ask me) where this project already sends outbound notifications and how it manages secrets/config (env vars, a settings service, etc.). Store TWATUMI_API_TOKEN there the same way — never hardcode it.
2. Add one small, typed helper/service that sends a single message on the requested channel(s) and returns a clear success/failure result, built on this project's existing HTTP client rather than a new dependency. Ask me which channel(s) each flow should use if it isn't obvious.
3. Wire it into [TELL THE ASSISTANT WHERE — e.g. "the OTP flow", "the order-shipped notification", "the appointment reminder job" — ask me if it isn't obvious from the codebase].
4. Handle the error codes above explicitly instead of swallowing them, and make retries safe with the Idempotency-Key header.
5. Use a tw_test_ token while building this, and tell me exactly what to change to go live.
6. Add a test, matching this project's existing test setup, that mocks the Twatumi API call and asserts the request shape plus at least one success and one failure path.
Ask me anything you need (which flow to hook this into, which field holds the phone number, whether an HTTP client wrapper already exists) before making changes.
The prompt intentionally leaves one thing for you to fill in or for the assistant to ask you about — which part of your app should trigger a send (e.g. after order confirmation, on OTP request). Everything else — the endpoint, auth, error codes, idempotency and webhook verification — is fully specified.