eSMS AfricaeSMS Africa
SMS PlatformTwo-Way SMS

Two-Way SMS

Your own keyword on an eSMS Africa shared short code. Customers text your keyword, you get a signed webhook, and you reply from the same code. Self-service in 8 countries, on request everywhere else.

Two-Way SMS lets people text your business and get answers back on the same number. eSMS Africa runs shared short codes in each country and gives you your own keyword on one of them. A customer texts your keyword, the message reaches your backend on a signed webhook, and you reply from the short code with one API call.

The short version

You get a keyword such as CLINIC on the short code 3450 in Nigeria. You tell your customers "Text CLINIC to 3450". Their messages arrive on your webhook, your replies go out from 3450, and once you have texted someone, their plain answers like 1, 2 or YES come back to you for the next 72 hours without the keyword.

Request a keyword at sms.esmsafrica.io/two-way. Nothing is charged until your request is approved, and you can build and test the whole flow in the Sandbox & phone simulator while you wait.

How it works

 Customer's phone            eSMS Africa                          Your backend
 ----------------            -----------                          ------------
       | 1. "CLINIC hi" to 3450   |                                     |
       | -----------------------> |                                     |
       |                          | 2. Match: STOP/START/HELP, then     |
       |                          |    keyword, then conversation       |
       |                          |                                     |
       |                          | 3. POST message.inbound (signed)    |
       |                          | ----------------------------------> |
       |                          |                                     | 4. Your logic
       |                          | 5. POST /v1/two-way/messages        |
       |                          | <---------------------------------- |
       | 6. Reply from 3450       |                                     |
       | <----------------------- |  (opens a 72h conversation window)  |
       | 7. "2"  (no keyword)     |                                     |
       | -----------------------> | 8. Matched by conversation -> you   |
       |                          | ----------------------------------> |
  1. A customer texts your keyword to the short code, for example CLINIC hi to 3450.
  2. eSMS works out who the message is for (see How inbound is matched).
  3. eSMS posts a signed message.inbound webhook to your backend. It tells you the keyword, the code, the sender, the text and the text without your keyword.
  4. Your backend decides what to do: store an answer, look something up, hand off to an agent.
  5. You reply with POST /v1/two-way/messages.
  6. The reply is delivered from the short code, and it opens a conversation window for that phone.
  7. The customer answers with just 2.
  8. Because you were the last keyword to text that phone from 3450, the 2 comes to you.

Shared short codes and keywords

eSMS Africa owns and operates the shared short codes. Many businesses share one code, and each business is identified by its keyword.

Who owns the codeeSMS Africa. You get a keyword on it - nothing to lease or maintain.
Your keywordOne word, 2 to 20 letters or digits, with at least one letter (for example CLINIC, VOTE24).
UniquenessOne keyword belongs to one business on a code. The same word can exist on another code.
CaseNot case sensitive. clinic, Clinic and CLINIC are the same keyword.
Reserved wordsSTOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, START, UNSTOP, SUBSCRIBE, RESUME, OPTIN, HELP and INFO can never be keywords. Numbers alone (1, 12) are reserved for menu replies.
What customers textCLINIC or CLINIC <message> to the code. clinic hi, Clinic: hi, CLINIC,hi and CLINIC-hi all match.

Every keyword comes with a copyable instruction such as Text CLINIC to 3450, shown on your keyword card in the app and returned by GET /v1/two-way/keywords. Check a keyword is free before you request it with GET /v1/two-way/keywords/check.

Need a dedicated short code?

A dedicated code (a whole number for your brand alone, no keyword needed) is arranged by our sales team: WhatsApp +254 11 449 4147 or email support@esmsafrica.io. Everything on this page works the same on a dedicated code, except that every message to the code is yours (matched_by: "dedicated").

Availability

You can request a keyword yourself (self-service, published prices) in Nigeria (NG), Ghana (GH), Madagascar (MG), Kenya (KE), Uganda (UG), Zambia (ZM), Ethiopia (ET) and Cote d'Ivoire (CI).

Every other African country is available on request: send a request from the app (or the API) and our team confirms availability, pricing and the documents the networks need before anything is charged. On-request countries show no prices - they are quoted per request. The availability field of GET /v1/two-way/pricing is always current.

A short code is national: it only reaches phone numbers in its own country. Request one keyword per country you serve.

How inbound is matched

Every message to a shared code is checked in this order. The first rule that applies wins.

