WhatsApp AI Assistant: Answers, Booking, Handoff

Small businesses get the same WhatsApp questions all day: prices, opening hours, location, payments, "can I book?". Answering by hand is slow, and a generic chatbot makes things up, which is worse than no answer.

I built a WhatsApp AI assistant on the official WhatsApp Cloud API. It answers from the business's own documents and shows the source, books appointments step by step against the opening hours, and hands the chat to a person when the customer asks. It speaks Spanish, Portuguese and English. The demo business is a fictional dental clinic.

Questions about prices, payments and the address were answered with their source. A question the documents don't cover got "I'd rather not guess" and an offer to talk to a person.

A full booking: Sunday refused because the clinic is closed, the next day at 10:30 accepted, confirmed as request #1, and the owner notified at once.

A Portuguese customer was understood without being asked for a language.

The run used the offline mode (no API key). With an Anthropic key, Claude writes the answers from the same documents.

Receive: Meta's signed webhook is answered at once, and the work continues in the background.

Understand: the language is detected per customer (Spanish, Portuguese or English).

Book: a step-by-step flow (service, date, time, patient name) that checks the opening hours and sends the request to the owner.

Answer: the business's documents are searched, and the answer cites its source or offers a person instead of guessing.

Hand off: the bot goes silent for that customer and relays their messages to the owner, who replies with /reply or turns the bot back on with /bot on.

Try it without WhatsApp: a terminal simulator runs the whole assistant with no account and no keys.

Only signed messages: every webhook call must carry Meta's signature. On a local server run, forged and unsigned calls got 401.

No double replies: each message id is handled once; the same message sent twice got one reply.

Flood control: 12 fast messages from one number got 8 answers and one polite "please wait".

Owner-only admin and privacy: bookings and handoffs sit behind a bearer token, tokens are compared in constant time, and phone numbers are masked in the logs.

Tested on a live run: it found that English customers could not reach a person ("I want to talk to a person" was not understood). It is fixed, with a test that fails without the fix.

245 automated tests at 98% coverage, plus ruff and strict mypy in CI.

Tech stack: Python, FastAPI, WhatsApp Cloud API, Claude (Anthropic), SQLite, Docker and Render.

Source code: github.com/mojtaba-py-code/whatsapp-ai-assistant

Want an assistant that answers your customers on WhatsApp? Send me a message with the questions your customers ask most.