A conversation, end to end

Before anyone speaks: the data

The customer, Rohan, is on your app's appointments screen. Your app has already told the agent who he is, what he has booked and where he is:

identify({ customer_name: "Rohan" });
setVariables({ open_bookings: 1, appointment_id: "apt_3301", appointment_date: "15 October" });
useGraineScreen({ screen: "my_appointments", title: "Your appointments" });

The Android, iOS and Flutter SDKs take the same values through identify, setVariables and setScreen. When the conversation connects, these become the conversation's data: the flow fills {customer_name} from it, and rules read the same values as recipient_data.customer_name and recipient_data.open_bookings. Values travel as text, so 1 arrives as "1"; a rule still compares it as a number. The flow's own defaults fill only what is still missing — here, business_name.

On a phone call the same data comes from a campaign's columns or the variables of POST /v2/calls, and there is no screen. Variables in text

The conversation connects: the welcome message

Rohan taps the bar. The conversation opens, following the same flow as the agent's phone calls, and the welcome message plays at once: "Hi Rohan, this is Asha from Acme." It is not a step, and nothing in the flow has run yet. In a chat it arrives as text.

On a phone call it plays when the call connects. Give every variable in the welcome message a default: on a phone call it is prepared before the call connects. When the call connects

Turn 1: three steps in one turn

Rohan: "Hi — I can't make it on the 15th. Can we move my appointment?"

1. The first step runs now, on his first words. confirm has two AI-decided paths, so the decision model reads their conditions and the conversation, and picks "The customer wants to move their appointment".
2. The branch decides in the same turn. has_booking says nothing: its rule holds ("1" is above 0), so the call moves on to pick_time. With no booking, the Always path would have taken it to the fixed line no_booking instead.
3. The step the call is now on replies. Rohan hears pick_time; confirm never speaks, because his first words already answered it.

The first turn · Which path the call takes

Still turn 1: a component on screen

pick_time's instructions tell the AI to show the open times. The component is a tool the AI calls by its name, offer_appointment_times: it says one is coming, the SDK draws your loader, and the calendar slots appear on Rohan's screen in your brand's design — fetched from your API at that moment if the component has an endpoint. The AI says: "I've put the next three dates on your screen — which suits you?"

The AI reply step also knows which screen Rohan is on and which component is open, and could call your in-app actions. Which tools it calls on a step it decides itself; only Uses a tool forces one.

On a phone call there is no screen and no component: write the step's instructions so they also work by voice ("…or read out two dates if they cannot see a screen"), or give each surface its own agent. On your website and in your app

Turn 2: the tap is a turn

Rohan taps Fri 17 Oct, 10:00. Three things happen:

• The choice reaches the agent as Rohan's next turn — "Friday 17 October at 10:00 works" — and the structured answer goes to your webhook.
• The component's When they tap → Open a screen runs your open_screen handler with appointments?time=…, and your app reports the screen it lands on.
• pick_time's paths are checked: the decision model takes "The customer has chosen a time" and collects new_time from the conversation. From now on, text can say {new_time} and rules can test new_time.

The call moves to book, which uses a tool: on arriving it must call move_appointment, so your server receives the booking and the new time, and the AI speaks from what your server answered: "Done — you're booked for Friday 17 October at 10:00. It's on your appointments screen." Had new_time been missing, the step would have replied without calling the tool: its instructions use {new_time}, and the tool requires it.

Collecting values on the way · Make a step use a tool · When they tap

Turn 3: the goodbye ends it

Rohan: "Great, thanks." book has one path, Always, so the call moves to goodbye, which uses End the call: the AI says goodbye and the conversation hangs up once the goodbye has played. In your app the SDK reports the end of the conversation, as it does for any ending.

A step with no paths would not have ended anything: the call stays on it until the agent's call settings, in Settings › On the call, end it. How a call ends

Afterwards: what it leaves