Custom SMS API: field guide

1. Introduction

ISPMan supports sending automatic SMS notifications to your customers such as payment confirmations, hotspot expiry alerts, and PPPoE renewal reminders. To enable this, you connect ISPMan to any third-party SMS provider using the Custom SMS API Settings.

This guide walks you through every field in that settings form, explains what each one does, and provides ready-to-use examples for popular Kenyan SMS providers.

What ISPMan will do automatically:

Send a payment confirmation SMS when a customer pays
Send a hotspot expiry reminder before their session ends
Send a PPPoE expiry or renewal notification

All you need to do is fill in the settings form once, and ISPMan handles the rest.

2. Where to Find the SMS Settings

Log in to your ISPMan dashboard
Go to Comms → SMS → Settings (/dashboard/sms/settings) and scroll to the “Automatic SMS” and “Custom SMS API Settings” sections. See also SMS settings.
You will see toggle switches for each automatic message type and below that, the Custom SMS API Settings form

Automatic SMS Toggles:

Payment Confirmation
Hotspot Expiry SMS
PPPoE Payment Confirmation
PPPoE Expiry SMS

Make sure all the toggles you want are turned ON (blue) before saving your settings.

3. Fields in the Custom SMS API Settings Form

Field	What It Means	Example
SMS API URL	The full POST endpoint URL from your SMS provider’s API docs	`https://bulksms.talksasa.com/api/v3/sms/send`
Sender ID	Your registered sender name or brand shown to the recipient	`TALKSASA` / `MYBRAND`
API Key	Your secret authentication key from your SMS provider’s dashboard	Paste from provider dashboard
API Key Location	Where ISPMan should place the API key	`header:authorization:Bearer`
API Schema (JSON)	A JSON template describing the body of the POST request ISPMan will send	`{"message":"$MESSAGE","recipient":"$RECIPIENT_NUMBER",...}`

4. Understanding the API Schema (JSON)

The API Schema field is where you tell ISPMan exactly what the body of the HTTP POST request should look like when it sends an SMS. Every SMS provider has a slightly different format — this is where you match ISPMan to your provider.

4.1 Dynamic Placeholders

ISPMan automatically replaces these placeholders with real values at send time. They are case-sensitive:

Placeholder	Description
`$MESSAGE`	The SMS text content (auto-filled by ISPMan)
`$RECIPIENT_NUMBER`	Customer’s phone number with country code
`$SENDER_ID`	Your Sender ID as configured in the settings
`$API_KEY`	Your API Key as configured in the settings

4.2 How to Build Your JSON Schema

Your SMS provider’s API documentation will show you the exact fields their API expects. Replace the values with the matching ISPMan placeholder.

Example — if your provider expects this body:

{
  "to": "0712345678",
  "text": "Hello, this is a test",
  "from": "MYBRAND"
}

Your ISPMan JSON Schema becomes:

{
  "to": "$RECIPIENT_NUMBER",
  "text": "$MESSAGE",
  "from": "$SENDER_ID"
}

⚠️ Important: $MESSAGE and $RECIPIENT_NUMBER are always required. Your SMS will not be sent correctly if these are missing or misspelled.

5. API Key Location — How to Authenticate

Option A — Bearer Token in the Header (most common)

Enter exactly:

header:authorization:Bearer

ISPMan will send the header: Authorization: Bearer YOUR_API_KEY

Option B — API Key Inside the JSON Body

Some providers (e.g. BlessedTexts) expect the API key as a field in the JSON body. Leave the API Key Location field blank and include $API_KEY in your JSON Schema:

{"api_key":"$API_KEY","message":"$MESSAGE","phone":"$RECIPIENT_NUMBER","sender_id":"$SENDER_ID"}

Option C — API Key as a Query Parameter

If your provider requires the key as a URL query parameter, consult the ISPMan guide at ispman.tech/guides/sms_custom_api_schema for the correct syntax.

6. Example Configuration — TalkSasa

TalkSasa (bulksms.talksasa.com) uses a Bearer token in the Authorization header.

