API base
All chatbot endpoints are under/api/v1/chatbot/:
| Path | Purpose |
|---|---|
welcome-messages/ | CRUD for welcome messages (single message per tenant; requires X-Schema-Name or tenant context) |
students/ | Look up students linked to a phone number (e.g. for parent verification) |
get-chatbot/, results/, results/manual-template/ | Results/report retrieval and manual template generation |
generate-reports/, batch-reports/, delete-reports/ | Generate class reports, batch PDFs, delete reports |
academic-sessions/, released-exam-sessions/ | Academic and exam session info for chatbot flows |
notices/ | Fetch notices for display in chat |
X-API-KEY). Some webhook endpoints may be public for provider verification; protected endpoints require auth and correct tenant context.
Webhooks
Incoming WhatsApp messages hit webhook URLs configured in your provider (e.g. Meta/Twilio):- Verification — The provider sends a challenge; the chatbot view responds so the webhook is verified.
- Ingestion — Incoming messages are parsed and pushed to a Celery queue so the HTTP response returns quickly and the provider does not timeout.
- Tenant resolution — The phone number is matched to a WhatsAppContact (and thus a Client); the worker runs in that tenant’s schema so all Core data (students, results, notices) is correct.
Session and state
- Each user (phone number) has a session; conversation state is stored (e.g. “Awaiting Student ID”, “Main Menu”, “Viewing Exam Results”).
- Flows can be state-machine driven or extended with an LLM: unhandled text can be sent to an AI prompt with school context to generate replies.
Features
- Results — User supplies ID/PIN; system queries Core assessment data in the tenant and returns results or report links.
- Attendance — Parents can request attendance for a term/class (tenant-scoped).
- Notices — Users can fetch current notices; admins can broadcast to registered numbers (by class or form).
- Report generation — Generate individual or batch PDF reports for classes; optional cleanup of old PDFs (e.g. via
cleanup_pdfsmanagement command). - Welcome messages — One configurable welcome message per tenant, manageable via the
welcome-messages/API (withX-Schema-Namefor tenant).
Integration points
- Core — Reads students, admissions, exam sessions, exams, marks, report cards, notices, academic sessions.
- Clients — WhatsAppContact and WhatsAppStudentMapping map phone numbers to schools and students.
- Celery/Redis — Async message handling and report generation; ensure Redis and workers are running in production.
Chatbot logic always runs in tenant context when serving student/parent data. The webhook or API sets the tenant from the request (domain, header, or phone lookup) so responses never leak data across schools.