# AI Presenter: presentations of any kind

The AI Presenter joins a room and presents to an audience for your organisation: a product or app, a proposal, a report or results, an idea or pitch, training, or anything else. It talks people through slides and screenshots (with the part that matters highlighted), shows charts, writes on the whiteboard, and takes questions. A person from your team can present with it: either of you can lead, and you can swap at any time.

While it presents, it writes down what the audience suggests or asks for, so your team can review it afterwards.

For a product, it can also **demo your real app live**: it opens your app in a cloud browser that everyone sees as its screen share, and clicks through it while it talks.

The audience can join on video or audio only, like any room.

The AI Presenter needs prepaid credit and costs **₦100 per minute** while it is in the room, instead of the AI Agent price (see [Pricing](https://docs.appsocom.dev/pricing.md)). An avatar face costs ₦300 per minute on top.

## 1. Make a presentation kit

A kit is everything the presenter needs: what your product is, the screens to show, the charts, the questions people usually ask, and what not to say. It lives in the same library as [AI Teacher](https://docs.appsocom.dev/ai-teacher.md), so it's drafted, reviewed and approved the same way. Nothing is presented until someone approves it.

In the console: open your project, then **AI Teacher → Presentations → New presentation**. Upload screenshots, add your notes, and the AI drafts the scenes. Through the API, send `style: "presentation"` with a brief:

```bash
curl -X POST https://api.appsocom.dev/lesson-plans \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{ "style": "presentation", "title": "Paywise for schools", "minutes": 20,
        "text": "Paywise collects school fees by card, transfer and USSD…",
        "presentation": {
          "organisation": "Paywise", "product": "Paywise School Fees",
          "appUrl": "https://app.paywise.example",
          "goal": "Bursars sign up for a free pilot",
          "lead": "ai",
          "avoid": ["Prices for more than 5,000 pupils", "Dates for features not released"],
          "faq": [{ "question": "Can parents pay in instalments?", "answer": "Yes, up to 3 per term." }],
          "followUp": "Our sales team replies within a day",
          "charts": [{ "title": "Fees collected on time", "type": "bar", "unit": "%",
                       "labels": ["Before", "After 1 term"], "series": [{ "name": "Pilot schools", "values": [61, 89] }] }]
        } }'
```

| Brief field | |
|---|---|
| `kind` | What you're presenting: `product`, `proposal`, `report`, `idea`, `training` or `other`. It sets the presenter's tone (a product specialist, an advisor making a case, a neutral analyst…), how the AI drafts the scenes, and what it notes for you. Default `product` when there's a `product` or `appUrl`, otherwise `other`. |
| `organisation`, `product` | Who is presenting and what (the product, the proposal, the report's subject…). |
| `appUrl` | Your app's link (https). It's mentioned to the audience; live demos will use it. |
| `goal` | What a good presentation ends with (a sign-up, a pilot, a decision). |
| `lead` | `"ai"` (default) or `"human"`: who leads when the presentation starts. |
| `liveDemo` | `false` to show screenshots only. On by default when there's an `appUrl`. |
| `demoLogin` | `{ "username", "password" }` of a demo account for the live demo. The AI never sees them (see below). |
| `demoSteps` | Scripted steps for the live demo, run exactly (see below). |
| `avoid` | Things the presenter must not say or promise. When asked, it says a person will follow up. |
| `faq` | Questions and the answers you want given. The presenter keeps to these answers. |
| `followUp` | What happens after (who gets in touch, how). |
| `charts` | Up to 20 charts: `bar`, `line`, `pie` or `table`, with `labels` and up to 6 `series` of `values`. |

Each **scene** of the kit (a section) has **screens** (slides). A screen can carry a screenshot (`imageUrl`) and a `highlight` box (`x`, `y`, `w`, `h` as fractions of the image, and an optional `label`), or a `chart`. Upload screenshots first and use the links it returns:

```bash
curl -X POST https://api.appsocom.dev/presentation-assets \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" \
  -F file=@dashboard.png -F file=@checkout.png
# → {"assets":[{"name":"dashboard.png","url":"https://api.appsocom.dev/presentation-assets/3f…png"},…]}
```

Screenshots are PNG, JPEG, WebP or GIF, up to 5 MB each and 20 per upload. Their links are public (anyone with the link can open them), so don't upload anything secret.

Then preview, **Trial run** (10 minutes, presented to you), edit or ask the AI to change it, and **Approve**, exactly as for [lessons](https://docs.appsocom.dev/ai-teacher.md#the-lesson-library-draft-review-approve).

## 2. Start a presentation

```bash
curl -X POST https://api.appsocom.dev/rooms/paywise-demo/presenter \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{ "planId": "9f2c…", "lead": "ai", "name": "Ada from Paywise",
        "reportEmails": ["sales@paywise.example"] }'
# → {"roomId":"paywise-demo","agentId":"agent-…","lessonId":"agent-…","presentationId":"agent-…",…}
```

It takes the same options as [starting a lesson](https://docs.appsocom.dev/ai-teacher.md#start-a-lesson) (voice, avatar, `reportEmails`, `webhookUrl`), plus `lead` to override the kit. It always runs for a whole room (there's no tutor mode). The default name is "AI Presenter".

## Live demo of your app

With an `appUrl`, the presenter can show the real app instead of screenshots. It opens the app in a cloud browser (Cloudflare Browser Run), and the browser becomes the presenter's **screen share** in the room, at 1280×720. Everyone sees it in the same place they'd see a person sharing their screen.

- **How the AI uses it.** It reads the page as a list of what's on screen ("[4] button: Create class"). It clicks, types, scrolls, goes back and points at things (a ring with a caption), one step at a time, saying what it does.
- **It stays on your site.** It can visit the app's address and other pages on the same domain (for example `app.acme.ng`, `acme.ng` and `docs.acme.ng`). Links to other sites are refused, and it comes straight back.
- **Signing in.** Give the kit a `demoLogin`. The AI types `{{username}}` and `{{password}}`, and the browser fills them in, so the model never sees or says them. Use a demo account with nothing private in it: the audience sees everything on the screen.
- **Scripted steps.** For the parts you want shown the same way every time, give the kit `demoSteps` (or write them in the console's kit editor). Each step has a `title`, and optionally a `url` (a page of your site; a path like `/classes` is read against `appUrl`), the element to show by `selector` (CSS) or `text` (what it says on screen, or its field label), an `action` (`point`, the default, rings it; `click`; or `type`, which types the step's `input` and, with `submit: true`, presses Enter) and `say`, what the presenter says there. The presenter runs a step exactly when the storyboard gets to it, and browses on its own for everything else. If a step can't find its element, it says so lightly and does it by hand or moves on. Pages off your site are dropped when the kit is saved, and `input` must be made-up demo data: `{{username}}`/`{{password}}`, your demo password, keys, tokens and card numbers are refused, and nothing is ever typed into a password field. Steps cost nothing extra: they're part of the presentation minutes.

```json
"demoSteps": [
  { "title": "Create a class", "url": "/classes", "text": "New class", "action": "click", "say": "Creating a class takes one click." },
  { "title": "Name it", "selector": "input[name=title]", "action": "type", "input": "Grade 5 Maths", "submit": true }
]
```

- **When it can't open.** It says so briefly and carries on with the kit's screenshots. Keep screenshots in the kit as a fallback.
- **Speed.** The screen share is usually up 4 to 7 seconds after the AI opens the app. It uses about 0.6 to 1 Mbit/s for viewers while the page moves, and much less while it's still.

### A person can take the browser

A host in the room can **take the browser** to drive it themselves. Clicks on the shared screen go to the app, and they can type, scroll and go back. The AI stops using it until they **give it back**. The UI kits will add these buttons. Through the room connection, send the lesson control `browser` (moderators only):

| Control | |
|---|---|
| `{ "action": "browser", "browser": "take" }` | You drive (this opens the app if it isn't open). |
| `{ "action": "browser", "browser": "op", "op": { "op": "click-at", "x": 0.42, "y": 0.18 } }` | Click a point of the shared screen (0 to 1 from the left and the top). Also `type` (`text`, `submit`), `key`, `scroll` (`direction`), `back`, `open` (`url` on your site). |
| `{ "action": "browser", "browser": "give" }` | Back to the AI. |
| `{ "action": "browser", "browser": "close" }` | Stop the screen share. |

Your server can do the same through `POST /rooms/:roomId/lessons/:lessonId/control`.

The lesson state has `demo` (`state`: `starting`, `live`, `failed` or `ended`; the page `url`; and `driver`, which is `"ai"` or the userId of the person driving). The report has `demoMinutes`. The live demo is included in the AI Presenter price per minute.

**Self-hosting the kit:** add `"browser": { "binding": "BROWSER" }` to `wrangler.jsonc` (Workers Paid plan) and deploy the bot (`wrangler.video.jsonc`). It runs the new `screen` mode. Without the binding, presenters use screenshots.

## What it does in the room

- **Presents** each scene, showing the live app, the screenshot with its highlight, the chart, or the board work, and checks that people are following.
- **Takes questions** by raised hand or typed. If it doesn't know, or the answer is in `avoid`, it doesn't guess: it **parks** the question to come back to, **sends it to your host** (an alert in the room), or **promises a follow-up** that goes in the report.
- **Shows charts** from the kit when they help an answer.
- **Knows your organisation.** If your project has a [knowledge base](https://docs.appsocom.dev/knowledge.md) (policies, handbooks, fees, FAQs), the presenter looks things up in it before it answers a question the kit doesn't cover, or adds to a discussion about how you do things, and keeps to what your documents say. The room's own documents count too. Only approved documents are used, and if nothing matches it doesn't guess.
- **Writes down suggestions**: feature requests, objections, confusion, bugs, pricing worries, praise and ideas from the audience, with who said them. A host can add one too.

### Who leads

| `lead` | |
|---|---|
| `"ai"` | The AI presents. The co-presenter can step in at any time. |
| `"human"` | The person presents. The AI stays quiet unless someone addresses it ("presenter", "AI", "assistant" or its name), or the person sends it a note. Then it answers briefly and hands back. |

If the human co-presenter leaves, the AI takes over. Switch from the room (the lesson controls) or through the API:

```bash
curl -X POST https://api.appsocom.dev/rooms/paywise-demo/lessons/agent-…/control \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{ "action": "lead", "lead": "human" }'
```

When the API hands the lead to a person, the first host in the room becomes the co-presenter. Other controls are the same as lessons (`pause`, `resume`, `goto`, `call-on`, `note`, `end`), plus:

| Control | |
|---|---|
| `{ "action": "lead", "lead": "ai" \| "human" }` | Change who leads. |
| `{ "action": "suggestion", "text": "…", "kind": "feature-request" }` | Add a suggestion to the report yourself. |
| `{ "action": "introduce" }` | The presenter says its name and its role in one sentence, then carries on. Also **Introduce yourself** in the kits' Presentation panel. |

You can also add an [AI Teammate](https://docs.appsocom.dev/ai-teammate.md) to the same room, for example a scribe that keeps the minutes. "Hey AI" goes to the presenter while it presents; the AI Teammate answers to its own name, and the two never talk over each other (see [With an AI Presenter in the room](https://docs.appsocom.dev/ai-teammate.md#with-an-ai-presenter-in-the-room)).

## Self-running presentations

Share a link and let the AI Presenter present on its own. Each visitor gets a **private presentation**: their own room, and the presenter starts the moment they join. Nobody from your team needs to be there. In a private presentation the visitor just speaks or types, with no raised hand, and the presenter answers them by name.

```bash
# 1. A link for an approved kit
curl -X POST https://api.appsocom.dev/presentation-links \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{"planId":"9f2c…","title":"Our proposal for Lagos schools","reportEmails":["sales@acme.ng"],"askDetails":["name","email","company"]}'
# → {"id":"pl_…","maxMinutes":30,"perDay":50,"maxConcurrent":5,"active":true,…}

# 2. A visitor opens it: your backend sends what they typed in your form
curl -X POST https://api.appsocom.dev/presentation-links/pl_…/sessions \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{"visitor":{"name":"Ngozi Eze","email":"ngozi@school.ng","company":"Bright Minds"}}'
# → {"sessionId":"ps_…","roomId":"pres-…","token":"…","expiresAt":…}
```

Join the visitor to `roomId` with `token` (they join as a guest: microphone and camera, no host rights). The presenter starts when they arrive, once per session.

| Link field | |
|---|---|
| `planId` | the approved presentation kit (required). `planVersion` pins a version; without it each session uses the newest approved one |
| `title` | shown to visitors and in your lists |
| `name`, `voice`, `avatar` | the presenter's name (default "AI Presenter"), voice and face |
| `reportEmails` | up to 20 addresses: each lead the moment it happens, and the report when a session ends. Default: the project's report emails |
| `askDetails` | which of `name`, `email`, `company`, `phone` the visitor must give. Default `["name","email"]` |
| `maxMinutes` | longest session, 1 to 120. Default 30 |
| `perDay` | new sessions a day (UTC). Default 50 |
| `maxConcurrent` | sessions at the same time. Default 5. A visitor who never joins stops counting after 30 minutes |
| `active` | `false` closes the link: new sessions are refused |

Past a limit, `POST …/sessions` answers 429 with a message you can show the visitor ("every presenter is busy right now…").

**Leads, at once.** When the presenter promises a visitor a follow-up, or sends a question to a person, `reportEmails` get an email straight away with the question and the visitor's details, and your webhook gets `presentation_lead` (`lesson.kind` `follow-up` or `host`, `question`, `note`, `visitor`, `sessionId`, `linkId`). The full report follows when the session ends, with the visitor and link on it.

**Your team can step in.** `POST /presentation-sessions/:id/join {"name":"Tunde"}` gives a colleague a host token for that visitor's room: they see the presenter's alerts and can take over.

Other calls:

- `GET /presentation-links`, `GET|PATCH|DELETE /presentation-links/:id`
- `GET /presentation-sessions?linkId=`: sessions newest first, each with its visitor, `status` (`waiting`, `live`, `ended`, `failed`), `leads`, question count and summary. The newest 5,000 per project are kept
- `GET /presentation-sessions/:id`

Each session is billed as presenter minutes, like any AI Presenter session (see [Pricing](https://docs.appsocom.dev/pricing.md)). If the project can't use AI right now (no credit, paused), `POST …/sessions` answers 403 before anyone joins.

## After the presentation

The report (`GET /lessons/:lessonId/report`, the `lesson_ended` webhook with `lesson.style: "presentation"`, and the email to `reportEmails`) has:

| | |
|---|---|
| `summary` | How it went. |
| `recommendations` | What the AI recommends your team does next, based on the questions and suggestions. |
| `suggestions` | Each one with `kind` (`feature-request`, `objection`, `confusion`, `bug`, `pricing`, `praise`, `idea`, `other`), `text`, who said it, and whether the AI or a host noted it. |
| `questions` | Every question asked and what happened to it: `answered`, `parked`, `host` or `follow-up`. |
| `alerts` | Questions sent to the host during the session. |

Every presentation is also kept for your team to review: in the console under **Presentations → Recent sessions**, where each suggestion can be marked reviewed, accepted or dismissed. Through the API:

```bash
GET /presentation-reports?planId=9f2c…   # sessions, newest first, with counts of new suggestions
GET /presentation-reports/:id            # one session
PUT /presentation-reports/:id/suggestions/0   {"status":"accepted"}   # new | reviewed | accepted | dismissed
```

The newest 500 sessions per project are kept.

## In your app

The UI kits show a running presentation on the stage in any kit: `AiLesson`, but also the meeting room and the classroom, with a **Presentation** panel for hosts. Everyone sees the live app, the screens (screenshots with their highlight, and charts) and the board, with a switch between them.

- **The live app.** `LessonDemoView` (React and Flutter) shows the presenter's screen share. A host can **Take the browser**: then clicking or tapping the picture clicks the app at that point, and a toolbar has back, scroll, a box to type into the app, and **Give back to AI**. Everyone else just watches, with a line that says who is driving.
- **Host controls** in the Presentation panel: **Who leads** (the AI or you), **Live demo** (open the app, take the browser, give it back, close it), and the lesson controls (pause, sections, notes, end).
- With the React kit, `LessonSlideView` draws screenshots with their highlight and charts (`PresentationChartView`); chart colours come from `--sfk-chart-1` to `--sfk-chart-6`. Older apps still show a chart's values as bullet points.

## From the SDKs

Every server SDK has presenter helpers next to the lesson ones (the presentation id is a lesson id, so `controlLesson`, `stopLesson` and `lessonReport` work too):

| | Node | Python | PHP | Go | Dart |
|---|---|---|---|---|---|
| Start | `startPresenter(room, { planId, lead })` | `start_presenter(room, planId=…)` | `startPresenter($room, [...])` | `StartPresenter` | `startPresenter` |
| Who leads | `setPresenterLead` | `set_presenter_lead` | `setPresenterLead` | `SetPresenterLead` | `setPresenterLead` |
| The browser | `presenterBrowser(room, id, "take" \| "give" \| "close" \| op)` | `presenter_browser` | `presenterBrowser` | `PresenterBrowser`, `PresenterBrowserOp` | `presenterBrowser` |
| Sessions | `listPresentationReports`, `getPresentationReport`, `reviewSuggestion` | `list_presentation_reports`, `get_presentation_report`, `review_suggestion` | same as Node | `ListPresentationReports`, `PresentationReport`, `ReviewSuggestion` | same as Node |
| Screenshots | `uploadPresentationAssets` | `upload_presentation_assets` | | | |
| Self-running links | `createPresentationLink`, `listPresentationLinks`, `getPresentationLink`, `updatePresentationLink`, `deletePresentationLink` | `create_presentation_link(plan_id, …)`, `list_…`, `get_…`, `update_…`, `delete_presentation_link` | same as Node | `CreatePresentationLink`, `ListPresentationLinks`, `PresentationLink`, `UpdatePresentationLink`, `DeletePresentationLink` | same as Node |
| A visitor's session | `startPresentationSession(link, visitor)`, `listPresentationSessions`, `getPresentationSession`, `joinPresentationSession` | `start_presentation_session(link, name=…, email=…)`, `list_…`, `get_…`, `join_presentation_session` | same as Node | `StartPresentationSession`, `ListPresentationSessions`, `PresentationSessionInfo`, `JoinPresentationSession` | same as Node (named visitor fields) |

```js
const { presentationId } = await kit.startPresenter("paywise-demo", { planId, lead: "ai", reportEmails: ["sales@paywise.example"] });
await kit.presenterBrowser("paywise-demo", presentationId, "take");
await kit.presenterBrowser("paywise-demo", presentationId, { op: "click-at", x: 0.42, y: 0.18 });
await kit.presenterBrowser("paywise-demo", presentationId, "give");
```

A self-running presentation from your backend, when a visitor submits your form:

```js
const { roomId, token } = await kit.startPresentationSession(linkId, { name, email, company });
// Send roomId and token to the visitor's browser and join with the client SDK or a UI kit.
```

The visitor's form is ready-made in the UI kits: `<PresentationLobby title askDetails onStart />` in React and `PresentationLobby(title:, askDetails:, onStart:)` in Flutter. `onStart` gets `{ name, email?, company?, phone? }`: call your backend, then join with the token. An error you throw is shown on the form.

```tsx
<PresentationLobby
  title="Our proposal for your school"
  askDetails={["name", "email", "company"]}
  onStart={async (visitor) => {
    const r = await fetch("/api/presentation", { method: "POST", body: JSON.stringify(visitor) });
    if (!r.ok) throw new Error((await r.json()).error);
    setJoin(await r.json()); // { roomId, token } → mount the meeting kit
  }}
/>
```

## In Spaces

In a white-label space, the space's owner makes and approves kits in the console: open the space and press **Open presentation kits** (the space's own AI Teacher pages). Then:

- **Hosts** press **AI Presenter** on a room in the space's admin page, pick an approved kit, who leads, the name it uses and whether it shows a face, and **Start presenting**. They join the room as host to watch, take the lead or take the browser, and can stop it from the same place. The report is emailed to the host who started it.
- **Admins** get a **Presentations** tab: each session with its summary, recommendations, questions and suggestions, and each suggestion can be marked reviewed, accepted or dismissed.

It costs the same <span data-price="presenterMinutes">$0.067</span> per minute from the account's credit.
