Scheduled calls

"Call me back tomorrow at six." A scheduled call is a call booked for later and rung when it falls due — in your app through hosted ringing, or on the phone for a caller who booked it on a phone call. Three ways to book, one set of rules:

An in-app call rings the customer's devices through hosted ringing, so it needs your push credentials uploaded, and an app on iOS, Android or Flutter 0.7.0 or React Native 0.41.0 (calls 0.2.0) — the versions with scheduleCall and hosted ringing. A callback the agent books on a phone call is an ordinary scheduled phone call to the caller's number.

How it works

Set it up

Agent → Calls & scheduling — also on Embed & Widgets → Calls.

Who may book a call

How it rings

Save call settings saves both.

The agent's calling window applies to every scheduled call, in the customer's time zone, which your app's SDK reports.

In-app call audio

In-app call audio shows once the agent is set up for your app or website, and is saved the moment you change it. Apps pick up the change the next time they start.

Booking

By the agent

With The agent, during a conversation on, the agent can book a call back when a customer asks for one. It is told the current time where the customer is, books a time with its offset, and hears back the confirmed time — or why it could not book — in plain words, which it passes on: "Done — I'll call you tomorrow at 6 pm."

In your app, the call is for the signed-in customer when this device is one of theirs (Identity and users), otherwise for this install. On a phone call, it is for the caller's number.

Say in the prompt when the agent should offer a call back, and what to say about it. It can only book within your rules.

From your app

With Users, from your app on:

const client = useGraineClient();
const call = await client.scheduleCall({ at: "2026-10-14T18:00:00+05:30", reason: "Talk through my order" });
const upcoming = await client.scheduledCalls();      // this customer's, or this install's
await client.cancelScheduledCall(call.id);

What each method returns and every error it can raise is on the SDK reference → Scheduling; schedulingRules tells your booking screen which times will be accepted before you ask. A time the customer chooses is checked against the calling window when it is booked, and refused outside it with a message you can show; quiet hours do not apply to it — they asked. reason is up to 120 characters; it reaches the agent when the call connects and never travels in the push.

From the dashboard

Agent → Calls & scheduling → Scheduled calls lists every booked call with its status, and Schedule a call books one: for an in-app customer by their identifier, or for a phone number. Listing needs a role that can view calls; booking and cancelling, one that can place calls.

What every booking must pass

• no sooner than With at least this much notice, and no further ahead than Booked at most this far ahead;
• no more than At most this many upcoming calls per user already booked for them;
• your workspace has credit and the agent is on;
• at most 10 bookings an hour from one install, within your workspace's own limit.

What happens at the time

1. Credit and the agent. With no credit, or the agent switched off, the call is held — still scheduled — for up to 10 minutes, and expires after that.
2. Not stale. A call more than 10 minutes past its time expires instead of ringing late.
3. The customer's hours. The calling window, in the customer's time zone, and quiet hours for a call the agent or your team booked. Outside them, the call moves to the next opening if that is still within Booked at most this far ahead, and expires if not. If the time zone cannot be read, the call does not ring.
4. How often. No ring within 6 hours of the customer declining one, and no more than Ring each user at most allows.
5. A device. The customer's devices seen in the last 30 days, newest first — or the one install it was booked for. None: no_device.
6. Ring. The newest device rings for Ring for; a dead device is skipped for the next one. Unanswered, the call is missed, and rings once more after After a missed call, ring once more after, if you set one.

When the customer answers, the agent hears who_called as scheduled and the call's reason as call_reason, with the variables the booking carried.

Statuses

Your webhooks get call_declined, call_missed and call_expired beside the call's own events, and every rung call is in Call History.

Errors

Troubleshooting

Where next