Two-Way SMS API
Every Two-Way SMS endpoint - keywords, sending from your short code, inbound messages, conversations, webhooks and the sandbox - with authentication, pagination and errors.
The Two-Way SMS API manages your keywords on eSMS Africa shared short codes, sends messages FROM your keyword, reads inbound messages and conversations, and drives the sandbox. Inbound messages and opt-outs are pushed to you as signed webhooks. For how matching, opt-out and billing work, read the Two-Way SMS guide first.
Base URL
https://sms.esmsafrica.io/v1/two-wayEvery path is also served under https://sms.esmsafrica.io/api/two-way/.... The two
prefixes are identical; these docs use /v1.
Authentication
Send an API key (or use a signed-in dashboard session):
Authorization: Bearer esms_live_your_api_key| Endpoints | Scope needed (any one) |
|---|---|
Reads: GET /keywords, /keywords/check, /countries, /messages, /conversations, /services and everything under /services/{id}/..., GET /sandbox/..., and POST /conversations/{phone}/read | two_way or query |
Sending: POST /messages, POST /services/{id}/reply | two_way or send |
Changes: POST /services, PATCH /services/{id}, POST /services/{id}/cancel, POST /kyc-documents, POST /services/{id}/test-webhook, and the sandbox writes (phones, inbound, send, demo, clock, settings, reset, bins) | two_way |
GET /pricing | None - public |
New keys get send, query and webhooks by default, which is enough to read and to
send from your keyword. To request keywords or drive the sandbox over the API, create the
key with "scopes": "send,query,webhooks,two_way" (see
API keys). A missing scope returns 403 insufficient_scope.
Sending from a suspended account returns 403 account_suspended.
Live and sandbox
| Key | POST /messages and /reply | Everything else |
|---|---|---|
esms_live_... | Sends a real SMS and charges your wallet. Add "environment": "sandbox" to send to the sandbox instead. | Your live data |
esms_test_... | Always goes to the sandbox: delivered to a simulated phone, never sent, never charged. Works for pending keywords. | Same endpoints, same data |
Endpoints
Keywords and services
| Method | Path | Description |
|---|---|---|
GET | /pricing | Pricing by country (public) |
GET | /countries | Countries, KYC notes and shared codes |
GET | /keywords | List your keywords with the "Text X to Y" instruction |
GET | /keywords/check | Check a keyword is free |
POST | /kyc-documents | Upload a KYC document |
GET | /kyc-documents/{id} | Download one of your KYC documents |
POST | /services | Request a keyword |
GET | /services | List your services |
GET | /services/{id} | Get a service |
PATCH | /services/{id} | Update webhook, auto-reply, HELP text, keyword stripping, email forwarding |
POST | /services/{id}/cancel | Cancel a keyword |
GET | /services/{id}/opt-outs | Phones that opted out |
GET | /services/{id}/stats | Usage stats |
GET | /services/{id}/billing | Billing history |
GET | /services/{id}/export.csv | Export messages as CSV |
Messages
| Method | Path | Description |
|---|---|---|
POST | /messages | Send FROM your keyword's short code |
GET | /messages | List inbound / outbound messages (cursor paginated) |
POST | /services/{id}/reply | Reply from the short code (legacy, still supported) |
GET | /services/{id}/messages | Message history for one service (legacy) |
Conversations
| Method | Path | Description |
|---|---|---|
GET | /conversations | List conversations for a keyword |
GET | /conversations/{phone} | Get one conversation |
POST | /conversations/{phone}/read | Mark a conversation read |
GET | /services/{id}/conversations | Service-scoped aliases |
Webhooks
| Event / endpoint | Description |
|---|---|
message.inbound | An inbound message for your keyword |
two_way.opt_out / two_way.opt_in | A phone opted out or back in |
POST /services/{id}/test-webhook | Send a signed test event |
GET /services/{id}/webhook-deliveries | Webhook delivery log |
Sandbox
| Method | Path | Description |
|---|---|---|
GET | /sandbox | Sandbox context |
GET | /sandbox/services | Keywords you can test |
POST / PATCH / DELETE | /sandbox/phones | Simulated phones |
POST | /sandbox/inbound | Simulate a phone texting the code |
POST | /sandbox/send | Send to a simulated phone |
POST | /sandbox/demo | Send a numbered demo menu |
GET | /sandbox/messages | Sandbox threads with debug records |
POST | /sandbox/clock | Fast-forward the clock |
PUT | /sandbox/settings | Sandbox webhook URL |
POST | /sandbox/reset | Reset the sandbox |
POST / GET / DELETE | /sandbox/bins | Request bins |
Pagination
List endpoints that can grow without bound use cursor pagination, newest first:
{ "data": [ ... ], "has_more": true, "next_cursor": "18342" }Pass next_cursor back as cursor to get the next page; stop when has_more is false.
limit is 1 to 200 (default 50). A single conversation pages backwards with before /
next_before instead, because it is returned oldest first.
let cursor = null;
do {
const params = new URLSearchParams({ keyword: "CLINIC", limit: "200", ...(cursor && { cursor }) });
const res = await fetch(`https://sms.esmsafrica.io/v1/two-way/messages?${params}`, {
headers: { Authorization: `Bearer ${process.env.ESMS_API_KEY}` },
});
const page = await res.json();
page.data.forEach((m) => console.log(m.created_at, m.from, m.text));
cursor = page.has_more ? page.next_cursor : null;
} while (cursor);Identifying a keyword
Endpoints that act on one keyword accept either service_id or keyword. If you hold
the same keyword on two short codes, add code (or use service_id); otherwise you get
409 ambiguous_keyword.
Errors
Errors use the standard envelope. Branch on error.code; extra fields are in
error.details.
{
"error": {
"code": "recipient_opted_out",
"message": "+2348012345678 has opted out of your messages and cannot be contacted.",
"request_id": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
"details": { "phone": "+2348012345678" }
}
}| HTTP | code | When |
|---|---|---|
400 | invalid_phone | to is not a valid number. |
400 | invalid_recipient_country | to is not in the short code's country - a code only reaches its own country. |
400 | empty_text | text is empty. |
400 | price_unset | No price is configured to bill the send. Contact support. |
401 | unauthorized | Missing or invalid key or session. |
402 | insufficient_balance | Your wallet cannot cover the send (details.required, details.available, details.currency). |
403 | insufficient_scope | The key lacks the scope for this endpoint. |
403 | account_suspended | The account is suspended and cannot send. |
403 | recipient_opted_out | The recipient opted out of your keyword (or of the whole code). |
403 | no_two_way_service | Sandbox: you need a two-way keyword first (pending is fine). |
404 | not_found | Service, keyword, conversation, document or bin not found (or not yours). |
409 | service_not_active | Sending needs an active or past_due keyword. |
409 | number_unavailable | The short code is paused for sending. |
409 | ambiguous_keyword | You hold the keyword on more than one code - pass code or service_id. |
409 | keyword_unavailable | The keyword is taken or already requested on that country's shared codes. |
409 | duplicate_request | You already have the same pending request. |
409 | invalid_state | The service is already cancelled or rejected. |
409 | service_not_available | Sandbox: the keyword is cancelled or rejected. |
409 | too_many_phones / duplicate_phone / too_many_bins | Sandbox limits. |
410 | expired | The request bin has expired. |
413 | message_too_long | More than 10 segments (1,600 characters). |
413 | file_too_large | KYC upload over 5 MB. |
415 | unsupported_type | KYC uploads must be PDF, PNG, JPG or WEBP. |
422 | validation_error | The request failed validation (details.errors lists fields). |
422 | country_unavailable / toll_free_unavailable | Two-way (or toll free) is not offered in that country. |
422 | kyc_required / invalid_document | No KYC document attached, or an unknown upload ID. |
422 | invalid_number | number_id is not an active shared code in that country. |
422 | invalid_url / url_not_public / invalid_email | A webhook URL or forwarding email is invalid or not public. |
422 | auto_reply_text_required | Enabling auto-reply without text. |
429 | rate_limited | Too many requests - back off and retry. |
503 | route_unavailable | Sending from this code is temporarily unavailable. |
Related
Inbound & two-way
GET /api/conversations - Read inbound (MO) replies and two-way threads.
Keywords & services
Pricing, countries, keyword availability, requesting a keyword with KYC, the service object, updating webhook / auto-reply / HELP text, cancelling, opt-outs, usage stats, billing history and CSV export.