Flows & events
What your app does after the call ended: a reminder a day later, a second try, a follow-up. A function that survives a deploy.
A flow is what your app does after the call ended: a reminder the day before a visit, a second try when nobody answered, a follow-up when the lab results are in. It is a function you write, and it survives a deploy, a crash and a weekend with nothing running.
What is a flow?#
A function of what started it and its steps. Each step is something that takes time or must happen once.
import { flow } from "@pinecall/agents";
const remindVisit = flow("remind-visit", async (visit, step) => {
await step.sleepUntil(visit.at, { before: "24h" });
let called = await step.call(visit.phone, Reminder, {
instruction: `Remind ${visit.patient} of the visit tomorrow at ${visit.time}.`,
});
if (!called.answered) {
await step.sleep("2h");
called = await step.call(visit.phone, Reminder);
}
await step.run(() => db.visits.update(visit.id, { reminded: called.answered }));
});
app.on("visit.booked", remindVisit);
app.on("visit.booked", remindVisit) starts a run of the flow each time an agent logs
visit.booked, with what it logged as the input. The front desk books the visit on a Monday call;
the reminder is made on Thursday, by another agent, on another call.
The flow in its app#
A flow lives in app.ts, beside the lines and the rules: the file pinecall start serves the
project's agents with. The whole file, with the agent that answers the number, the one that makes
the reminder, and the flow between them:
import { flow, voiceApp } from "@pinecall/agents";
import FrontDesk from "./agents/front-desk/agent";
import Reminder from "./agents/reminder/agent";
import { db } from "./lib/db";
const app = voiceApp("brightside-dental", { timezone: "America/Los_Angeles" });
app.line("+1 415 555 0134", {
greeting: "Brightside Dental. How can I help?",
answers: FrontDesk,
});
app.rule("Never say an amount of money that a tool did not give you.");
const remindVisit = flow("remind-visit", async (visit, step) => {
await step.sleepUntil(String(visit.at), { before: "24h" });
let called = await step.call(String(visit.phone), Reminder, {
instruction: `Remind ${visit.patient} of the visit tomorrow at ${visit.time}.`,
});
if (!called.answered) {
await step.sleep("2h");
called = await step.call(String(visit.phone), Reminder);
}
await step.run(() => db.visits.update(String(visit.id), { reminded: called.answered }));
}).cancelOn("visit.cancelled", (gone, visit) => gone.id === visit.id);
app.on("visit.booked", remindVisit);
export default app;
The front desk starts it from one of its tools, on the call where the visit is booked:
this.log("visit.booked", { id, at, phone, patient, time }). What it logs is the flow's input.
Who runs it#
Your function runs in your process, the one pinecall start or pinecall deploy runs. Pinecall
keeps the run: every step it reached, what each came to, and what it is waiting for. When the time
comes, or the call ends, or the event arrives, Pinecall hands the run back to your process and the
function goes on.
| where it lives | |
|---|---|
| the function, your database, your code | your process |
| the run's journal, the clock, the call it placed, the events it waits for | Pinecall |
So nothing is lost when your process restarts. A run that was due while nothing was running goes on when something is.
The steps#
| step | what it does |
|---|---|
step.sleep("2h") |
waits: a number and s, m, h or d |
step.sleepUntil(at, { before: "24h" }) |
waits until a time, or that long before it |
step.call(number, Agent, { instruction, greeting, state }) |
the agent calls the number and the step answers how the call ended |
step.text(number, Agent, "Your cleaning is tomorrow at 9:30.") |
the agent sends the contact one SMS, from a number it answers SMS at, and the step answers at once |
step.waitFor("lab.ready", { match: { patient }, within: "7d" }) |
waits for an event sent to the app; null when it gave up |
step.run(() => …) |
runs your own code once and keeps what it returned |
step.emit("visit.reminded", { id }) |
sends an event to the app |
step.call answers { answered, reason, call }. answered is false when nobody picked up, the
line was busy or the dial failed. A call your org's calling rules refused (the hour, the number of
calls a day to one person) rings nobody and answers at once with { answered: false, refused, message },
so the flow reads why and decides.
step.text answers { sent, call, from }: the conversation the words were said on, where what the
contact answers reaches the agent with those words before it (SMS).
A text the same rules refused, a contact who texted STOP, or an agent nobody is running answers
{ sent: false, refused, message }. In Python it is await step.text(number, Agent, words), in Ruby
step.text(number, Agent, words).
Each time a run goes on, its function is called again from the top, and every step it already reached answers what it came to without doing it again. So what must happen once goes inside
step.run: a write to your database, a text message. Code outside a step runs again on every wake.
Cancelling#
const remindVisit = flow("remind-visit", async (visit, step) => {
// …
}).cancelOn("visit.cancelled", (gone, visit) => gone.id === visit.id);
cancelOn(event, when) cancels the runs still waiting when that event comes and when is true
for the run's input. The patient cancels the visit on Tuesday: Thursday's reminder is never made.
Events from your own systems#
An agent starts a flow by logging a line. Your backend starts one, or wakes one that is waiting, by sending the app an event:
curl -X POST https://cloud.pinecall.io/v1/apps/brightside-dental/events \
-H "Authorization: Bearer $PINECALL_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "lab.ready", "data": {"patient": "p-1"}}'
{"id": 4127}
The event reaches app.on("lab.ready", …), a function or a flow, and wakes a step.waitFor("lab.ready")
whose match it carries. Pinecall keeps it until your process heard it: an event sent while nothing
is running is heard when something is.
What to know#
- A flow's name is how its runs are kept. Rename it and the runs of the old name wait for a flow that is gone.
- The function reaches its steps in the same order every time. A run whose function asks for another step than the one it reached before is failed, saying which: change a flow's steps when no run of it is waiting.
- A step your code runs (
step.run) finishes within a minute. - A run sleeps or waits 90 days at most. An org has 10,000 runs waiting at most.
- What starts a run or rides an event is 16 KB of JSON at most: an id and a few facts, not a document.
- A line an agent logs starts a flow and cancels one. Only an event sent to the app wakes a
waitFor.