Field	Value
SMS API URL	`https://bulksms.talksasa.com/api/v3/sms/send`
Sender ID	`TALKSASA` (or your registered sender name)
API Key	Paste your API key from the TalkSasa dashboard
API Key Location	`header:authorization:Bearer`
API Schema	`{"message":"$MESSAGE","recipient":"$RECIPIENT_NUMBER","sender_id":"TALKSASA","type":"plain"}`

TalkSasa — Step by Step

Log in to your TalkSasa account and copy your API key from the dashboard
In ISPMan SMS Settings, paste the API URL shown above
Enter your registered Sender ID (e.g. TALKSASA or your brand name)
Paste the API Key
Type header:authorization:Bearer in the API Key Location field
Paste the JSON Schema exactly as shown in the table above
Click Save Settings

✅ Successful response from TalkSasa looks like: {"status":"success","message":"SMS queued successfully for 1 recipient(s). Delivery in progress.",...}

7. Example Configuration — BlessedTexts

BlessedTexts (sms.blessedtexts.com) expects the API key inside the JSON body rather than in the header.

Field	Value
SMS API URL	`https://sms.blessedtexts.com/api/sms/v1/sendsms`
Sender ID	Your registered BlessedTexts sender name
API Key	Paste your API key from the BlessedTexts dashboard
API Key Location	(leave blank — key goes in the JSON body via `$API_KEY`)
API Schema	`{"api_key":"$API_KEY","message":"$MESSAGE","phone":"$RECIPIENT_NUMBER","sender_id":"$SENDER_ID"}`

BlessedTexts — Step by Step

Log in to your BlessedTexts account and copy your API key
In ISPMan, enter the SMS API URL shown above
Enter your registered Sender ID
Paste the API Key
Leave the API Key Location field blank
Paste the JSON Schema (note that $API_KEY is inside the JSON)
Click Save Settings

8. How to Find the Right Settings for Any Provider

Step 1 — Find the API Documentation

Look for a link called “API Docs”, “Developer Docs”, “API Reference”, or “Integration Guide” in your provider’s dashboard or website.

Step 2 — Find the Send SMS Endpoint

Look for a section called “Send SMS”, “Send Message”, or “Outbound SMS”. It will show you an API Endpoint URL. This goes into the SMS API URL field. The method will almost always be POST.

Step 3 — Find the Authentication Method

Look at the Headers section of the API docs:

Authorization: Bearer {api_token} → use header:authorization:Bearer
X-API-KEY: {key} → use header:x-api-key
api_key in the body → leave API Key Location blank and use $API_KEY in your JSON Schema

Step 4 — Build Your JSON Schema

Find the Parameters or Request Body section. List every required field. Replace the dynamic values (phone number, message, sender) with the matching ISPMan placeholder.

Step 5 — Test

After saving your settings, send a test SMS from the ISPMan interface. Check the SMS logs to confirm the message shows as Queued or Delivered.

9. Troubleshooting

Symptom	What to Check
SMS not sending at all	Check that the API URL is correct and reachable. Verify your API Key is still valid in your provider’s dashboard.
401 Unauthorised error	The API Key is wrong or the API Key Location format is incorrect. For Bearer auth use exactly: `header:authorization:Bearer`
Message sends but wrong body	Double-check your JSON Schema. Make sure `$MESSAGE` and `$RECIPIENT_NUMBER` are present and spelled exactly (case-sensitive).
Customer gets no Sender ID	Ensure the Sender ID field matches what your SMS provider has registered for your account.
SMS logs show Queued only	This is normal — delivery confirmation depends on the provider. Wait a few minutes and check again.

10. Quick Checklist Before Saving Settings

SMS API URL starts with https:// and ends with the correct path
Sender ID matches what your provider has registered
API Key is correct and has not expired
API Key Location matches your provider’s auth method
JSON Schema contains $MESSAGE and $RECIPIENT_NUMBER (case-sensitive)
All four automatic SMS toggles are turned on
You have clicked Save Settings

11. Conclusion

Once these fields are configured correctly and saved, ISPMan will send customer SMS notifications automatically based on your enabled toggles.

If SMS still fails after this setup, recheck your provider API documentation, compare it with your JSON schema, and test with a known-good recipient number.