#RuleExampleGoes tomatched_by
1Compliance words. The whole message is STOP, START or HELP (or a synonym), or <KEYWORD> STOP/START/HELP, or STOP <KEYWORD>.STOP, CLINIC STOP, helpSee Opt-out and HELPkeyword or affinity
2Keyword. The first word is a live keyword on this code.CLINIC 2, clinic: bookThat keyword's ownerkeyword
3Conversation affinity. No keyword, but a keyword on this code sent an SMS to this phone within the window (72 hours by default). The most recent sender wins.1, YES, TuesdayThe keyword that last texted the phoneaffinity
4Unmatched. None of the above.2 from a phone nobody texted recentlyNobody. The phone gets a free hint reply.-

Things to know:

  • A keyword always wins. If a customer texts PHARMA 1 while a conversation with CLINIC is open, the message goes to PHARMA.
  • Only your outbound messages open or extend the window. Each successful send to a phone from the code restarts the 72-hour timer for that phone. An inbound message on its own does not extend it, so reply to keep the conversation going.
  • The latest sender wins. If two keywords on the same code both texted a phone, plain replies go to whichever texted it last.
  • The window can differ per code. 72 hours is the default; the window that applies to a conversation is returned as affinity_expires_at on conversations.
  • Unmatched messages are never charged to anyone. The sender normally gets a free hint (at most once every 10 minutes per phone), for example "This is 3450, a shared short code. Start your message with the keyword of the service you want, e.g. KEYWORD HELLO. Reply STOP to opt out of all messages from 3450." The hint never names any business. Our team reviews unmatched messages and can pass one to the right keyword (it then arrives unbilled with matched_by: "admin").

Design menus so a customer can always restart with the keyword: end long flows with "Text CLINIC anytime to start again". If they come back after the window has closed, a bare 1 is unmatched, but CLINIC 1 always reaches you.

Opt-out: STOP and START

Opt-out is handled by the platform. You never need to parse STOP yourself, but you are told about it.

Customer textsEffectWebhook eventsConfirmation SMS (free)
CLINIC STOP (or STOP CLINIC)Opted out of your keyword only on this codemessage.inbound (action: "opted_out") and two_way.opt_out with scope: "service"You have been unsubscribed from CLINIC on 3450. Reply CLINIC START to resubscribe.
STOPOpted out of every keyword on this codeEvery keyword the phone has talked to gets message.inbound and two_way.opt_out with scope: "global"You will no longer receive messages from 3450. Reply START to resubscribe.
CLINIC STARTOpted back in to your keywordmessage.inbound (action: "opted_in") and two_way.opt_in, scope: "service"You are subscribed to CLINIC on 3450 again. Reply CLINIC STOP to opt out.
STARTOpted back in to every keyword on the codeEvery keyword the phone has talked to gets message.inbound and two_way.opt_in with scope: "global"You are subscribed to messages from 3450 again. Reply STOP to opt out.

STOP synonyms: STOP, STOPALL, STOP ALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, OPT OUT, OPT-OUT. START synonyms: START, UNSTOP, SUBSCRIBE, RESUME, OPTIN, OPT IN, OPT-IN. Matching ignores case and a trailing . or !.

While a phone is opted out, sending to it from your keyword is refused with 403 recipient_opted_out. When a phone opts out of your keyword it is also added to your account's opt-out list, which blocks every SMS from your account to that number until it opts back in. List who opted out with GET /v1/two-way/services/{id}/opt-outs. Opt-out messages are never billed.

HELP

Customer textsReply (free)
CLINIC HELPYour keyword's HELP text
HELP (or INFO) while a conversation with you is openYour keyword's HELP text
HELP with no open conversationThe code's generic help, which names no business

Set your HELP text (up to 480 characters) under Manage > HELP in the app or with PATCH /v1/two-way/services/{id} (help_text). Say who you are, what the service does and how to opt out. Without one, the default is "<Company>: text CLINIC to 3450. Reply CLINIC STOP to opt out." You still get a message.inbound webhook with action: "help".

Webhooks

Every message for your keyword is posted to your webhook as it arrives. Set the URL per keyword (webhook_url, in the request wizard, under Manage, or with PATCH), or set an account-wide MO URL under Settings > Webhooks. The keyword's URL wins.

message.inbound

