Any other platform

Every Graine SDK is a thin host around one page Graine serves. The page does capture, playback, jitter buffering, echo suppression, the WebRTC relay and the WebSocket fallback. The host shows it in a WebView, tells it who the customer is and what is on screen, and answers when the agent asks to do something. Nothing about audio is the host's problem, and an audio fix reaches every app without a release.

1. Ask for the session

POST https://www.graine.ai/api/embed/session
Content-Type: application/json
 
{ "publishableKey": "pk_live_…" }

A 403 means the agent's Allowed domains does not list app://. A native HTTP client sends no Origin header, and that entry is what matches its absence. A 401 means the key was rejected.

2. Load the page, idle

https://www.graine.ai/embed/<webcallAgentId>?mode=voice&branding=0&embed=1&transport=<rtc|ws>&b=<pageVersion>&idle=1&pk=<publishableKey>&accent=<hex without #>

Percent-encode every value. The SDKs build this URL from a shared test fixture, so theirs is byte-for-byte the one above.

The WebView needs JavaScript and DOM storage on, inline media playback allowed, and media playback not gated on a user gesture — nothing in a 1×1 view can be tapped, so a gesture requirement is never met and the agent never makes a sound.

Give it a real box: 1×1, fully transparent, attached to the window. Not display:none, not zero height, not removed from the hierarchy. A view with no box can have its media suspended, which kills the call the moment your UI collapses.

3. Build the bridge

Into the page, evaluate:

window.postMessage(<json>, "*"); true;

The trailing true; matters on Android: evaluateJavascript otherwise logs an error for every message, because a postMessage call returns nothing it can serialise.

Out of the page, the page calls window.ReactNativeWebView.postMessage(<json string>). That object must exist before the page's own scripts run. The name is a handle, not a React Native dependency.

webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.settings.mediaPlaybackRequiresUserGesture = false
webView.addJavascriptInterface(object {
    @JavascriptInterface
    fun postMessage(json: String) {
        // Called on a WebView thread. Hop to the main thread before touching UI.
        mainHandler.post { onPageMessage(json) }
    }
}, "ReactNativeWebView")
 
webView.webChromeClient = object : WebChromeClient() {
    // Grant the microphone only, and only when the app itself holds it.
    override fun onPermissionRequest(request: PermissionRequest) {
        val wantsAudio = PermissionRequest.RESOURCE_AUDIO_CAPTURE in request.resources
        if (wantsAudio && hasRecordAudioPermission()) {
            request.grant(arrayOf(PermissionRequest.RESOURCE_AUDIO_CAPTURE))
        } else {
            request.deny()
        }
    }
}

4. The messages

Into the page

Out of the page

Ignore any type you do not recognise. New ones are added without a version bump, and a host that throws on them breaks on a page update it never shipped.

graine:quality comes from the peer connection's own statistics, so a WebSocket call has none. Every SDK reads a sample the same way: 400 ms of round trip, 80 ms of jitter or 8% loss is a poor line; 150 ms, 30 ms or 2% is good rather than excellent. Say "weak connection" when it is poor. A customer whose agent goes quiet on a train otherwise reads "listening" and concludes the agent is broken.

On a website

A web page can host the engine too: the same page, in an iframe instead of a WebView. Three things differ.

• Messages travel between windows. Send with frame.contentWindow.postMessage(message, "https://www.graine.ai"), and the page sends to its parent. Read only messages whose event.origin is https://www.graine.ai and whose event.source is the frame.
• The frame needs the microphone delegated: allow="microphone; autoplay". Keep it laid out — 1 × 1 pixels, transparent — rather than display: none.
• Your page vouches for its site. The engine's own requests carry Graine's address, not yours, so when WebRTC needs to know which site it is on the page posts graine:need-ticket to its parent. Request a ticket from your page — POST https://www.graine.ai/api/embed/ticket with { "publishableKey": "pk_live_…" }, which checks YOUR origin against Allowed domains — and answer { type: "graine:ticket", ticket, wsUrl }, or { type: "graine:ticket", ticket: null } if it failed. The Graine loader does this for you.

A complete page, with a status line and a talk button, is in Your own UI → Website.

Answering an action

The agent waits for your answer.

// in
{ "type": "graine:app-action",
  "action": { "action_id": "a1", "name": "set_tenure", "arguments": { "months": 24 } } }
 
// out — always, and only once
{ "type": "graine:app-action-result",
  "actionId": "a1", "status": "ok", "message": "Tenure set to 24 months." }

status is ok, refused or error. Say what actually happened: the agent repeats your message to the customer, so ok on a change that did not apply tells them their form is complete when it is not. An action your build does not implement is refused, with a message that says so.

The SDKs give a handler six seconds, then answer error on its behalf. For anything slower, answer immediately and report the outcome in your next graine:app-context.

Describing the screen

{ "type": "graine:app-context",
  "seq": 1735820100000,
  "availableActions": ["set_tenure", "open_setting"],
  "context": {
    "screen": "loan_offer",
    "title": "Your offer",
    "journey": { "name": "Loan", "step": 3, "of": 4 },
    "fields": [
      { "name": "tenure", "label": "Tenure", "value": "12 months", "status": "filled" },
      { "name": "pan", "label": "PAN", "value": "", "status": "empty" }
    ],
    "idle_ms": 45000
  }
}

seq must increase. Frames can overtake each other on a reconnect, and an older screen applied over a newer one leaves the agent describing somewhere the customer has left.

status (empty, filled, invalid, pending, locked, plus error) is what turns proactive help from "need a hand?" into "the PAN isn't being accepted".

availableActions may only narrow what the dashboard declared. An action invented here is not callable.

Mask before you send. The SDKs replace PAN, Aadhaar, card, phone and email patterns in every value that leaves the device — screen, variables and events — with [PAN], [AADHAAR], [CARD], [PHONE] and [EMAIL]. A host of your own has to do the same.

Before you ship

• Send graine:end-call before destroying the view. Tearing down the WebView drops the socket unclosed, which files as a lost connection rather than a hang-up.
• End the call when the app goes to the background. A backgrounded WebView can keep the microphone open and the call billing with nobody listening.
• Declare every action in the dashboard under Agent → Embed & Widgets. A handler with no declaration is never offered to the model.
• Add app:// to the agent's allowed domains.

Next steps