Pages & screens
A page of the app's own, drawn by its agents: the agenda, a form, a ticket. Deployed with the app, with no server to write.
A voice app can have a page of its own, and its agents draw it. A caller who talks to the line from that page sees the agenda when the agent reads it, a form when a tool needs something from them, and their ticket once the visit is booked. You write the page once and Pinecall serves it.
What is a screen?#
What an agent puts on its caller's page, from the same state the model reads. It is a method beside the tools:
import { Agent, part, tool, type Asked } from "@pinecall/agents";
const Agenda = part<{ slots: Slot[]; picked: string }>("agenda");
const Form = part<Asked>("form");
const Ticket = part<{ visit: Visit }>("ticket");
export default class FrontDesk extends Agent {
slots: Slot[] = [];
picked = "";
visit: Visit | null = null;
override screen() {
const asked = this.call.asking;
if (asked !== undefined) return <Form {...asked} />;
if (this.visit !== null) return <Ticket visit={this.visit} />;
return <Agenda slots={this.slots} picked={this.picked} />;
}
}
The screen follows the conversation#
A screen that only reads the state stays on what the state holds. Declare the scenes the screen has, and which tool puts each one up:
@agent({ scenes: { agenda: "the open times you last read", ticket: "the visit booked on this call" } })
@tool({ shows: "agenda" })
freeSlots(day: string) { … }
override screen() {
if (this.call.scene === "agenda") return <Agenda slots={this.slots} />;
return <Welcome />;
}
The caller asks for Tuesday: the agenda comes up. They ask who they are talking to: the agent answers and the agenda goes away. They ask for the times again: it comes back.
A turn the caller opened in which nothing showed the scene takes it away. The model is told which scene is up, and has a tool of its own to keep it or put another up, which it calls in the same turn as its words, with no wait.
A part is a name and plain data. It carries no markup and no style: the agent says what is on the
screen, and the page says how it looks. screen() is drawn again whenever the state moves, a tool
ends or a tool stops to ask, and nothing is sent while the screen is the one already there.
part<Props>("agenda") |
a part of your own: a tag in a .tsx file, and a function (Agenda({ slots })) in a .ts one |
screen() |
what the page shows now. Parts nest, and a component that is no part is called |
@agent({ scenes }) · @tool({ shows }) · this.call.scene |
the scenes of the screen, the tool that puts each up, the one up now |
this.call.asking |
what a tool stopped to ask for with this.ask(GetPhone): { task, asks, fields }, so the screen can draw the question as a form |
this.call.show(<Map />) |
puts a part over the screen at once, from a tool or a hook; this.call.show(null) takes it away |
The page#
The page maps each part to a component of its own. With React and @pinecall/room:
import { hosted, screenOf } from "@pinecall/room";
import { Screen, useRoom } from "@pinecall/room/react";
const PARTS = { agenda: Agenda, form: Form, ticket: Ticket };
export function App() {
const call = useRoom(hosted());
return (
<>
<button onClick={() => call.start("talk")}>Talk to the front desk</button>
<Screen screen={screenOf(call.log)} parts={PARTS} />
</>
);
}
The page shows whatever the call's agent drew last. When the call passes to another agent of the team, the screen is that agent's from then on.
hosted() is how the page gets its ticket: it asks its own name, and Pinecall answers. There is no
server to write and no key in the page.
What the caller does on the page#
A tap is an event the class declares, as on any page:
@agent({ events: { "slot.picked": { from: ["participant"] } } })
override onEvent(_name: string, tapped: Record<string, unknown>) {
this.picked = `${tapped["day"]} ${tapped["time"]}`;
void this.reply(`The caller tapped ${this.picked} on their screen. Read it back and ask for their yes.`);
}
<button onClick={() => call.event("slot.picked", { day: slot.day, time: slot.time })}>{slot.time}</button>
One event is Pinecall's own. When the screen shows what a tool stopped to ask for, the page gives the answer in the model's place:
call.event("task.give", { task: "phone", given: { number: "+14155550142" } });
The task checks it as it checks what the model gives. The tool that asked goes on, and the model is
told how it ended so it can say so. A value the check refuses comes back on
this.call.asking.refused.
Anybody can send what a browser sends. A tap changes the state and may make the agent speak; it never books, pays or cancels on its own. The model does that on the caller's word.
Deploy it#
Name the folder your page builds into, in app.ts:
app.page("ui/dist");
pnpm ui:build && pinecall deploy
brightside-dental · release 5 sent · 268 KB · 9c1e44d07a31
→ its page: https://brightside-dental--acme.app.pinecall.io/
| the page's address | |
|---|---|
| production | https://<app>--<org>.app.pinecall.io |
| the sandbox | https://<app>--<org>--sandbox.app.pinecall.io |
A page in one environment only. app.page("site", { only: "sandbox" }) keeps the page to the
sandbox: pinecall deploy --prod sends the app alone, nothing is served at its production name, and
its visitors come from wherever the widget is (your own site, with its own ticket endpoint).
{ only: "production" } is the other way round, and with neither the page is in both. pinecall start
follows the same rule for the environment it holds the app in.
A visitor reaches the agent of the app's first line, or the one app.page("ui/dist", { answers: Billing })
names. Before a ticket the visitor passes a captcha, shown only when Cloudflare asks them for
something.
While you write it#
pinecall start serves the same folder and the same routes on http://localhost:4747, with your own
key and no captcha. A dev server of yours only passes /pinecall on to it:
server: { proxy: { "/pinecall": "http://localhost:4747" } }
What to know#
- An app has one page. Its routes are its own: a path that names no file is answered with the page.
- A page has no caller id:
call.contactis empty for its visitors. What the page knows of them it says with an event the class declares. - The screen is part of the call's state, public to that call's own page and to nobody else's. A page that follows a phone call draws it too, and it is still there after the call ended.
- A deployed page offers talking, writing and a code to call with. Nobody anonymous has the agent ring a number.
- An address is given six tickets a minute.
- The page is served from the release that runs. The built folder rides with the release even though
a
.gitignorenames it, and a page that is not built is refused before anything is sent.