https://github.com/josedasilva11/ai-reception-agent
AI receptionist webhook that answers, qualifies and proposes booking slots (FastAPI + LLM).
https://github.com/josedasilva11/ai-reception-agent
ai-agent booking chatbot fastapi llm openai python receptionist small-business webhook
Last synced: about 10 hours ago
JSON representation
AI receptionist webhook that answers, qualifies and proposes booking slots (FastAPI + LLM).
- Host: GitHub
- URL: https://github.com/josedasilva11/ai-reception-agent
- Owner: josedasilva11
- Created: 2026-06-29T17:14:59.000Z (3 days ago)
- Default Branch: main
- Last Pushed: 2026-06-29T17:53:59.000Z (3 days ago)
- Last Synced: 2026-06-29T19:27:13.044Z (3 days ago)
- Topics: ai-agent, booking, chatbot, fastapi, llm, openai, python, receptionist, small-business, webhook
- Language: Python
- Size: 41 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# AI Reception Agent
An AI receptionist for small businesses, exposed as a single FastAPI webhook. It receives an incoming customer message and a business profile (services, opening hours, booking rules) loaded from a YAML config, then answers FAQs, qualifies the request, and proposes concrete booking slots. The response is always structured JSON (reply text, intent, qualified flag, suggested slots), so it drops straight into WhatsApp bots, web chat widgets, or phone-to-text pipelines. It proves AI agents that answer, qualify, and book 24/7.
It works with or without an LLM key. If `OPENAI_API_KEY` is set, replies are generated by the model and grounded in the business profile. If no key is present, a deterministic rule based fallback keeps the endpoint fully functional, so you can clone and run it immediately.
## Features
- Single HTTP webhook (`POST /webhook`) returning structured JSON: `reply`, `intent`, `qualified`, `suggested_slots`.
- Business profile loaded from an editable YAML config: services, opening hours, booking rules, FAQs.
- Real booking slot generation that respects opening hours, slot length, lead time, and booking horizon.
- LLM grounded answers via the OpenAI Chat Completions API, constrained to the business profile.
- Graceful no key fallback: intent detection and FAQ matching with zero external calls.
- Built in browser demo page served at `/`, plus a copy paste curl example.
- Secrets only via environment variables, never hardcoded.
## Tech
Python 3.10+, FastAPI, Uvicorn, Pydantic, PyYAML, OpenAI Python SDK (optional at runtime).
## Run
```bash
cp .env.example .env # optional: set OPENAI_API_KEY for real LLM replies
pip install -r requirements.txt
uvicorn app.main:app --reload
```
Then open http://localhost:8000/ for the demo page.
Or call the webhook directly:
```bash
curl -X POST http://localhost:8000/webhook \
-H "Content-Type: application/json" \
-d '{"message": "Hi, do you do gel manicures on Saturday morning?"}'
```
Example response:
```json
{
"reply": "Yes, we offer gel manicures. We are open Saturday 09:00 to 14:00. Here are some times I can hold for you.",
"intent": "booking",
"qualified": true,
"suggested_slots": [
"2026-07-04T09:00:00",
"2026-07-04T09:45:00",
"2026-07-04T10:30:00"
]
}
```
To point the agent at a different business, edit `config/business.yaml` or set `BUSINESS_CONFIG` to another YAML path.
Built by José Pedro Silva, marjers.com