{
  "event": "message.inbound",
  "id": "a3c5e8f0-6b1d-4c2e-9f7a-1d2e3f4a5b6c",
  "message_id": "a3c5e8f0-6b1d-4c2e-9f7a-1d2e3f4a5b6c",
  "service_id": 42,
  "keyword": "CLINIC",
  "code": "3450",
  "from": "+2348012345678",
  "to": "3450",
  "text": "CLINIC book a visit",
  "raw_text": "CLINIC book a visit",
  "body_without_keyword": "book a visit",
  "received_at": "2026-10-12T09:30:00+00:00",
  "conversation_id": 981,
  "matched_by": "keyword",
  "opt_out": false,
  "action": null,
  "segments": 1,
  "billed": true,
  "two_way": { "service_id": 42, "number": "3450", "keyword": "CLINIC", "type": "shared", "toll_free": false }
}
FieldWhat it means
keyword / codeYour keyword and the short code it lives on.
fromThe customer's number in international format. Reply to this.
textThe message. If you turned on strip keyword, keyword matches arrive without the keyword here.
raw_textAlways exactly what the customer sent.
body_without_keywordThe message with your keyword removed ("book a visit"). For an affinity match it is the whole message ("2"). Use this for menus.
conversation_idStable ID of this customer's thread with your keyword on this code. Key your session state on it.
matched_bykeyword, affinity (plain reply inside the window), dedicated or admin (passed to you by our team).
action / opt_outnull for a normal message; opted_out, opted_in or help for compliance words (opt_out is true for STOP).
billedtrue charged, false stored unbilled because your balance was too low, null not billable (STOP/START/HELP, passed on by our team).

two_way.opt_out and two_way.opt_in

{
  "event": "two_way.opt_out",
  "id": "evt_5f2a9c1b7d3e4a60",
  "message_id": "a3c5e8f0-6b1d-4c2e-9f7a-1d2e3f4a5b6c",
  "service_id": 42,
  "keyword": "CLINIC",
  "code": "3450",
  "phone": "+2348012345678",
  "from": "+2348012345678",
  "scope": "service",
  "occurred_at": "2026-10-12T09:31:00+00:00",
  "conversation_id": 981,
  "two_way": { "service_id": 42, "number": "3450", "keyword": "CLINIC", "type": "shared", "toll_free": false }
}

scope is service when they texted CLINIC STOP, or global when they texted a bare STOP to the code.

Verify the signature

Every webhook has an X-Webhook-Signature header: sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your account signing secret (shown and rotated under Settings > Webhooks). Compute it over the bytes you received, before parsing JSON, and compare in constant time.

import crypto from "node:crypto";

export function verifyEsms(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header || "");
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Full handlers that verify and reply are on the webhook reference.

Retries

Return any 2xx status within 15 seconds and do slow work in the background. If your endpoint fails or times out, the same payload is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours (six attempts in total). Retries survive restarts on our side. De-duplicate on id. Every attempt, with its HTTP status and next retry time, is listed under Manage > Webhook log and by GET /v1/two-way/services/{id}/webhook-deliveries.

No webhook yet? Every message is also stored in your inbox (Manage > Inbox) and readable with GET /v1/two-way/messages. You can also forward each message to an email address (forward_email).

Sending from your keyword

curl -X POST "https://sms.esmsafrica.io/v1/two-way/messages" \
  -H "Authorization: Bearer $ESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "CLINIC", "to": "+2348012345678", "text": "Reply 1 to book, 2 to talk to a nurse"}'
  • Identify the keyword with keyword (add code only if you hold the same keyword on two codes) or with service_id.
  • The message goes out from the short code and opens or extends the 72-hour conversation window, so the customer's plain replies come back to you.
  • You can start a conversation (the customer has not texted you yet) or continue one. Only send to people who agreed to hear from you.
  • The recipient must be in the short code's country, and must not have opted out.
  • Up to 1,600 characters (10 segments). Each segment is billed at your outbound price.
  • The keyword must be active or past_due. Use a test key to send in the sandbox before you go live.

The older POST /v1/two-way/services/{id}/reply still works and behaves the same. Full details are on the Messages reference.

You can also turn on an auto-reply per keyword (up to 480 characters). It is sent from the code to each new inbound message, at most once per phone per minute, never in answer to STOP, START or HELP, and is charged like any other message you send.

Billing

Two-Way SMS is priced per country in USD and paid from your prepaid eSMS wallet (converted to your wallet currency at the time of each charge).

