Two-way SMS lets your application both send messages to a customer and receive their reply — perfect for conversational support, surveys, menus and SMS-driven workflows on any feature phone.

How it works

1. Customers text your shortcode. Messages from Safaricom and Airtel subscribers are received.
2. Sozuri forwards each message to your Inbound Messages callback URL as a JSON POST, as it arrives.
3. You reply with the standard Send SMS endpoint, using your shortcode as the from.

Sending the reply

Two-way and one-way SMS share the same request format. Use the Send SMS endpoint with your shortcode as the from field. Like any sender ID, the shortcode must be registered to your project, exactly as written, for the recipient’s network and the type you send; a recipient on a network where it is not registered comes back as sender_not_registered and is not charged.

Receiving messages

When a customer texts your shortcode, Sozuri POSTs the message to your Inbound Messages callback URL — the Inbox URL under Manage API › Callback URLs. It may be a comma-separated list; each URL receives its own copy.

The request looks like this:

POST https://your-app.example/sozuri/incoming
Content-Type: application/json
Accept: application/json
X-Sozuri-Signature: t=1762560000,v1=<hex hmac_sha256(signing_secret, "1762560000." + raw_body)>

{
    "project": "my project",
    "number": "254700000001",
    "shortcode": "20000",
    "message": "Hello, where is your Nairobi office?",
    "messageId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "channel": "interactive",
    "status": "success",
    "network": "safaricom",
    "type": "interactive",
    "timestamp": 1762560000,
    "authKey": "szk_YOUR_AUTH_KEY"
}

• One attempt. Each message is sent to your URL once, as it arrives, and is not retried if your server is down or answers with an error. Every inbound message is also saved to your project, so you can still see it in the dashboard.
• Enforce HTTPS. If it is ticked on your callback configuration, a plain http:// URL is not called at all.
• Test it. Test Inbox next to the URL on the Callback URLs page sends a signed sample. A test carries "test": true and a messageId starting sozuri_test_.
• Automatic replies. If you have switched on keyword replies or the AI agent under AI Automation, they can also answer the message. Their replies are ordinary, billed SMS.

Callback authentication

Every inbound callback carries your project’s Auth Key in the body as authKey, plus an X-Sozuri-Signature HMAC header over the raw body, so your server can confirm the request really came from us. Find both under Manage API › Callback URLs › Webhook security — see Verifying authenticity.