Inbound & two-way

Overview

When a recipient replies to one of your messages, the inbound (MO) message is attributed to the account that last messaged that number, stored, and pushed to your mo_url webhook in real time. You can also read replies over the API. STOP/START keywords are handled automatically - see Opt-outs.

Two-way messaging requires a route/number that supports inbound SMS. Check two_way per country on the Coverage endpoint.

Authentication

Authorization: Bearer esms_live_your_api_key

List conversations

GET https://sms.esmsafrica.io/api/conversations

Everyone who has replied to you (at least one inbound message), newest activity first, with a short preview of the latest message in each thread.

Parameter	Type	Description
`limit`	integer	Max conversations, up to `500` (default `100`).

Response

{
  "conversations": [
    {
      "phone": "+254712345678",
      "last_text": "YES please send more info",
      "last_direction": "inbound",
      "last_at": "2026-08-14T12:40:00+00:00"
    }
  ]
}

Get a thread

GET https://sms.esmsafrica.io/api/conversations/{phone}

The full two-way thread with one number (inbound and outbound), oldest first.

Parameter	Type	Description
`limit`	integer	Max messages, up to `500` (default `200`).

Response

{
  "phone": "+254712345678",
  "messages": [
    {
      "id": "msg_abc123",
      "text": "Reply YES to subscribe",
      "direction": "outbound",
      "status": "delivered",
      "created_at": "2026-08-14T12:30:00+00:00"
    },
    {
      "id": "mo_def456",
      "text": "YES",
      "direction": "inbound",
      "status": "received",
      "created_at": "2026-08-14T12:40:00+00:00"
    }
  ]
}

Receiving replies via webhook

Set a mo_url in your webhook settings. Each inbound message is delivered as an HMAC-signed POST:

{
  "event": "message.inbound",
  "message_id": "mo_def456",
  "from": "+254712345678",
  "to": "MyApp",
  "text": "YES",
  "keyword": null,
  "opt_out": false,
  "connector": "AT_KE"
}

keyword is set (and opt_out is true) when the reply is a recognised STOP keyword.

Example

curl https://sms.esmsafrica.io/api/conversations/+254712345678 \
  -H "Authorization: Bearer esms_live_your_api_key"

Inbound & two-way

On this page