ItemWhenPrice in the self-service countries
Setup feeOnce, when your keyword is approvedUSD 100
Monthly keyword feeOn approval, then every 30 daysUSD 50 per month, VAT inclusive
Inbound SMSEach message delivered to your keyword, per segmentThe country's Basic SMS price, unless a custom two-way price is set
Outbound SMSEach message you send from the code, per segmentThe country's Basic SMS price, unless a custom two-way price is set or your account has its own price for that country
STOP, START, HELP-Free, and so are the platform's confirmations, HELP replies and unmatched hints

Live per-country figures are on esmsafrica.io/two-way-sms and from the public GET /v1/two-way/pricing endpoint. The prices on your keyword (fees on the service object) are the ones you are charged. On a toll-free code (where offered) the end user pays nothing to text you and you pay the country's toll-free inbound price.

Rules

  • Nothing is charged when you request. Setup and the first month are charged on approval. A rejected request costs nothing.
  • Approved but your balance is short? The keyword shows Awaiting payment with the amount due. Top up and it activates automatically within minutes.
  • Renewals are charged every 30 days. You get a reminder about 3 days before if your balance looks too low. If the fee cannot be collected the keyword becomes past_due and we retry daily.
  • Suspension. After 7 days past due the keyword is suspended: incoming messages are still stored (and not billed) but not sent to your webhook, and you cannot send. Top up and it resumes automatically with a new 30-day period.
  • Low balance on inbound. A customer's message is never dropped. If your balance cannot cover an inbound message it is stored and still forwarded with billed: false, and you are notified.
  • Cancelling stops future monthly fees and frees the keyword. Fees already charged are not refunded.

See your fee history with GET /v1/two-way/services/{id}/billing.

Request a keyword

  1. Sign in at sms.esmsafrica.io and open Two-Way SMS.
  2. Click Request a keyword.
  3. Country - pick where your customers are. Countries marked On request are arranged by our team.
  4. Short code and keyword - pick a shared code (or let us assign one) and type your keyword. Availability is checked as you type, and you see exactly what customers will text, for example Text CLINIC to 3450.
  5. Billing model - standard rated, or toll free where offered.
  6. Business - company name, your use case with sample messages, an optional webhook URL, and KYC documents (PDF, PNG, JPG or WEBP up to 5 MB each, or links). Typical documents: certificate of incorporation or business registration, tax certificate, ID of the authorised representative, and a signed authorisation letter on company letterhead. Final requirements depend on the networks. In on-request countries the documents are optional at first - we tell you what is needed.
  7. Review and submit. We review the request with the networks. Nothing is charged until it is approved.

Once approved, your keyword card shows the instruction to give customers and a Manage panel with the inbox, conversations, opt-outs, webhook log, HELP text, auto-reply, usage and billing. The same request can be made over the API with POST /v1/two-way/services.

Worked example

See the healthcare navigation example: a numbered menu flow on a shared code, with the webhook each step produces and a complete handler.

Going-live checklist

  • Flow built and tested in the sandbox, including STOP, HELP and an expired conversation
  • Keyword approved (status: "active") and the setup fee and first month paid
  • Webhook URL set, and your handler verifies X-Webhook-Signature and returns 2xx fast
  • Handler is idempotent on id and ignores payloads with "sandbox": true
  • Session state keyed on conversation_id, with a restart path ("Text CLINIC to start again")
  • HELP text set, and opt-out instructions in your first message
  • Sending uses a live key (esms_live_) with the two_way or send scope
  • Wallet topped up for the monthly fee and expected traffic, low-balance alerts on

FAQ

Do my customers need to type the keyword every time? Only to start. After you text them from the code, plain replies reach you for 72 hours from your latest message. After that, they start again with the keyword.

What if two businesses on the same code text the same customer? Plain replies go to whichever texted the customer last. A message that starts with a keyword always goes to that keyword.

Can I message customers who have never texted me? Yes, POST /v1/two-way/messages can start a conversation, as long as the number is in the code's country, has not opted out, and you have their consent.

Do customers pay to text the code? On a standard-rated code they pay their normal SMS rate to send, and nothing to receive. On a toll-free code (where offered) texting you is free for them.

What happens when my balance runs out? Inbound messages are still stored and forwarded (billed: false) and you are notified. Sends fail with 402 insufficient_balance. A monthly fee that cannot be collected makes the keyword past_due, and it is suspended after 7 days until you top up.

Can I change my keyword? Request the new keyword, then cancel the old one when you have moved your customers over.

Support

WhatsApp +254 11 449 4147 or email support@esmsafrica.io.

On this page