Two-Way SMS API with Webhooks: Building Automated Reply Handling

🔑 Key Takeaways:

  • Two-way SMS turns a broadcast channel into a conversation—customers reply and your system responds intelligently
  • Webhook-based reply handling enables real-time response routing without polling for new messages
  • Keyword-based automation (YES/NO/STOP/INFO) handles the majority of replies with zero human involvement

One-way SMS is a push notification system. It works fine for alerts, reminders, and confirmations where no response is expected. But the moment you send a message that invites a reply—"text YES to confirm" or "reply STOP to opt out"—you need a two-way system that actually handles what comes back.

The webhook architecture makes this reliable and real-time. Instead of your application checking for new replies every few minutes, your SMS provider calls your endpoint the instant a reply arrives. Your system processes it immediately and responds accordingly.

How Inbound SMS Webhooks Work

The flow is simple once you understand the direction of data:

  1. Customer receives your outbound SMS and replies with "YES"
  2. Your SMS provider receives the inbound message on your assigned number
  3. The provider immediately sends an HTTP POST to your webhook URL with the message data
  4. Your application processes the incoming payload, executes your business logic (confirm appointment, update database, trigger next message)
  5. Your application optionally sends a response SMS back through the same provider API
  6. The whole cycle completes in under 3 seconds from reply to action

Webhook Payload Structure

A typical inbound SMS webhook payload from a provider looks like:

POST /webhooks/sms-inbound
{
  "from": "+15551234567",
  "to": "+18005550100",
  "body": "YES",
  "message_id": "msg_abc123",
  "timestamp": "2025-05-24T14:30:00Z",
  "media_urls": []
}

Your handler receives this, normalizes the body text (trim whitespace, uppercase), and routes to your keyword handler.

Building Keyword-Based Response Logic

Keyword Typical Use Automated Response Action
YES / CONFIRM / 1 Appointment confirmation, opt-in Update booking status, send confirmation, log activity
NO / CANCEL / 2 Appointment cancellation, decline Cancel booking, free time slot, notify staff, send alternatives
STOP / UNSUBSCRIBE / QUIT / END Opt-out (TCPA mandatory) Immediately suppress from all future sends, send mandatory opt-out confirmation
START / UNSTOP Re-opt-in after previous stop Restore messaging permissions, send welcome back message
HELP / INFO Support request, information Send info message with contact options, optionally route to human agent queue
[Unrecognized] Free-text reply Route to human agent queue or NLP processor; send "Your message was received" acknowledgment

Session Management for Multi-Turn Conversations

Simple keyword handling works for one-turn interactions. For multi-step conversations—like guiding a customer through a rescheduling flow—you need session management:

Session-Based Reply Flow Example

Step 1: System sends "Your appointment is Wednesday at 3 PM. Reply YES to confirm or NO to reschedule."

Customer replies: "NO"

Step 2: System reads session state (customer is in "reschedule flow"), sends "We have Thursday at 2 PM or Friday at 10 AM available. Reply 1 for Thursday or 2 for Friday."

Customer replies: "1"

Step 3: System processes "1" in context of step 2, books Thursday at 2 PM, sends confirmation, closes session.

Session state can be stored in Redis (for high-volume systems), a database table, or even a simple in-memory cache for lower-volume applications. The key is that each incoming webhook includes the "from" number, which acts as the session key.

Handling Unrecognized Replies

Not every customer will reply with a tidy keyword. "Sure!", "Sounds good", "What time again?", "Actually can we do 4pm?"—these require either NLP processing or routing to a human agent. Design your system with this reality in mind:

  • For freeform replies that match intent but not exact keywords (e.g., "yep", "absolutely"), use fuzzy matching or simple NLP to classify intent
  • For genuinely unstructured messages, send an acknowledgment and route to a human queue: "Thanks for your message! A team member will follow up shortly."
  • Track unrecognized reply patterns—if 30% of replies to your confirmation message are "what time again?", your original message isn't including enough information

For more on building two-way SMS customer engagement systems, see our guide to automated text APIs and custom solutions.

Build a Two-Way SMS System That Actually Responds

Robotalker's API supports both outbound SMS campaigns and inbound reply handling with webhook delivery.

  • ✔️ Real-time inbound SMS webhooks
  • ✔️ Two-way dedicated numbers
  • ✔️ Automatic STOP/opt-out processing
Start Free Trial →

FAQ: Two-Way SMS Webhooks

Reputable SMS providers will retry failed webhook deliveries, typically with exponential backoff (retry after 30 seconds, 5 minutes, 30 minutes, etc.). Implement idempotency in your webhook handler using the message_id field so that duplicate deliveries during retries don't create duplicate actions.

For conversation-style two-way SMS, a dedicated long code (10DLC) or dedicated short code is strongly recommended. Shared short codes make it impossible to identify which business a consumer is replying to, and they've been largely deprecated by US carriers for A2P messaging. 10DLC registration is required for business texting in the US regardless.

Related Articles