Voice

The agent is a conversation. Text is the fallback.

The short way

import { WebView } from "react-native-webview";
import { GraineProvider, GraineVoiceLauncher, GraineAgentBar } from "@graineai/inapp-react-native";
 
<GraineProvider
  publishableKey="pk_live_…"
  navigationRef={navigationRef}
  autoConnect={false}
>
  <GraineVoiceLauncher
    webView={WebView}
    autoStart
    onError={(m) => console.warn("[graine]", m)}
  >
    {() => <GraineAgentBar />}
  </GraineVoiceLauncher>
</GraineProvider>

That is the whole voice integration. react-native-webview autolinks; there is no native initialisation, no MainApplication.kt edit, no AppDelegate.swift edit, no ProGuard rule, no babel plugin ordering.

Why a WebView

React Native has no getUserMedia. Every route to a microphone is a native module — and a native module means an app-store release for every fix.

The audio path is where nearly every fix lands. Decoding, jitter buffering, echo suppression, the mute latch: all of it changed in the last month. Through a WebView those ship over the air, because the microphone and speaker run inside the same hosted page the web widget uses, which already does capture, playback, buffering, mu-law decoding and echo suppression.

The customer never sees it. It is one pixel, invisible, unreachable — laid out at 1×1 rather than hidden, because a view with no box can have its media suspended by the platform, and that would kill the call the moment the bar collapses.

Controlling the call

The child function receives the controls, so your own UI can drive it:

<GraineVoiceLauncher webView={WebView}>
  {({ connected, connecting, muted, start, end, setMuted }) => (
    <MyBar
      status={connecting ? "connecting" : connected ? "live" : "idle"}
      onCall={() => (connected ? end() : start())}
      onMute={() => setMuted(!muted)}
      muted={muted}
    />
  )}
</GraineVoiceLauncher>

onCaption gives you each line as it is said, if you draw your own captions.

Captions, and the CC button

The launcher keeps the transcript. A caption box is a map, and the CC switch is api.captionsOn — you do not accumulate anything yourself. 0.28.0.

<GraineVoiceLauncher webView={WebView} active={open} autoStart>
  {(api) => (
    <>
      {api.captionsOn && api.captions.slice(-3).map((c, i) => (
        <Text key={i} style={{ opacity: c.live ? 0.7 : 1 }}>
          {c.role === "agent" ? "Agent" : "You"}: {c.text}
        </Text>
      ))}
      <Button title="CC" onPress={() => api.setCaptionsOn(!api.captionsOn)} />
    </>
  )}
</GraineVoiceLauncher>

A turn arrives many times as its words come in — each with fuller text and live: true — then once settled with live: false. The launcher folds those into one entry, so captions holds turns rather than keystrokes. Render live ones faded if you want; they are the same line about to be finished.

onCaption still fires for every line and is unchanged — it is a convenience on top of captions now, rather than the only way to see them.

Hanging up

Two paths, both idempotent, so a host that uses one, the other, or both ends exactly one call:

• api.end() — your own close or hang-up button.
• active={false} — your UI closing. Since 0.28.0 this posts the stop frame unconditionally. It used to be guarded on the launcher's own belief about whether a call was running, and those flags are cleared by the page's own frame — so a close that raced it dismissed the UI and left the call up.

Deactivating also clears connected / connecting and the transcript, so a reopened launcher never shows a call that has ended.

Microphone permission

The SDK never asks. When to ask is a product decision, and a permission dialog appearing from inside an SDK at a moment the customer does not expect is the fastest way to be denied permanently.

Declare it, ask at a sensible moment in your flow, then start the call.

<!-- Android -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<!-- iOS Info.plist -->
<key>NSMicrophoneUsageDescription</key>
<string>Used to talk to the in-app assistant.</string>

Interruption

Handled for you. When the customer talks over the agent, the agent stops and whatever it had queued is discarded rather than played out behind them.

A customer who interrupts and then hears the agent finish the sentence anyway concludes it is not listening — and they are right.

The SDK also keeps the agent from hearing itself. On a phone the speaker is two inches from the microphone, so a large part of what it hears while the agent talks is the agent; sent upstream, the transcriber writes those words down as the customer's and the agent interrupts itself after a word or two. The guard measures the echo on the device rather than assuming a level, and holds ~240ms of audio back so a real interruption is not clipped at the start.

Voice and screen context together

This is the combination worth building for. The customer says "why was this rejected?" without naming a field, and the agent already knows which screen they are on and which field is red — so it answers about that one.

Nothing extra is required. Add screen context and it applies to voice conversations automatically.

Bringing your own audio

If you already ship a native audio module and would rather use it than a WebView, the adapter path is still there. It is more work and it cannot be updated over the air, so reach for it only when you have a reason.

import { useGraineVoice, liveAudioStreamAdapter } from "@graineai/inapp-react-native";
import LiveAudioStream from "react-native-live-audio-stream";
 
const adapter = liveAudioStreamAdapter(LiveAudioStream, myPcmPlayer);
const { listening, start, stop } = useGraineVoice(adapter);

This path needs voice on the provider, since the SDK's own socket carries the audio:

<GraineProvider baseUrl="…" publishableKey="pk_live_…" voice>

The boundary is four methods:

interface AudioAdapter {
  startCapture(onChunk: (base64: string) => void): void | Promise<void>;
  stopCapture(): void | Promise<void>;
  play(pcm16: Int16Array, sampleRate: number): void;
  clear(): void;             // the customer interrupted — drop what is queued
  bufferedSeconds?(): number; // lets marks be acked at playout, not on arrival
}

Capture at 16 kHz, mono, PCM16. Ask your native module for exactly that.

Do not resample in JavaScript: resampling every chunk on the audio path is how a mid-range Android starts dropping frames and the agent starts hearing every third word. And read MIN_PLAYOUT_BUFFER_SECONDS before writing the player — a cushion enforced as a hard gate strands the end of every reply and eventually stops the conversation.

How the audio travels

Two transports, one integration. GraineVoiceLauncher takes a transport prop, and if you omit it the agent's dashboard setting decides — Agent → Embed & Widgets → Call audio — so this can change for every app running your build without shipping a release.

Screen context, actions and events work identically on both. On rtc they travel on a separate control channel that the runtime joins to the media call, so the agent sees exactly what it sees on ws.

When rtc cannot be used

It falls back to ws rather than failing, and tells you through onTransport:

onTransport={({ transport, requested, reason, message }) => {
  if (transport !== requested) console.warn(`[graine] ${reason}: ${message}`);
}}

Diagnosing not_configured

The call still works, so nothing is on fire — but WebRTC will never be used until this is fixed. Ask the endpoint directly, without rebuilding anything:

curl -i -X POST https://www.graine.ai/api/embed/rtc-session \
  -H 'Content-Type: application/json' \
  -d '{"publishableKey":"pk_live_YOUR_KEY"}'

That curl sends no Origin header, exactly as a native app does — so a 403 from it is precisely the 403 your app is getting.

Next steps