AI Teacher: tutoring and AI-taught classes
The AI Teacher joins a room and teaches a lesson you give it (an AI lesson). It talks, shows slides, writes and draws on a whiteboard, runs quizzes and written checks, sets timers and answers questions. There are two kinds:
mode |
|
|---|---|
"tutor" |
One-to-one. The AI listens to one learner the whole time, checks in when they go quiet, and remembers their progress between sessions. |
"class" (default) |
Many learners. The AI teaches the whole room and takes questions one person at a time (raised hands or typed questions). |
The AI Teacher is billed like the AI Agent, so it needs prepaid credit (see Pricing) and uses the same voices.
The lesson library: draft, review, approve
Nothing is taught that a person hasn't checked. You give the AI your material, it drafts a lesson plan, someone previews and approves it, and only approved plans can be taught or scheduled.
- Add material. Upload files, paste text, share a Google Docs or Slides link, or just give a topic or curriculum. The AI turns it into sections, slides, board work and quizzes. Anything it added that wasn't in your material is marked
aiSuggested: true, so reviewers know what to check (especially quiz answers). - Preview. The console shows the plan the way learners will see it, and Trial run lets you hear the AI teach it to you for 5 minutes.
- Edit. Change it yourself, or ask the AI ("make section 2 simpler and add two harder questions").
- Approve. Each approval is a new version. Lessons and timetables always teach the newest approved version; editing an approved plan doesn't change what is taught until you approve again.
In the console: open your project, then AI Teacher. Through the API:
# From a topic (the AI writes it all), or text, a Google link, a curriculum or an exam
curl -X POST https://api.appsocom.dev/lesson-plans \
-H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
-d '{ "topic": "Adding fractions", "subject": "Mathematics", "level": "JSS1", "minutes": 40,
"curriculum": "NERDC Mathematics JSS1, Term 2: fractions" }'
# → 202 {"id":"9f2c…","status":"draft","draftState":"processing",…}
# From files: PDF, Word (.docx), PowerPoint (.pptx), text, Markdown, HTML, RTF or photos of notes
curl -X POST https://api.appsocom.dev/lesson-plans/upload \
-H "Authorization: Bearer $APPSOCOM_API_KEY" \
-F file=@scheme-of-work.docx -F file=@slides.pptx -F level=JSS1Drafting takes under a minute. Your webhook gets lesson_plan_ready (with draftState "ready" or "failed"), or poll GET /lesson-plans/:id. Then:
GET /lesson-plans?status=draft |
the library (draft, approved or archived) |
GET /lesson-plans/:id |
one plan, with plan.sections to preview |
PUT /lesson-plans/:id |
edit: { "plan": {…}, "language": "fr" } |
POST /lesson-plans/:id/revise |
{ "instruction": "…" }: the AI changes it |
POST /lesson-plans/:id/trial |
a 5-minute tutor run of the plan as it is now, { "roomId"? } → { roomId, lessonId }. No reports or emails. |
POST /lesson-plans/:id/approve |
approve it as it is now (a new version) |
GET /lesson-plans/:id/versions[/:v] |
approved versions |
DELETE /lesson-plans/:id |
archive it |
POST /lesson-plans with { "plan": {…} } |
save a plan you wrote yourself (still a draft until approved) |
Files can be up to 20 MB each (photos 5 MB), 10 at a time. Old .doc and .ppt files aren't read: save them as .docx, .pptx or PDF. Google links must be shared as "Anyone with the link can view".
Each project can make 30 AI drafts and revisions a day (LESSON_DRAFTS_PER_DAY on a self-hosted kit), and only once AI is enabled for the project.
Require review before teaching
Settings in the console, or PUT /lesson-settings { "requireReview": true }, which is the default. While it is on, lessons start only from an approved plan (planId), from the API, the console and timetables alike. If you turn it off, you can also send a fully written plan straight to POST /rooms/:roomId/lessons; raw text or a bare curriculum is never taught without review either way. PUT /lesson-settings also takes defaults used by every lesson in the project: mode, scope, floor, language, name, voice, llmModel, reportEmails, guardianEmails.
Start a lesson
curl -X POST https://api.appsocom.dev/rooms/jss1-maths/lessons \
-H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
-d '{ "mode": "class", "planId": "9f2c…", "scope": "guided" }'
# → {"roomId":"jss1-maths","agentId":"agent-…","lessonId":"agent-…","participant":{…}}With review turned off you can send the plan itself instead of planId:
{
"mode": "class",
"lesson": {
"title": "Adding fractions",
"subject": "Mathematics",
"level": "JSS1",
"objectives": [{ "id": "same", "text": "Add fractions with the same denominator" }],
"sections": [{
"title": "Same denominators",
"minutes": 5,
"content": "Add the tops, keep the bottom: 1/5 + 2/5 = 3/5.",
"slides": [{ "title": "Same bottom number", "bullets": ["Add the tops", "Keep the bottom"] }],
"questions": [{ "question": "What is 2/7 + 3/7?", "options": ["5/14", "5/7", "6/7"], "answer": 1, "objective": "same" }]
}]
}
}| Field | |
|---|---|
mode |
"tutor" or "class" |
planId |
an approved plan from the library; planVersion picks an older approved version |
lesson |
only with review off: title and sections. Optional subject, level, audience, objectives. |
scope |
how strictly the AI sticks to your content (below). Default "guided". |
floor |
class only: "hands" (default, the AI calls on raised hands), "teacher" (only a human teacher picks who speaks) or "off" (typed questions only) |
learnerId |
tutor only: your id for the learner. Their progress is saved and picked up next time. |
language |
"en" (default), "pcm" or "fr" (below) |
reportEmails, guardianEmails |
email the report when the lesson ends (below) |
maxMinutes |
the lesson ends after this long. Default 60, at most 240. |
llmModel |
default claude-sonnet-5-5. claude-haiku-5-5 costs less and teaches a little less well. |
name, voice, tts, instructions, toolsUrl |
as for the AI Agent. instructions is added to the teaching rules. |
Anything you leave out comes from the project's lesson defaults, then from the plan.
GET /rooms/:roomId/lessons/:lessonId returns the lesson's state, and DELETE ends it.
How strictly the AI keeps to your content
scope |
|
|---|---|
"strict" |
Only teaches what is in the lesson. Off-topic questions are politely turned back to the lesson. |
"guided" |
Teaches the lesson and answers related questions briefly, then comes back to the plan. |
"open" |
Uses the lesson as a starting point and follows learners' curiosity. |
A human teacher can change it during the lesson.
Many learners, one at a time
In a class the AI listens to one person at a time: whoever has "the floor".
- A learner raises their hand. The AI takes hands in the order they went up, calls on each learner by name when it reaches a good moment, and listens to their mic until they finish (at most 60 seconds).
- While a learner has the floor, they are shown large to everyone (spotlight). If the room keeps their camera off, they are allowed to turn it on and get a Start video prompt (a
permissionsevent in the SDK); they choose. When the floor returns to the AI, their camera goes off again and the spotlight goes back to how it was. A teacher'scall-ondoes the same. - Typed questions (
room.askLesson(text)or the room's Q&A) are collected and answered between points, saying who asked. A question with a photo (room.askQuestion(text, { photo })) is read first, so the AI can talk a learner through their own working without solving it for them. - The AI also reads the public chat. It answers only messages that are questions or need the teacher, and ignores chatter.
- Quizzes are polls. Each learner answers on their own screen, and the AI grades every answer and goes over the results.
Only one mic is sent to speech-to-text, so a class costs the same as a one-to-one lesson.
In your app
room.lesson; // LessonState: title, section, slide, board, quiz, timer, floor, status
room.on("lesson", (lesson) => …); // sent again whenever anything changes
room.on("lesson-ended", (lessonId) => …);
room.raiseHand(); // ask to speak
room.askLesson("Why do the bottoms stay the same?");
room.vote(room.lesson.quiz.pollId, 1); // answer a quiz
room.answerCheck("x = 3"); // answer a written check (room.lesson.check)
room.on("lesson-check-result", (r) => …); // your own result: { answer, correct, feedback }Written checks
Besides multiple-choice quizzes, the AI can ask a question that everyone answers by typing: a number, an expression, an equation or a few words. It shows as lesson.check ({ id, question, kind, closesAt, closed }, with answer once it closes).
- Maths is checked by value, without a model, so any equivalent form is right:
2(x+1),2x + 2and\frac{4x+4}{2};x = 3and9/3;x = 2 or x = 3in any order;0.33for1/3(rounded to at least 2 places). Plain text and LaTeX both work. - Answers in words, with units, or that the maths check can't read are marked by a fast model, which also writes one line of feedback on each wrong answer without giving the answer away.
- The check closes when its time is up or as soon as everyone has answered. Each learner gets their own result (
correctisnullif it couldn't be marked), and the AI hears how the class did, with the most common wrong answers, so it can go over them. - Results count in the lesson report like quiz answers (
writtenholds what they typed).
In Flutter: room.answerCheck('x = 3') and the LessonCheckResult event.
React: useLesson() returns { lesson, ask, control }, and LessonWhiteboard, LessonSlideView and LessonStatusBar draw the lesson.
The whiteboard is a list of items (text, maths, lists, shapes, images, highlights) placed in fractions of a 16:10 board. The AI also draws them as pen strokes on topic "whiteboard" app messages, so stroke-based whiteboards show its writing too. Turn this off with "strokes": false.
There is a sample page at /demo/lesson.html in the Worker template.
Human teachers
Anyone with the teacher role (or a moderator) can control the lesson from the room:
room.controlLesson({ action: "pause" }); // and "resume"
room.controlLesson({ action: "takeover" }); // the AI goes quiet and listens to you
room.controlLesson({ action: "handback" });
room.controlLesson({ action: "goto", section: 2 }); // 0-based, like lesson.section
room.controlLesson({ action: "call-on", userId: "ada" });
room.controlLesson({ action: "scope", scope: "strict" });
room.controlLesson({ action: "note", text: "Go slower, they're struggling" }); // only the AI sees it
room.controlLesson({ action: "end" });Your backend can do the same (except takeover and handback) with POST /rooms/:roomId/lessons/:lessonId/control.
Safeguarding
If a learner says something that suggests they may be at risk of harm, or bullies someone, the AI responds kindly and briefly, never promises to keep a secret, and alerts a human straight away. It also alerts a teacher when it needs a human's help. Teachers in the room get a lesson-alert event (severity is "urgent", "concern" or "help"), and your webhook gets lesson_alert. Alerts are also in the report.
Always have an adult responsible for the class who receives these alerts.
Reports and progress
When a lesson ends, GET /lessons/:lessonId/report returns a summary, each learner's attendance, quiz answers, contributions, objectives (met, weak or not-seen), the AI's notes and feedback, any alerts and the transcript. Your webhook gets lesson_ended.
For tutors with a learnerId, GET /learners/:learnerId/progress returns what they have covered and what they found hard. DELETE removes it.
Webhooks: lesson_started, lesson_section, lesson_quiz, lesson_ended, lesson_alert.
Courses and timetables
A course is approved lessons in order (POST /courses { "title", "subject", "level", "plans": [planIds] }). A timetable slot that teaches a course moves to the next lesson each time.
A timetable starts lessons by itself at set times, in the school's own time zone:
{
"name": "JSS1 A",
"timeZone": "Africa/Lagos",
"termStart": "2027-01-11", "termEnd": "2027-04-02",
"holidays": ["2027-03-26"],
"slots": [{ "days": [1, 3], "start": "09:00", "minutes": 40, "roomId": "jss1a", "courseId": "…" }],
"sessions": [{ "date": "2027-02-20", "start": "10:00", "minutes": 60, "roomId": "jss1a", "planId": "…", "label": "Revision" }],
"defaults": { "mode": "class", "reportEmails": ["form.teacher@school.ng"] },
"active": true
}days are 0 (Sunday) to 6. Send it to POST /timetables (PUT /timetables/:id to change it). A school can have as many timetables as it likes, one per class or teacher. If two lessons would be in the same room at the same time the save is refused with a 409 listing the clashes; add ?allowClashes=true to save anyway.
GET /timetable-runs?days=7 lists what is coming up and what already ran (upcoming, started, failed, skipped). POST /timetable-runs/:key/start starts one now and /skip skips it. A lesson that can't start (no approved version, AI off, the project's limit reached) is marked failed and your webhook gets lesson_schedule_failed. Lessons start within a minute of their time; one more than 10 minutes late is not started.
Exam practice
"style": "practice" with "exam": { "board": "WAEC", "subject": "Mathematics", "year": "2023" } makes a past-question style practice session: exam-style questions with the board's format, timed, worked solutions and exam tips. Boards: WAEC, NECO, JAMB, BECE, NABTEB. Create one in the library with POST /lesson-plans { "exam": {…}, "topic"? }; the AI writes questions in the style of the exam, which reviewers should check like any other quiz.
Languages
language sets the language the AI teaches in. Reports stay in English.
en |
English (default) |
pcm |
Nigerian Pidgin |
fr |
French, spoken and heard |
Emailed reports
When a lesson ends the report can be emailed:
reportEmails: teachers get the whole class's report, including any safeguarding alerts.guardianEmails:{ "learner-user-id": ["mum@example.com"] }. Each parent or guardian gets only their own learner's part, never alerts (a school's safeguarding lead decides what parents are told).
Set them per lesson, on a timetable's defaults, or in the project's lesson defaults. Trial runs send no email.
How many at once
Set the most AI lessons a project can run at the same time on the project's page in the console. Starting one more returns 429. Each lesson runs in its own room, so a school can teach several classes at once.
What it costs
A lesson costs about the same per minute whether one learner or a whole class is listening:
| per lesson minute | |
|---|---|
| Sonnet 5.5 (default) + Cartesia voice | about $0.039 |
| Haiku 5.5 + Deepgram voice | about $0.023 |
A 40-minute class on the default settings is about $1.56, or about 5 cents per learner for a class of 30. The worst case is a lesson that runs to maxMinutes, so keep that close to the real length.
Drafting a plan with the AI costs about $0.05 to $0.15 (a long PDF with many pages up to about $0.80). A project can make at most 30 drafts and revisions a day, so the most drafting can cost is about $24 a day. A trial run is at most 5 minutes, about $0.20.
Server SDKs
const draft = await appsocom.createLessonPlan({ topic: "Adding fractions", level: "JSS1" });
// …after lesson_plan_ready and a person's review:
await appsocom.approveLessonPlan(draft.id);
const { lessonId } = await appsocom.startLesson("jss1-maths", { mode: "class", planId: draft.id });
await appsocom.controlLesson("jss1-maths", lessonId, { action: "goto", section: 1 });
const report = await appsocom.lessonReport(lessonId);Node also has uploadLessonMaterial, updateLessonPlan, reviseLessonPlan, trialLessonPlan, lessonPlanVersions, listLessonPlans, saveCourse, saveTimetable, timetableRuns, startTimetableRun, skipTimetableRun and lessonSettings / setLessonSettings. Python (create_lesson_plan, upload_lesson_material, …), PHP, Dart and Go (CreateLessonPlan, …) have the same methods; uploading files is in Node and Python (in the others, send text or a Google link, or use request).