Skip to main content
The Chatbot module handles WhatsApp integration, webhook ingestion, conversation state, and self-service features (results, attendance, notices, report PDFs). It can run on the public or tenant domain; tenant context is set from the incoming route or phone-number lookup so data is always scoped to the correct school.

​
API base

All chatbot endpoints are under /api/v1/chatbot/:
PathPurpose
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
Authentication: JWT or API key (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):
  1. Verification — The provider sends a challenge; the chatbot view responds so the webhook is verified.
  2. Ingestion — Incoming messages are parsed and pushed to a Celery queue so the HTTP response returns quickly and the provider does not timeout.
  3. 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_pdfs management command).
  • Welcome messages — One configurable welcome message per tenant, manageable via the welcome-messages/ API (with X-Schema-Name for 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.