How to Connect Your ERP or Hospital System (HMIS) to an SMS API in Kenya

Your ERP already knows when an invoice is overdue, a lab result is ready or a delivery has left the warehouse. Your HMIS already knows tomorrow's appointments. The missing piece is telling the customer or patient, automatically, on the phone they carry everywhere.

This guide explains how an SMS API integration works and how to plan one, for operations managers, hospital administrators and IT leads in Kenya. It is vendor-neutral, with notes on where chat.or.ke fits.

What is an SMS API integration?

An SMS API integration is a connection that lets your own software send SMS automatically by calling the SMS provider's interface over the internet. Your system sends the phone number and message; the provider delivers it through the mobile networks and reports back whether it arrived.

APIs are usually REST APIs: your system makes an HTTPS request with an API key, and the provider replies with a message ID. Later, the provider sends a delivery report, often to a web address on your side known as a callback URL or webhook.

Before you start

Prepare the following:

• A list of message events, with sample wording for each.
• A registered sender ID for your organisation, or the paperwork to apply for one.
• An SMS provider that offers an API or another integration route, plus its documentation.
• Someone who can change your system: your in-house developer, your ERP or HMIS vendor, or an integrator.
• Agreement from your data protection lead on what information may go into SMS.
• A test environment or test records, so you never practise on real patients or customers.

Step 1: Choose the events that should send an SMS

List the moments when a message helps the customer or saves your staff a phone call. Keep the first phase to three to five events.

Typical examples:

A Kisumu hospital might start with appointment reminders alone, measure missed appointments for a month, then add results notifications.

Step 2: Register a transactional sender ID

Use a sender ID in your organisation's name, registered for transactional messages. Reminders, receipts and notices sent to your own patients or customers are transactional, and Safaricom keeps transactional and promotional traffic on separate sender IDs.

Registration takes time, so apply early. chat.or.ke registers sender IDs with Safaricom, Airtel and Telkom for a one-off KES 7,500; the sender ID page explains the documents needed, and transactional vs promotional SMS explains the difference.

Step 3: Decide how your system will connect

Choose between a direct API integration and a file-based integration. Both work; the right one depends on how quickly you need messages to go out and how easily your system can be changed.

Many organisations start with files and move to an API once the messages are proven. Kenyan schools, for example, often export fee balances from their fees system as a CSV and send personalised reminders using variables, as described on bulk SMS for schools. In chat.or.ke's bulk SMS portal you can import a CSV, fill in names and balances with variables, target contacts by tag and export delivery reports. If you need a direct system-to-system connection, contact the team to discuss what fits your system.

Step 4: Get API credentials and read the documentation

If you choose the API route, request credentials from your provider, usually an API key or a key and secret. Treat them like a password.

Check the documentation for:

• The endpoint URL for sending a message.
• How to authenticate, usually a header containing the API key.
• Required fields, typically the recipient number, the message text and your sender ID.
• Limits on how many requests you may send per second.
• How delivery reports are delivered: pushed to your callback URL, or fetched by your system.

Store keys in your system's secure configuration, never in code shared by email or in a spreadsheet.

Step 5: Map your data and clean phone numbers

Map each field in your system to the message. Then make sure every phone number is in one consistent format before it is sent.

Kenyan numbers are stored in many ways: 0712..., 712..., 254712... and +254712.... Convert them to the international format your provider expects, and reject numbers that are too short or too long. Watch message length too: one SMS holds 160 standard characters, and longer messages are split into parts of 153 characters, each billed separately. On chat.or.ke each part costs KES 0.55.

Step 6: Build the trigger and send a test

Add the code or vendor feature that sends a request when the event happens, and test it against a small group of staff phones first.

Test the awkward cases, not just the happy path:

1. A patient with no phone number.
2. A number in an unusual format.
3. A name with an apostrophe or a non-English character.
4. The same appointment edited twice: does it send two reminders?
5. The SMS provider being unreachable: does your system retry, and does it retry only once?

Step 7: Store delivery reports and handle failures

Save the provider's message ID against the record that triggered it, then update the status when the delivery report arrives. That lets staff see, inside your own system, whether the patient or customer actually got the message.

A delivered status means the SMS reached the phone. Failed numbers are often switched off, out of service or wrong. Flag repeat failures for staff to correct, rather than retrying forever.

If your system also receives payment confirmations from M-Pesa through Safaricom Daraja, the pattern will feel familiar: Daraja also sends results to a callback URL you provide.

Step 8: Protect personal data and respect opt-outs

Send the minimum information needed, keep sensitive details out of SMS and honour opt-outs. Under the Data Protection Act, 2019, health data is sensitive personal data, and SMS can be read by anyone holding the phone.

• Say "Your results are ready" rather than naming a test or diagnosis.
• Confirm that patients agreed to receive SMS when they registered.
• Do not reuse a transactional sender ID for promotions.
• Keep an audit trail of what was sent and why.

The Office of the Data Protection Commissioner publishes guidance, and opt-in and opt-out rules in Kenya covers consent in practice.