Use Cases
SMS notifications playbook
Turn payment, payout and invoice events into SMS messages without duplicates, and watch delivery and balance.
The playbook in one page
Customers want to know what happened: payment received, order shipped, payout sent, invoice due. Moolre sends SMS for you. This playbook turns the events your system already knows about into messages you can trust, without sending duplicates or blowing the balance.
| Event | Trigger | Message |
|---|---|---|
| Payment received | payment.succeeded webhook | Thank you, we received GHS 120.00 for order 1001 |
| Payment failed | payment.failed webhook | Your payment did not go through: wrong PIN. Try again |
| Payout sent | payout.succeeded webhook | GHS 85.00 was sent to your MoMo number |
| Invoice due soon | Your scheduler + List invoices | Fees of GHS 450.00 are due on 31 Dec: pay at the link |
| One-time passcodes of your own app | Your login flow | Your code is 123456 |
Step by step
- Get an approved Sender ID (Create Sender ID, then Sender ID Status) and the SMS X-API-VASKEY. Check the balance with SMS Account Status.
- Decide the messages and keep each under 160 GSM characters where you can (the SMS counter shows how many segments a text uses). Avoid characters outside the GSM set unless you need them.
- Subscribe to the events. In your webhook handler, after the signature check and the event_id dedupe, create a message record instead of sending straight away: ref = the event_id (for example sms-evt_0123…), recipient, text.
- A sender job reads unsent records and calls Send SMS with their refs. Because the ref is derived from the event_id, a retried webhook cannot create a second message.
- Mark records sent when the call is accepted. Later ask SMS Status with the refs to learn delivery, and mark delivered or failed.
- Retry only failed messages, with a new ref ("-r1"), and cap retries.
- Watch the balance: alert when it is below what a day's traffic needs, and pause marketing sends before transactional ones.
curl https://api.moolre.com/open/sms/send \ -H "Content-Type: application/json" \ -H "X-API-VASKEY: $MOOLRE_SMS_VASKEY" \ -d '{ "type": 1, "senderid": "Acme", "messages": [ { "recipient": "0240000001", "message": "Thank you. We received GHS 120.00 for order 1001.", "ref": "sms-evt_0123456789abcdef01234567" } ] }'Edge cases
| Situation | What to do |
|---|---|
| The webhook is delivered twice | The message ref comes from event_id, so you send one message |
| The customer has no phone number on file | Skip SMS and use your in-app or email receipt; do not guess numbers |
| The Sender ID is not approved | The send returns ASMS07. Fix the approval before launch |
| The balance runs out | Sends fail. Alert early and top up; queue the messages instead of dropping them |
| A message is long | It uses several segments and costs more. Shorten it |
| The recipient opted out of marketing | Do not send marketing; transactional messages about their own payment are fine |
Checklist
- Messages are queued from verified, deduped events, never sent inline from a webhook.
- Every message ref is unique and derived from the event so a retry cannot duplicate it.
- You track delivery with SMS Status and retry only failures.
- The Sender ID is approved and the balance is monitored.
- No secrets or unnecessary personal data are in a message.