Send reliable SMS from your applications.

How the gateway works

The Ctech SMS Gateway sits between your application and the SMS provider. Your system authenticates, submits a request, stores the returned request_id, then tracks processing through polling or a callback.

Send your first message

Request an access token, then use it to submit an SMS request. Replace all placeholder values with credentials issued privately by Ctech.

1. Request a token

curl --request POST \
  'https://sms-gateway-api.ctechapp.com/api/v1/auth/token' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

2. Submit the message

curl --request POST \
  'https://sms-gateway-api.ctechapp.com/api/v1/sms/requests' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Idempotency-Key: appointment-1042-v1' \
  --data '{
    "recipients": [
      {
        "phone": "0991234567",
        "external_reference": "patient-1042"
      }
    ],
    "message": "Reminder: your appointment is tomorrow at 09:00.",
    "sender_id": "YOUR_APPROVED_SENDER_ID",
    "metadata": {
      "source": "hms",
      "campaign": "appointment-reminders"
    }
  }'

Base URL and headers

All requests and callbacks use JSON over HTTPS. Protected endpoints require a Bearer token.

Endpoints

Exchange an active client_id and client_secret for a Sanctum Bearer token. Tokens contain the send:sms and read:sms-status abilities.

Request body

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

{
  "status": "success",
  "access_token": "1|plain_text_token",
  "token_type": "Bearer",
  "expires_at": "2026-07-20T10:07:20.815252Z"
}

Submit one or more Malawi mobile numbers. The endpoint accepts either one shared top-level message or a message on every recipient.

Single recipient

{
  "recipients": [
    {
      "phone": "0991234567",
      "external_reference": "invoice-8001"
    }
  ],
  "message": "Your payment of MWK 25,000 was received.",
  "sender_id": "YOUR_APPROVED_SENDER_ID"
}

One message to many recipients

{
  "recipients": [
    { "phone": "0991234567", "external_reference": "patient-1001" },
    { "phone": "0881234567", "external_reference": "patient-1002" },
    { "phone": "+265981234567", "external_reference": "patient-1003" }
  ],
  "message": "The clinic will close at 15:00 today.",
  "sender_id": "YOUR_APPROVED_SENDER_ID",
  "callback_url": "https://your-system.example/api/sms/callback",
  "metadata": {
    "source": "hms",
    "batch": "clinic-notice-20260720"
  }
}

Personalised messages

{
  "recipients": [
    {
      "phone": "0991234567",
      "external_reference": "appointment-1001",
      "message": "Hello Mary, your appointment is at 09:00."
    },
    {
      "phone": "0881234567",
      "external_reference": "appointment-1002",
      "message": "Hello James, your appointment is at 10:30."
    }
  ],
  "sender_id": "YOUR_APPROVED_SENDER_ID",
  "metadata": {
    "source": "hms",
    "batch": "personalised-reminders"
  }
}

When using recipient-level messages, omit the top-level message. If there is no top-level message, every recipient must contain a non-empty message.

Accepted response

{
  "status": "processing",
  "message": "SMS request received and is being processed",
  "request_id": "019f7ec9-5a06-71fa-965b-cf5c43c36667"
}

SMS request fields

Supported phone-number formats

The gateway removes spaces and punctuation, validates Malawi mobile prefixes, and normalises accepted values to +265....

Numbers must resolve to +265 followed by an 8 or 9 and eight additional digits.

Idempotency and safe retries

Every SMS submission must contain an Idempotency-Key. Generate one stable key for one logical submission and retain it when retrying after a timeout.

{
  "status": "error",
  "message": "Idempotency-Key has already been used with a different request payload.",
  "request_id": "019f7ec9-5a06-71fa-965b-cf5c43c36667"
}

Good keys include an order, appointment, invoice, or campaign identifier plus a version, for example invoice-8001-reminder-v1.

Returns the request-level summary. The request belongs to the authenticated client; another client receives 403 Forbidden.

curl --request GET \
  'https://sms-gateway-api.ctechapp.com/api/v1/sms/requests/REQUEST_ID' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "data": {
    "request_id": "019f7ec9-5a06-71fa-965b-cf5c43c36667",
    "request_status": "completed",
    "total_count": 3,
    "success_count": 2,
    "failure_count": 1,
    "message_preview": "The clinic will close at 15:00 today.",
    "sender_id": "YOUR_APPROVED_SENDER_ID",
    "callback_url": "https://your-system.example/api/sms/callback",
    "metadata": {
      "source": "hms"
    },
    "accepted_at": "2026-07-20T09:09:12.000000Z",
    "completed_at": "2026-07-20T09:09:31.000000Z",
    "created_at": "2026-07-20T09:09:12.000000Z"
  }
}

