Personalized SMS API: Send Each Customer Their Own Alert

Personalized SMS API: Send Each Customer Their Own Alert

Personalized SMS API concept: one request listing several customers sends each phone its own premium alert from a fictional insurer, with each customer's name filled in

To send every customer their own balance, charge or premium alert by SMS, you need a personalized SMS API call, and in the Arkesel SMS API that is the template send operation. You write the alert once, attach each customer’s own values to their number, and one request delivers a different message to every customer on it.

If you are new to the API, start with sending SMS through the Arkesel API for authentication and a first working request, then come back here to build the alert run itself.

Why does a bulk send give everyone the same message?

The two bulk send routes are built for one text going to many people. According to Arkesel’s published API specification, the original send-sms operation sends one message to one or several phone numbers, with several numbers separated by commas in the ‘to’ parameter. The v2 send endpoint takes a recipients list of mobile numbers for one message.

On either route, giving each customer different text means one request per customer. At month-end that becomes thousands of separate requests to send, log and retry. The template send endpoint removes that loop:

RouteWhat each recipient getsPer-recipient valuesRecipients per request
GET send-sms (V1)The same messageNoOne or several numbers, comma-separated
POST /api/v2/sms/sendThe same messageNoUp to 10,000 at the time of writing
POST /api/v2/sms/template/sendTheir own messageYesUp to 15,000 at the time of writing

At the time of writing, a single template send request accepts up to 15,000 recipients and a single v2 send request accepts up to 10,000 recipients. Confirm the current limits with Arkesel before you size a production job.

Comparison of bulk SMS send routes with the personalized SMS API template send: bulk routes give every number the same message, while template send gives each recipient their own message from one request

How does the personalized SMS API template send work?

The template send endpoint sends variable SMS. You write the message once with variables in it, and each recipient in the request carries its own values for those variables. The specification adds one rule that shapes how you prepare your data: every recipient must use the same set of variable keys.

A variable is a named slot in the message, such as the customer’s first name, the amount, the balance after the transaction or the date. Each recipient entry pairs a phone number with a value for every slot. A debit alert run sends the same sentence structure to every customer in the request, with each customer’s own amount and balance filled in. The exact format for marking a variable in the message, and for listing each recipient’s values, is in the Arkesel API documentation, along with code samples.

Two fields need attention before you write any alert copy:

  • Sender ID. It can be at most 11 characters including spaces, and anything longer makes messages fail. Choose a name your customers already recognise as your institution.
  • Recipient numbers. The SMS send API accepts recipient numbers with a leading + as well as the 233 form (233 is Ghana’s country code). Normalise your export to one format so a customer never appears twice under two spellings of the same number.

If several of your systems already send SMS, read our guide to running more than one API key on an account before you connect the alert job.

What should a bank or insurance SMS alert contain?

A useful alert tells the customer who sent it, what happened to which account, and what to do if they did not expect it. The points below are good practice rather than any regulator’s rule, and your compliance team may add requirements of its own:

  • Name the institution, both in the sender ID and at the start of the message.
  • Mask the account or policy number so only the last four digits show.
  • Never include a PIN, a password or a full card number.
  • Describe fees in plain words, such as “account charge”, rather than internal fee codes.
  • Give the customer a way to reach you, such as a helpline number.

These sample alerts use a fictional institution and dummy values. Each count is the number of characters in the message as written.

AlertSample (dummy values)Characters
Debit with balanceDemoBank: GHS 250.00 debited from a/c ending 4821 on 05-Nov-26. Balance: GHS 1,230.40. Not you? Call 0800 000 000.114
Account chargeDemoBank: account charge of GHS 12.50 applied to a/c ending 4821 on 30-Nov-26. Balance: GHS 1,217.90. Queries: 0800 000 000.124
Insurance premium debitDemoInsure: Dear Ama, your monthly premium of GHS 85.00 for policy ending 7730 was debited on 01-Dec-26. Thank you. Queries: 0800 000 000.138
Loan repayment reminderDemoFin: Hi Chidi, your loan repayment of NGN 45,000.00 is due on 15-Dec-26. Pay in the app or call 0800 000 000.113

