Build messaging into
your everyday workflows.
A practical guide to authentication, SMS requests, credit usage and delivery tracking.
Getting started
Connect your application to Ctech SMS in three steps.
Get your credentials
Ask your administrator to activate your account and provide a Client ID and API client secret and assign your gateway connection.
Send a request
Use HTTPS, provide a Bearer credential and include a unique Idempotency-Key for every business event.
Track the result
Save the request_id and check recipient outcomes. Configure an approved callback for completion notifications.
https://sms-gateway-api.ctechapp.com/api/v1Replace example values with your issued credentials. Keep credentials on your application's server.
Authentication
Exchange your Client ID and API client secret for a temporary access token. Use that token for API requests. Your manually assigned gateway API key is configured by your administrator and is never used as a Bearer token. Once assigned, view or copy it from API & integrations after confirming your sign-in password.
Use your access token
Send the access_token returned by /auth/token in the Authorization header. Treat the complete value as a secret.
Authorization: Bearer YOUR_ACCESS_TOKENObtain an access token · Client ID and API client secret
/auth/token| Field | Type | Required | Description |
|---|---|---|---|
| client_id | string | Yes | Your stable integration identifier. |
| client_secret | string | Yes | Your API client secret, separate from your sign-in password. |
curl -X POST "https://sms-gateway-api.ctechapp.com/api/v1/auth/token" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'{
"status": "success",
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_at": "2026-10-17T12:00:00.000000Z"
}Use access_token as your Bearer credential until expires_at. After expiry, request a new token. Changing the client secret revokes existing access tokens. Your manually assigned gateway API key remains unchanged.
Send SMS
Submit a common message, or personalise the text for each recipient.
/sms/requests| Field | Type | Required | Description |
|---|---|---|---|
| recipients | array | Yes | 1–1,000 recipient objects. Duplicate normalised numbers are rejected. |
| recipients[].phone | string | Yes | Malawi local number (0999123456) or international format (+265999123456). |
| recipients[].external_reference | string | No | Your reference for this recipient, up to 255 characters. |
| message | string | Conditional | Common message, up to 1,000 characters. Required unless every recipient has a message. |
| recipients[].message | string | Conditional | Overrides the common message for this recipient. |
| sender_id | string | No | An assigned sender ID. Omit to use your default. |
| callback_url | HTTPS URL | No | Must exactly match the callback URL approved for your account. |
| metadata | object | No | Your business context, returned with the request and completion callback. |
curl -X POST "https://sms-gateway-api.ctechapp.com/api/v1/sms/requests" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" -H "Idempotency-Key: application-42-notification" -d '{"message":"Your application has been received.","recipients":[{"phone":"0999123456","external_reference":"application-42"}]}'<?php
$payload = [
'message' => 'Your application has been received.',
'recipients' => [['phone' => '0999123456', 'external_reference' => 'application-42']],
];
$ch = curl_init('https://sms-gateway-api.ctechapp.com/api/v1/sms/requests');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CTECH_SMS_API_KEY'),
'Accept: application/json',
'Content-Type: application/json',
'Idempotency-Key: application-42-notification',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
if ($body === false) { throw new RuntimeException(curl_error($ch)); }
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($body, true);import os
import requests
response = requests.post(
"https://sms-gateway-api.ctechapp.com/api/v1/sms/requests",
headers={
"Authorization": "Bearer " + os.environ["CTECH_SMS_API_KEY"],
"Accept": "application/json",
"Idempotency-Key": "application-42-notification",
},
json={
"message": "Your application has been received.",
"recipients": [{"phone": "0999123456", "external_reference": "application-42"}],
},
timeout=30,
)
print(response.status_code, response.json())// Run on your application's server, keeping the key in its environment.
const response = await fetch('https://sms-gateway-api.ctechapp.com/api/v1/sms/requests', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CTECH_SMS_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json',
'Idempotency-Key': 'application-42-notification',
},
body: JSON.stringify({
message: 'Your application has been received.',
recipients: [{ phone: '0999123456', external_reference: 'application-42' }],
}),
});
console.log(response.status, await response.json());Accepted response · HTTP 202
{"status":"processing","request_id":"01931e12-0000-7000-8000-000000000042"}Acceptance means your request has entered processing. It does not confirm delivery to the recipient's handset.
Personalised messages
Send different text within the same request.
{
"recipients": [
{"phone":"0999123456","message":"Hello Ruth, your application is ready."},
{"phone":"0888123456","message":"Hello Alex, your application is ready."}
],
"metadata": {"campaign":"application-updates"}
}Each recipient is charged according to their message length and your account rate. Invalid numbers are reported as failures and do not consume credits. A request containing only invalid numbers is rejected.
Safe retries & idempotency
Prevent duplicate requests when your application retries a business event.
Idempotency-Key: application-42-notification| Situation | Result |
|---|---|
| New key and valid request | HTTP 202 with a new request_id. |
| Same key and matching payload | HTTP 200 with the existing request_id; no duplicate submission. |
| Same key and changed payload | HTTP 409. Use a new key only for a genuinely new event. |
Keys are scoped to your account, limited to 120 characters and retained with the request. Keep the request payload unchanged when retrying. If the network response is lost, reuse the same key rather than inventing a new one.
Check request status and recipient outcomes first. An unknown submission may already have been sent and needs support review.
Request status
Use the returned request_id to follow processing.
/sms/requests/{request_id}{
"data": {
"request_id": "01931e12-0000-7000-8000-000000000042",
"request_status": "completed",
"total_count": 1,
"success_count": 1,
"failure_count": 0,
"sender_id": "CTECH",
"metadata": null,
"created_at": "2026-10-16T12:00:00.000000Z"
}
}| Status | Meaning |
|---|---|
| processing | One or more recipients are queued, being submitted or awaiting reconciliation. |
| completed | Submission processing is complete. Final delivery updates may still arrive. |
Poll at a moderate interval, for example every five seconds, and stop when your application has enough information. Every status request counts towards your API rate limit.
Recipient outcomes
Inspect the outcome and credit state for each recipient.
/sms/requests/{request_id}/recipients?page=1Results are paginated, with up to 100 recipients per page. Follow next_page_url when it is present.
{
"current_page": 1,
"data": [{
"phone": "0999123456",
"normalized_phone": "+265999123456",
"message": "Your application has been received.",
"status": "delivered",
"external_reference": "application-42",
"credit_units": 1,
"billing_status": "charged",
"error_reason": null
}],
"next_page_url": null,
"per_page": 100,
"total": 1
}| Recipient status | Meaning |
|---|---|
| pending | Waiting for submission. |
| sending | Submission is in progress. |
| sent | The message submission was accepted. |
| delivered | Delivery has been confirmed. |
| failed | Submission or delivery failed; inspect billing_status separately. |
| unknown | The submission outcome is uncertain; contact support before resending. |
Account & credits
Read your available balance before a larger send.
/account{
"client_id": "YOUR_CLIENT_ID",
"name": "Example School",
"balance": 1000,
"reserved": 10,
"available": 990,
"credits_per_segment": 1,
"sender_id": "CTECH"
}Available credits equal balance minus reserved credits. Credits are reserved when your request enters processing, charged when submission is accepted, and released if submission is rejected. An uncertain outcome keeps its reservation until reviewed.
The rate is an integer number of credits per SMS segment. Standard text uses up to 160 characters in a single segment; longer text normally uses 153 characters per segment. Unicode uses up to 70 UTF-16 units in a single segment, or 67 per concatenated segment. Some symbols use extra space.
A later delivery failure does not automatically refund an accepted submission. Changing a rate affects new submissions; existing reservations keep their original rate.
Completion callbacks
Receive a signed notification when submission processing completes.
Ask your administrator to approve your public HTTPS callback URL. The URL in a send request must match that approved value. Your endpoint should return a successful HTTP response promptly and process repeated notifications idempotently by request_id.
{
"status":"completed",
"request_id":"01931e12-0000-7000-8000-000000000042",
"success_count":1,
"failure_count":0,
"failures":[],
"metadata":{"event":"application-42"},
"completed_at":"2026-10-16T12:01:00.000000Z"
}Verify the signature
Use the callback signing secret issued with your gateway credentials. The X-SMS-Gateway-Signature header contains a hexadecimal HMAC-SHA256 over the compact JSON representation of the parsed payload, preserving field order and Unicode escaping while leaving forward slashes unescaped. Do not sign the incoming whitespace-formatted text directly.
$payload = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
$canonical = json_encode($payload, JSON_UNESCAPED_SLASHES);
$expected = hash_hmac('sha256', $canonical, $callbackSigningSecret);
if (!hash_equals($expected, $receivedSignature)) {
http_response_code(401);
exit;
}Callbacks describe submission completion. Use recipient status checks for later delivery outcomes. Failed callback delivery may be retried, so duplicates must be safe.
Errors & troubleshooting
Use the HTTP status and validation fields to decide what to do next.
| HTTP | Meaning | Next step |
|---|---|---|
| 400 | Missing or invalid Idempotency-Key. | Provide a nonempty key of up to 120 characters. |
| 401 | Missing, expired or invalid credentials. | Check your key or exchange your client credentials again. |
| 403 | Account access, IP policy or permission denied. | Check account activation, allowed IPs and credential permissions. |
| 404 | Resource was not found. | Check the request_id and account. |
| 409 | Request conflict or messaging setup pending. | Inspect the message; do not change retry keys blindly. |
| 422 | Invalid payload or insufficient credits. | Correct the fields in errors, or top up your account. |
| 429 | API request rate exceeded. | Slow down and respect the Retry-After response header. |
| 500 / 503 | Temporary service error. | Check status before retrying, preserving the original key. |
{
"message":"Insufficient available SMS credits.",
"errors":{"credits":["Insufficient available SMS credits."]}
}Keep secrets out of error reports. When contacting support, include the request_id, time and your own business reference.
Integration tools
Download the reference files or test from your workspace.