Atharv Vadehra

Distributed Systems

WhatsApp Appointment Automation Bot

Engineered an automated WhatsApp conversational booking assistant using Twilio API and Python FastAPI. Implemented intelligent slot-finding algorithms, structured interactive message templates, automated calendar sync, and proactive customer reminder workflows.

PythonFastAPITwilio APIWebhooksRedisPostgreSQLDocker

View on GitHub

Project Architecture

Manual appointment scheduling in healthcare and service industries suffers from high administrative overhead and missed appointments. This bot enables natural conversational scheduling directly via WhatsApp with zero app installations required by end clients.

[ Client WhatsApp ] ──► [ Twilio WhatsApp Sandbox / API ]
                                    │
                              (HTTP Webhook)
                                    │
                                    ▼
                         [ FastAPI Webhook Worker ]
                                    │
                     ┌──────────────┴──────────────┐
                     ▼                             ▼
           [ Slot-Finding Algorithm ]     [ PostgreSQL Calendar DB ]
                     │
                     ▼
           [ Interactive Response + Reminders (Twilio) ]

Core Capabilities & Algorithmic Design

  1. Stateful Conversation Engine: Maintains session state in Redis with time-to-live (TTL) expiration to track intent progression across user messages.
  2. Dynamic Slot-Finding Algorithm: Scans provider schedules to find conflicts, merges overlapping breaks, and presents the top 3 earliest available time windows.
  3. Structured Interactive Templates: Generates WhatsApp quick-reply buttons and list pickers for rapid, error-free date selection.
# FastAPI webhook handler snippet
from fastapi import FastAPI, Request, Response
from twilio.twiml.messaging_response import MessagingResponse

app = FastAPI()

@app.post("/whatsapp/webhook")
async def handle_incoming_message(request: Request):
    form_data = await request.form()
    incoming_msg = form_data.get('Body', '').strip().lower()
    sender_phone = form_data.get('From')

    resp = MessagingResponse()
    msg = resp.message()

    if "book" in incoming_msg or "appointment" in incoming_msg:
        available_slots = await find_earliest_slots()
        msg.body(f"Welcome! Here are the available slots:\n{available_slots}\nReply with slot number to confirm.")
    else:
        msg.body("Hello! Reply 'book' to schedule an appointment.")

    return Response(content=str(resp), media_type="application/xml")

Reliability & Reminders

  • Background asynchronous tasks trigger reminders 24 hours and 2 hours prior to scheduled slots, drastically cutting no-show rates.
  • Cryptographic signature validation (X-Twilio-Signature) verifies that incoming webhook payloads originate exclusively from Twilio servers.