All four fit in a single 160-character page as written. Real names and amounts change those counts, so count again once your own data is in.

How do you prepare customer data so no alert goes out broken?

Build the export so the request only ever receives complete, clean rows:

  • One row per customer, one column per variable. Include the phone number and every value the alert uses: first name, masked account number, amount, balance and date.
  • Mask in the export. Mask account numbers in the export query itself, keeping only the last four digits, so full numbers never reach the SMS layer. The account numbers stored in your core-banking or policy system stay as they are.
  • Check every value before you send. Confirm that every recipient carries every variable, and that each one holds a real value rather than a blank. A missing balance or an empty name in a financial alert reads as an error, or as a scam. Move incomplete rows to an exceptions file for someone to correct instead of sending them.
  • Format consistently. Use two decimal places, a thousands separator, one date format and the same currency code on every row.
  • Test with a small real send. Send the first version of each alert to a few staff numbers and read it on an actual phone before any customer receives it.

Why do some customers’ alerts cost two segments?

Variable values change the length of each message. The API documentation counts one SMS page as 160 characters and says a 200-character message is 2 pages. SMS is billed per segment, so a customer whose alert runs past 160 characters costs you at least two messages instead of one. You can check current rates on the Arkesel pricing page.

Here is the same premium alert, with a slightly longer closing line, filled in for two customers:

  • “DemoInsure: Dear Ama, your monthly premium of GHS 85.00 for policy ending 7730 was debited on 01-Dec-26. Thank you for staying covered. Queries: 0800 000 000.” This is 158 characters, so it fits on one page.
  • “DemoInsure: Dear Nana Akosua Serwaa, your monthly premium of GHS 1,285.00 for policy ending 7730 was debited on 01-Dec-26. Thank you for staying covered. Queries: 0800 000 000.” This is 176 characters, so it takes two pages.

Both messages go out in the same request, yet the second costs twice as much. Before you go live, fill each alert with the longest name in your customer base and the largest amount you expect, then count. If that version crosses 160 characters, shorten the fixed wording or cap the name field at the first name. In the example above, cutting the closing line back to “Thank you.” brings the longer message to 156 characters.

Two personalised premium alerts from the same request: the 158-character alert fits one SMS page, the 176-character alert needs two, and writing GH¢ instead of GHS would push the shorter alert to three segments

Should you write GH¢, ₵ or GHS in an SMS?

Write GHS. As Arkesel’s guide to how SMS length and Unicode work explains, the cedi sign (₵) and the cent sign (¢) in GH¢ are not in the GSM-7 tables, the standard SMS character set. A message containing either is encoded as UCS-2 and its limit drops from 160 characters to 70. Writing the amount as GHS keeps every character in GSM-7.

One symbol changes the whole message, not just the amount. Once a Unicode message is split, each segment holds 67 characters, so the 158-character premium alert above, written with GH¢, would need three segments instead of one. Across a month-end run, that difference applies to every customer whose alert carries the symbol.

For naira amounts, write NGN. If you would rather use a currency symbol, send a test message and check its character count before the symbol goes into a live template.

When do alerts need separate requests?

In a template send, the callback URL and the scheduled date apply to every message in that request. Group your alerts before you build the requests, and give each group its own:

  • Send time. Premium reminders scheduled for the morning of the due date cannot share a request with alerts you send immediately.
  • Callback endpoint. If your banking and insurance systems each receive delivery results at their own endpoint, their alerts go in separate requests.
  • Set of variables. Because every recipient in a request uses the same variable keys, a debit alert and a loan reminder built from different fields belong in different requests.

Within each group, keep every request inside the per-request limit. For a month-end run in the hundreds of thousands, our guide to sending month-end SMS at volume covers batch sizing, pacing and safe retries.

Planning a large month-end alert run? Talk to Arkesel about your alert volumes before you size the job.

How do you send transactional alerts to Nigerian numbers?

