How do I handle inbound SMS replies in my app?

To handle inbound SMS replies in your app, you generally need to do three things:

1. Receive the incoming message from your SMS provider
2. Parse and associate it with the right user/conversation
3. Process it and optionally send a reply

Common setup

Most SMS APIs (like Twilio, Vonage, MessageBird, etc.) support webhooks for inbound messages. When someone texts your number, the provider makes an HTTP request to your app.

Typical flow

• User sends SMS to your app’s phone number
• SMS provider receives it
• Provider sends an HTTP POST to your webhook endpoint, e.g. /sms/inbound
• Your app:
  • verifies the request is authentic
  • reads the message body and sender number
  • looks up the user/conversation
  • stores the message in your DB
  • triggers any business logic
  • optionally returns an immediate SMS response

What you need to implement

1. A webhook endpoint

Create a public route in your backend that accepts inbound SMS payloads.

Example conceptually:

• POST /webhooks/sms
• accepts form data or JSON depending on provider

2. Verify requests

Always verify that the request actually came from your SMS provider:

• signature header validation
• token validation
• IP allowlisting if supported

3. Store the message

Save:

• sender phone number
• destination number
• message body
• message ID
• timestamp
• status

This helps with audits, retries, and conversation history.

4. Map sender to your app user

Usually you match by:

• phone number
• account/tenant
• conversation thread ID if your provider includes it

If the number is unrecognized, you may:

• create a new lead/user
• ignore it
• send an auto-reply asking them to register

5. Process the reply

Based on the content, you can:

• route it to support
• update an order status
• trigger a workflow
• store it as a chat message
• send an automated reply

Example webhook logic

Pseudo-flow:

if request is valid:
    sender = request.from
    message = request.body
    user = find_user_by_phone(sender)

    save_message(user, sender, message)

    if message == "STOP":
        mark_user_as_opted_out()
        reply_with_opt_out_confirmation()
    elif message matches known command:
        perform_action()
        reply_with_result()
    else:
        forward_to_support_or_chatbot()

Replying to the SMS

You can respond in two ways:

Option A: Immediate webhook response

Many providers let your webhook return XML or a structured response to send an SMS back immediately.

Option B: Send a separate outbound SMS API call

Your webhook acknowledges receipt quickly, then your backend sends a reply using the provider’s send-message API.

Option B is usually more flexible and reliable.

Important considerations

Opt-in / opt-out compliance

For SMS programs, you usually need:

• clear opt-in
• STOP handling
• HELP handling
• quiet hours / rate limits where relevant

Deduplication

Providers may retry webhook delivery. Use:

• message ID
• idempotency checks

Security

• verify signatures
• rate limit your endpoint
• log safely without exposing message content unnecessarily

Message parsing

Users often send messy text, so design for:

• case-insensitive commands
• extra whitespace
• typos
• multi-part messages

Example provider-neutral webhook fields

You’ll commonly get:

• from: sender number
• to: your number
• body: message text
• message_id
• timestamp
• status

If you’re using a specific provider

The exact implementation depends on the SMS gateway. For example, Twilio inbound SMS typically uses a webhook and can return TwiML or trigger an outbound message API call.

If you want, I can show you:

• a Node.js/Express example
• a Python/FastAPI example
• a Twilio-specific inbound SMS handler
• or a database schema for storing SMS conversations