pinecallDocs
Key concepts / Flows & events

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.

app.ts
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:

app.ts
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#

TypeScript
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:

Terminal
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.