Nigerian alerts need two settings, and they work together:

  1. Set use_case to transactional. The use_case field marks a message as promotional or transactional, and it applies only to Nigerian traffic. It also keeps a sender ID registered for promotional messages from sending transactional ones, and the reverse.
  2. Use a sender ID whitelisted for the DND route. In Nigeria, transactional messages are delivered through the DND route once the sender ID is whitelisted. Whitelisting takes about 4 to 6 weeks and applies to Nigerian-registered businesses. If your business is not registered in Nigeria, talk to Arkesel about how your Nigerian alerts will be routed before you build.

Start the whitelisting before you start the build, so the sender ID is ready when your integration is. Our article on Nigeria’s DND route and sender IDs explains the route in more detail, and promotional vs transactional SMS covers how the two message types differ.

How do you match delivery reports back to each customer?

The send response returns a notification id for each recipient, so each message can be matched to its delivery notification. Store that id against the customer and the alert in your own system at the moment you send. It is how you answer a customer who asks, weeks later, whether their alert arrived.

Delivery notifications report statuses such as DELIVERED, SUBMITTED, PROHIBITED, QUEUED, NOT_DELIVERED and EXPIRED. Decide in advance which statuses your system records as final and which it keeps waiting on.

Plan your reconciliation around how the results arrive:

  • Webhooks arrive in batches. Delivery-status webhooks to your endpoint are dispatched in batches every ten minutes, so a result can take up to about ten minutes to reach you. Do not build anything that needs an instant answer on them.
  • The per-recipient report updates sooner. The platform normally updates a message’s delivery status within about one minute of delivery, in the per-recipient report.
  • No separate failure alert is sent. After each run, check every message whose status has not reached DELIVERED, using your delivery webhook data or the per-recipient report, and decide what happens to each one.
  • Credit should not run out halfway. A low balance alert notifies you by email or webhook when credit falls below a threshold you set, which gives you time to top up before a month-end run stalls.

How SMS delivery results reach you after a personalized SMS API send: an id for each recipient at send, report status within about one minute of delivery, webhooks in batches every ten minutes, and your own check of every message not yet DELIVERED

Our guide to tracking SMS delivery reports covers reading the reports in more depth.

Pre-send checklist

  1. The sender ID is 11 characters or fewer and names your institution.
  2. Every recipient carries every variable, and each holds a real value.
  3. Account numbers are masked, and no PIN, password or full card number appears anywhere in the data.
  4. Amounts are written as GHS or NGN, with no ₵, GH¢ or untested symbol.
  5. The longest realistic name and the largest amount still fit in 160 characters, or you have accepted the cost of a second segment.
  6. Each request has one send time, one callback URL and one set of variables.
  7. Nigerian alerts set use_case to transactional and use a sender ID whitelisted for the DND route.
  8. Your system stores the id returned for each recipient.
  9. You have decided how your system handles every status that is not DELIVERED, including PROHIBITED.
  10. A low balance alert is set on the account.
  11. A small real send to your own staff numbers has been read on real phones.

Can you send personalised alerts without a developer?

Yes, from the dashboard. In ordinary dashboard bulk campaigns, per-recipient merge fields fill from contact-group fields or from the columns of an uploaded CSV or Excel file, and you pick the fields from those the platform presents. That suits a monthly batch exported from your system, such as premium reminders. For an alert that should go out the moment a transaction happens, connect your system through the API instead. Our guide to personalising bulk SMS from the dashboard walks through the dashboard route step by step.

Frequently asked questions

Is there an official SDK for the Arkesel SMS API?

No. The SMS API ships copy-paste code samples in cURL, Python, Node.js and PHP, with no official SDK client libraries. The samples are in the Arkesel API documentation.

Are transaction alerts the same as OTP messages?

No. An alert tells a customer that something has already happened on their account, while a one-time password confirms who they are before something happens. Login and payment codes raise their own security questions, covered in our guide to OTP for fintech and banking.

Who can help while we integrate?

Arkesel support runs by email and live chat from 06:00 to 22:00 UTC.

Start with a small real send

Read the template send reference in the Arkesel API documentation, then create an Arkesel account and send your first alerts to a handful of staff numbers. Once each alert reads correctly on a phone and its length is checked against your longest values, you are ready to point the SMS API at your customer export.

Scroll to Top