Receive SMS with Twilio: Inbound Message Webhook Handling

# In Twilio Console:
# 1. Go to Phone Numbers > Manage > Active Numbers
# 2. Select your number
# 3. Set "A message comes in" webhook URL
# 4. Choose HTTP POST (default)

# Or configure via API:
from twilio.rest import Client
import os

client = Client(
    os.environ["TWILIO_ACCOUNT_SID"],
    os.environ["TWILIO_AUTH_TOKEN"]
)

# Update phone number webhook
number_sid = "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
incoming = client.incoming_phone_numbers(number_sid).update(
    sms_url="https://example.com/inbound-sms",
    sms_method="POST"
)
print(f"Webhook set: {incoming.sms_url}")
# Expected output:
# Webhook set: https://example.com/inbound-sms

from flask import Flask, request, Response
from twilio.twiml.messaging_response import MessagingResponse

app = Flask(__name__)

@app.route("/inbound-sms", methods=["POST"])
def inbound_sms():
    # Extract message details
    from_number = request.form["From"]
    to_number = request.form["To"]
    body = request.form["Body"].strip().upper()
    message_sid = request.form["MessageSid"]

    print(f"From: {from_number}")
    print(f"Message: {body}")
    print(f"SID: {message_sid}")

    # Prepare response
    resp = MessagingResponse()

    if body == "STATUS":
        resp.message("Your DodaTech order ORD-12345 is out for delivery.")
    elif body == "HELP":
        resp.message(
            "Available commands:\n"
            "STATUS - Check order status\n"
            "HELP - Show this menu\n"
            "STOP - Unsubscribe from messages"
        )
    elif body == "STOP":
        # Handle opt-out
        resp.message("You have been unsubscribed. Reply START to resubscribe.")
    else:
        resp.message(f"Unknown command: {body}. Reply HELP for options.")

    return Response(str(resp), mimetype="text/xml")

# Start: flask run --port 8000
# Expected output when customer texts "STATUS":
# From: +14155551234
# Message: STATUS
# SID: SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

<!-- TwiML response generated by the code above: -->
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>
        Your DodaTech order ORD-12345 is out for delivery.
    </Message>
</Response>

import sqlite3

def handle_opt_out(from_number):
    """Store opt-out preference and do not send future messages."""
    conn = sqlite3.connect("optouts.db")
    cursor = conn.cursor()
    cursor.execute("""
        INSERT OR REPLACE INTO opt_outs (phone_number, opted_out_at)
        VALUES (?, datetime('now'))
    """, (from_number,))
    conn.commit()
    conn.close()
    print(f"Opted out: {from_number}")

def is_opted_out(from_number):
    conn = sqlite3.connect("optouts.db")
    cursor = conn.cursor()
    cursor.execute(
        "SELECT 1 FROM opt_outs WHERE phone_number = ?",
        (from_number,)
    )
    result = cursor.fetchone()
    conn.close()
    return result is not None

# Check before sending
def send_sms_if_allowed(to_number, message_body):
    if is_opted_out(to_number):
        print(f"Skipped {to_number}: opted out")
        return None
    message = client.messages.create(
        body=message_body,
        from_=os.environ["TWILIO_PHONE_NUMBER"],
        to=to_number
    )
    print(f"Sent to {to_number}: {message.sid}")
    return message

# Maintain conversation state per number
conversation_state = {}

@app.route("/inbound-sms", methods=["POST"])
def sms_conversation():
    from_number = request.form["From"]
    body = request.form["Body"].strip().upper()

    resp = MessagingResponse()
    state = conversation_state.get(from_number, {})

    if body == "ORDER":
        conversation_state[from_number] = {"step": "awaiting_order_id"}
        resp.message("Please enter your order ID (e.g., ORD-XXXXX):")

    elif state.get("step") == "awaiting_order_id":
        order_id = body
        # Look up order
        conversation_state[from_number] = {"step": "awaiting_action", "order_id": order_id}
        resp.message(
            f"Order {order_id} found.\n"
            "Reply STATUS for update, CANCEL to cancel, or MENU for options."
        )

    elif body == "STATUS" and state.get("order_id"):
        resp.message(f"Order {state['order_id']} is being processed and will ship tomorrow.")
        conversation_state.pop(from_number, None)  # End conversation

    else:
        resp.message("Reply ORDER to start, HELP for commands, or STOP to opt out.")

    return Response(str(resp), mimetype="text/xml")