completed means there are no pending recipients. Inspect recipient results to distinguish provider-accepted, delivered, and failed messages.

Returns recipient-level status records, 100 per page. Use ?page=2 for later pages.

{
  "status": "success",
  "data": [
    {
      "id": 3,
      "sms_request_id": 3,
      "phone": "0991234567",
      "normalized_phone": "+265991234567",
      "external_reference": "patient-1001",
      "message": null,
      "status": "sent",
      "provider": "africastalking",
      "provider_message_id": "ATXid_example",
      "provider_cost": "17.0000",
      "provider_status": "Success",
      "error_reason": null,
      "sent_at": "2026-07-20T09:09:31.000000Z",
      "delivered_at": null,
      "created_at": "2026-07-20T09:09:12.000000Z",
      "updated_at": "2026-07-20T09:09:31.000000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total": 1,
    "last_page": 1
  }
}

Signed completion callbacks

If the request or API client has a callback URL, the gateway posts a completion summary after queue processing finishes. Callback delivery is retried and signed with the client-specific callback secret.

Callback headers

Content-Type: application/json
X-SMS-Gateway-Signature: <hex-hmac-sha256>
X-SMS-Gateway-Request-Id: 019f7ec9-5a06-71fa-965b-cf5c43c36667

Callback body

{
  "status": "completed",
  "request_id": "019f7ec9-5a06-71fa-965b-cf5c43c36667",
  "success_count": 2,
  "failure_count": 1,
  "failures": [
    {
      "phone": "+265881234567",
      "reason": "Invalid phone number format",
      "external_reference": "patient-1002"
    }
  ],
  "metadata": {
    "source": "hms",
    "batch": "clinic-notice-20260720"
  },
  "completed_at": "2026-07-20T09:09:31.000000Z"
}

Verify the signature in PHP

<?php

$rawBody = file_get_contents('php://input');
$payload = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
$received = $_SERVER['HTTP_X_SMS_GATEWAY_SIGNATURE'] ?? '';
$callbackSecret = getenv('SMS_GATEWAY_CALLBACK_SECRET');

// The gateway signs JSON_UNESCAPED_SLASHES output.
$canonicalJson = json_encode($payload, JSON_UNESCAPED_SLASHES);
$expected = hash_hmac('sha256', $canonicalJson, $callbackSecret);

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Process idempotently using payload.request_id.
http_response_code(200);

Verify the signature in Node.js

import crypto from 'node:crypto';

const canonicalJson = JSON.stringify(req.body);
const expected = crypto
  .createHmac('sha256', process.env.SMS_GATEWAY_CALLBACK_SECRET)
  .update(canonicalJson)
  .digest('hex');

const received = req.get('X-SMS-Gateway-Signature') ?? '';
const valid = received.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

if (!valid) return res.status(401).json({ message: 'Invalid signature' });
return res.sendStatus(200);

HTTP errors

{
  "status": "error",
  "message": "Invalid client credentials"
}

{
  "status": "error",
  "message": "No valid recipients were supplied.",
  "failures": [
    {
      "phone": "12345",
      "reason": "Invalid phone number format"
    }
  ]
}

Rate limits and retry strategy

Read the standard rate-limit response headers when present. On 429 or temporary 5xx failures, use exponential backoff with jitter. Reuse the same idempotency key when retrying the same SMS submission.

Postman and integration testing

Import the included collection, configure environment variables, and run tests in this order:

1. 1
   Generate token

   Confirm 200, save access_token, and note expiry.

2. 2
   Send one SMS

   Use a controlled recipient and a new idempotency key.

3. 3
   Repeat the identical request

   Confirm 200 and the same request ID, with no duplicate SMS.

4. 4
   Change the payload but keep the key

   Confirm 409 Conflict.

5. 5
   Poll request and recipients

   Confirm processing completes and inspect every failure.

6. 6
   Verify callback handling

   Confirm signature verification, idempotent processing, and 2xx acknowledgement.

Go-live checklist