eSMS AfricaeSMS Africa
API ReferenceSMS APITwo-Way SMS

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-way

Every 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
EndpointsScope needed (any one)
Reads: GET /keywords, /keywords/check, /countries, /messages, /conversations, /services and everything under /services/{id}/..., GET /sandbox/..., and POST /conversations/{phone}/readtwo_way or query
Sending: POST /messages, POST /services/{id}/replytwo_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 /pricingNone - 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

KeyPOST /messages and /replyEverything 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

MethodPathDescription
GET/pricingPricing by country (public)
GET/countriesCountries, KYC notes and shared codes
GET/keywordsList your keywords with the "Text X to Y" instruction
GET/keywords/checkCheck a keyword is free
POST/kyc-documentsUpload a KYC document
GET/kyc-documents/{id}Download one of your KYC documents
POST/servicesRequest a keyword
GET/servicesList your services
GET/services/{id}Get a service
PATCH/services/{id}Update webhook, auto-reply, HELP text, keyword stripping, email forwarding
POST/services/{id}/cancelCancel a keyword
GET/services/{id}/opt-outsPhones that opted out
GET/services/{id}/statsUsage stats
GET/services/{id}/billingBilling history
GET/services/{id}/export.csvExport messages as CSV

Messages

MethodPathDescription
POST/messagesSend FROM your keyword's short code
GET/messagesList inbound / outbound messages (cursor paginated)
POST/services/{id}/replyReply from the short code (legacy, still supported)
GET/services/{id}/messagesMessage history for one service (legacy)

Conversations

MethodPathDescription
GET/conversationsList conversations for a keyword
GET/conversations/{phone}Get one conversation
POST/conversations/{phone}/readMark a conversation read
GET/services/{id}/conversationsService-scoped aliases

Webhooks

Event / endpointDescription
message.inboundAn inbound message for your keyword
two_way.opt_out / two_way.opt_inA phone opted out or back in
POST /services/{id}/test-webhookSend a signed test event
GET /services/{id}/webhook-deliveriesWebhook delivery log

Sandbox

MethodPathDescription
GET/sandboxSandbox context
GET/sandbox/servicesKeywords you can test
POST / PATCH / DELETE/sandbox/phonesSimulated phones
POST/sandbox/inboundSimulate a phone texting the code
POST/sandbox/sendSend to a simulated phone
POST/sandbox/demoSend a numbered demo menu
GET/sandbox/messagesSandbox threads with debug records
POST/sandbox/clockFast-forward the clock
PUT/sandbox/settingsSandbox webhook URL
POST/sandbox/resetReset the sandbox
POST / GET / DELETE/sandbox/binsRequest 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" }
  }
}
HTTPcodeWhen
400invalid_phoneto is not a valid number.
400invalid_recipient_countryto is not in the short code's country - a code only reaches its own country.
400empty_texttext is empty.
400price_unsetNo price is configured to bill the send. Contact support.
401unauthorizedMissing or invalid key or session.
402insufficient_balanceYour wallet cannot cover the send (details.required, details.available, details.currency).
403insufficient_scopeThe key lacks the scope for this endpoint.
403account_suspendedThe account is suspended and cannot send.
403recipient_opted_outThe recipient opted out of your keyword (or of the whole code).
403no_two_way_serviceSandbox: you need a two-way keyword first (pending is fine).
404not_foundService, keyword, conversation, document or bin not found (or not yours).
409service_not_activeSending needs an active or past_due keyword.
409number_unavailableThe short code is paused for sending.
409ambiguous_keywordYou hold the keyword on more than one code - pass code or service_id.
409keyword_unavailableThe keyword is taken or already requested on that country's shared codes.
409duplicate_requestYou already have the same pending request.
409invalid_stateThe service is already cancelled or rejected.
409service_not_availableSandbox: the keyword is cancelled or rejected.
409too_many_phones / duplicate_phone / too_many_binsSandbox limits.
410expiredThe request bin has expired.
413message_too_longMore than 10 segments (1,600 characters).
413file_too_largeKYC upload over 5 MB.
415unsupported_typeKYC uploads must be PDF, PNG, JPG or WEBP.
422validation_errorThe request failed validation (details.errors lists fields).
422country_unavailable / toll_free_unavailableTwo-way (or toll free) is not offered in that country.
422kyc_required / invalid_documentNo KYC document attached, or an unknown upload ID.
422invalid_numbernumber_id is not an active shared code in that country.
422invalid_url / url_not_public / invalid_emailA webhook URL or forwarding email is invalid or not public.
422auto_reply_text_requiredEnabling auto-reply without text.
429rate_limitedToo many requests - back off and retry.
503route_unavailableSending from this code is temporarily unavailable.

On this page