Architecture and guarantees

This page is the platform as a whole, for the engineer who signs off on it: what runs where, what crosses the network, what is promised and where the edges are. To build first and read later, start with Integrate in an afternoon.

The pieces

Surfaces

Only one conversation runs at a time in an app: moving from the call to the chat ends the call, and a native call ends a conversation in the bar (which ends which).

How the audio travels

The bar loads the engine page idle at launch — no microphone, nothing dialled — and keeps a line registered, so a tap connects in about a fifth of a second when the engine is ready and under two seconds when it is not. The agent's dashboard setting (Call audio) picks the transport:

The engine connects on the first network route that works within 1.5 seconds. If WebRTC cannot be used, the call moves to the WebSocket and says why (onTransport): not_configured, unreachable, screen_channel or media — a call that answered with no audio path is caught within 8 seconds. A network drop mid-call holds the call as reconnecting for up to 30 seconds and picks it up on the same session. Voice

A native call opens its own connection from your app's process: over WebRTC when the app includes the SDK's WebRTC module, else over the WebSocket. WebRTC that cannot set the call up within 12 seconds hands it to the WebSocket inside the same call — no second ring — and the call says why (transportFallbackReason). The line must open within 15 seconds. Once the audio flows a call never changes road: on WebRTC a dropped connection gets one chance to recover, and a network that stays down ends the call — your app hears ended with failed. WebRTC or the WebSocket

A chat is a text connection the SDK opens for the conversation, with a single-use ticket.

How a conversation is admitted

1. The publishable key selects the agent. It is public by design — anyone can read it out of an app or a page — and it cannot read your data or place a phone call.
2. Allowed domains decides who may use it. A website's origin must be on the list. A native app sends no origin, so the literal entry app:// admits apps. This is why the allowlist does not protect a key shipped in an app — Privacy and security.
3. A connection ticket is minted per conversation — single-use, valid for about two minutes, not replayable — and session and ticket requests are rate-limited per key and per address.
4. The agent must be switched on and your workspace must have credit. A conversation that cannot start never starts; one already running is never cut off by these checks.

Who the customer is

identify() takes the traits your app knows — a name, a plan — and the SDK masks them on the device like everything else. They become prompt variables (Hi {name}) and the line "who you are talking to" in the agent's context.

The one exception is the identifier, the trait the agent's identity setting names: it is sent as it is, only to identify the customer, and never becomes a prompt variable. Graine stores the identifier your app sends so your team can see who each conversation was with — Call History shows it, such as Email · asha@acme.example — and the memory service only ever receives a one-way key derived from it (Identity and users).

Data handled

Masked means PAN, Aadhaar, card and account numbers, phone numbers and email addresses become [PAN], [AADHAAR], [CARD], [PHONE] and [EMAIL] before anything leaves the phone, with your own patterns added through the masking rules. A masked value stays masked everywhere after it: there is no unmasked copy to recover. Component content and tools are fetched from Graine's servers, never the phone, so a key in a request header never ships in your app; endpoints must be public https and get 8 seconds.

What the SDK never does: read the screen on its own (no screen recording, no accessibility scraping), open the microphone before a call starts, or perform an action your app did not register.

Limits

When something fails

Guarantees

• Masking runs before the network, the same way everywhere. Every SDK applies the same rules, checked against one shared set of test cases, in every script — Devanagari next to an identifier included.
• Every action request gets exactly one answer — yours, or a timeout, error or refused given on its behalf. The agent never waits forever and never claims something your app did not report.
• Screen frames are ordered. Each carries a sequence number, so a late frame never replaces a newer one, and the latest screen is sent again when the connection rejoins and when the app returns to the foreground.
• Ending ends it. Hanging up is idempotent from every path, and a page that never confirms is torn down.
• One conversation at a time, so the agent never answers twice — once aloud, once in writing.
• Your design is legible. Every text colour a design resolves to is checked for contrast, in light and dark.
• Older SDKs keep working. New fields are optional: an SDK that does not know a component look draws Cards, and one older than a design feature draws without it — a plain surface instead of windows, say.

What each SDK does today

Where next