Building a Conversational Invoice Engine on WhatsApp

WhatsApp has over two billion active users. For small business owners in the trades (electricians, plumbers, painters), it is the communication layer of choice. The question we asked ourselves when building Kaepsi was simple: why force tradespeople to open a separate application to create an invoice, when they are already in WhatsApp all day?

The answer led us to build a conversational invoicing engine: a system that transforms unstructured WhatsApp messages into structured, legally compliant invoices.

The Three-Layer Architecture

Our engine processes every incoming message through three sequential layers.

Layer 1: the State Updater receives the raw message text alongside the user's current task stack and produces an updated stack. It determines whether the user is continuing an existing task (filling in more details for an invoice in progress) or starting a new one. The task stack is a lightweight data structure stored in Redis with a one-hour TTL, containing all currently active and completed tasks for the user.

Layer 2: the Address Resolver runs only when a delivery or service address has been mentioned. It validates the address against the Google Maps Geocoding API, normalises it to a canonical form, and, if the address is ambiguous, triggers a confirmation dialogue before proceeding.

Layer 3: the Response Generator synthesises the current task state and produces either a prompt for missing information or, when all required slots are filled, a structured execution payload ready for invoice creation.

Intent Detection and Session Management

Before the engine runs, an intent classifier determines the nature of the message. Kaepsi handles seventeen distinct intent types: from invoice creation and quote generation to payment confirmation, dunning notices, and time-tracking check-ins. Each intent routes to a dedicated handler, keeping the core engine focused exclusively on document creation.

Session state is held in PostgreSQL with a thirty-day TTL, backed by Redis for the active task window. When a user returns after a period of inactivity, the system detects the gap, saves any partial task context to the database, and offers to resume on next contact, preserving continuity without forcing the user to restart from scratch.

Why This Approach Works

The conversational model maps directly onto how tradespeople actually work. A roofer finishing a job site does not want to open a web form. They want to send a quick message on their way to the next site. Our engine accepts exactly this: free-form text, voice messages transcribed via Whisper, and mixed input. It produces a fully structured invoice draft that the user can confirm with a single tap.

The result: invoice creation in under thirty seconds, with no application to install and no interface to learn beyond the one they already use every day.