Callbacks · Pinecall Docs

A callback is a caller who should be rung back: the agent promised it, or Pinecall could not serve the call. Pinecall writes each one down and lists them for your team; placing the call back is yours.

How it works#

Every callback is one callback.requested entry in a log, and GET /v1/callbacks collects them across the org, oldest first.

The agent promises oneA tool calls this.call.callback(...) with the number, and when and why. Every line is busyThe overflow answers the caller and takes their number. The call is lostA phone call whose worker went away mid-call is offered a callback.

Nothing marks a callback as done. The list is a record of who asked, and your team or your backend works through it.

From the agent#

agents/front-desk/agent.tsx

/** The caller wants to be called back later. Ask when suits them before you use it. */
@tool()
async callMeBack(when: string, reason: string): Promise<string> {
  const number = this.call.from;
  if (number === undefined) return "There is no number to call back. Ask the caller for one.";
  this.call.callback(number, { when, note: reason });
  return `A call back is written down for ${when}. Tell the caller.`;
}

callback(number, { when, note }) writes the number into the call's log, with the call, the channel and the contact beside it. It returns nothing, and it dials nothing.

When Pinecall writes one#

You do not write these. Pinecall does, on the agent's log:

`via`	when
`agent`	your tool called `this.call.callback`
`overflow`	every line was busy, and the overflow agent took the caller's number
`overflow`	a phone call's worker went away mid-call: the caller is told once, the call ends, and their number is offered a callback

Read the list#

From a terminal#

Terminal

pinecall callbacks

One line each, oldest first: when, the agent, the number, the channel, and how it was taken. --agent <slug> keeps one agent's. When there is another page, the last line says more: --after <cursor>.

From your backend#

GET /v1/callbacks with a key that opens calls, the same list as JSON. Pass agent to keep one agent's, and after to continue from the last page's next.

Call them back#

Your backend places each call with POST /v1/agents/{slug}/dial, or a person presses Call back on the conversation in the console's Calls. Both run the org's dial rules.

A call back is an outbound call. It needs outbound calls turned on, a phone number the agent answers at, and it passes the same rules as any dial: the do-not-call list, consent for a +1 number, the number's own hours. See Calling out.

Next steps#

Calling outPlace the call back, and the rules every dial passes. Handing a call to a personTransfer, or ask a person to join now. pinecall callbacksThe verb's reference.