Send SMS

Send a single SMS message to one recipient. Charges are deducted from your wallet immediately.

Endpoint

POST /v1/sms/send/

Authentication: Bearer API key

Request Body

{
  "mobile":    "254712345678",
  "message":   "Hello! Your order #1234 has been shipped.",
  "sender_id": "TALKNTALK"
}

Field	Type	Required	Description
`mobile`	string	Yes	Recipient phone number in international format (`254XXXXXXXXX`)
`message`	string	Yes	SMS body — up to 160 characters per SMS part
`sender_id`	string	No	Sender name to show on recipient's device. Defaults to your organisation's default sender ID.

Request

curl -X POST https://api.talkntalk.africa/v1/sms/send/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile":    "254712345678",
    "message":   "Hello from TalkNTalk!",
    "sender_id": "TALKNTALK"
  }'

Response

201 Created

{
  "id":         "018f3a2b-7c4d-7e1a-b3f2-9d8e2c1a4b5f",
  "mobile":     "254712345678",
  "sender_id":  "TALKNTALK",
  "message":    "Hello from TalkNTalk!",
  "status":     "queued",
  "created_at": "2026-05-20T11:30:00+03:00"
}

Field	Description
`id`	UUID — use this to look up the message in Fetch Messages
`status`	`queued` — message is being dispatched to the provider
`mobile`	Recipient number as submitted
`sender_id`	Sender name used

The message transitions from queued → sent → delivered as the provider processes it. Use Webhooks to get notified on each status change.

Code Examples

Node.js

const res = await fetch('https://api.talkntalk.africa/v1/sms/send/', {
  method:  'POST',
  headers: {
    'Authorization': 'Bearer tk_live_xxxx',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    mobile:    '254712345678',
    message:   'Hello from TalkNTalk!',
    sender_id: 'TALKNTALK',
  }),
});
const msg = await res.json();
console.log('Message ID:', msg.id, '| Status:', msg.status);

Python

import requests
 
r = requests.post(
    'https://api.talkntalk.africa/v1/sms/send/',
    headers={'Authorization': 'Bearer tk_live_xxxx'},
    json={
        'mobile':    '254712345678',
        'message':   'Hello from TalkNTalk!',
        'sender_id': 'TALKNTALK',
    },
)
msg = r.json()
print(f"ID: {msg['id']} | Status: {msg['status']}")

PHP

$ch = curl_init('https://api.talkntalk.africa/v1/sms/send/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer tk_live_xxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'mobile'    => '254712345678',
        'message'   => 'Hello from TalkNTalk!',
        'sender_id' => 'TALKNTALK',
    ]),
]);
$msg = json_decode(curl_exec($ch), true);
echo "ID: {$msg['id']} | Status: {$msg['status']}";

Rate Limits

This endpoint is limited to 300 requests per minute per organisation. Exceeding the limit returns HTTP 429. See Rate Limits for retry strategies.

Error Responses

Status	Code	Description
`400 Bad Request`	—	`mobile` or `message` missing, or invalid `sender_id`
`401 Unauthorized`	`authentication_failed`	Missing or invalid API key
`402 Payment Required`	`insufficient_balance`	Wallet balance too low
`429 Too Many Requests`	—	Rate limit exceeded — retry after the `Retry-After` header

Sender IDs Send Bulk SMS