Integration guide: apps and website

This guide takes your team from nothing to a launched agent in your app and on your website — talking, chatting, seeing the screen, acting on it, remembering each user, booking calls and calling them like WhatsApp — with no meeting. It is written for release 0.10.1, and every part links to the page that covers it in depth.

Start here — no meeting needed

Everything your engineers need is in this guide, the SDK references and the demo apps. Read in the order below; if anything blocks you, write to us (at the end of this section) and we answer by email.

What you receive

The versions

The iOS pod (pod 'GraineInApp', '~> 0.10') builds the same sources. The source of every native SDK is public: github.com/GraineAI.

The order to read

1. This section, then What you build and How it works.
2. Set up everything from scratch — the dashboard, in order, with screenshots.
3. Install and initialise on your platform.
4. The use cases you need — each with the exact code on every platform, the dashboard settings it needs and a troubleshooting table.
5. Your platform's SDK reference, as you code.
6. The QA script and the go-live checklist.

A first success in 30 minutes

1. An agent. Create one in the dashboard (or clone yours), and try it there.
2. Its key and your app. Agent → Embed & Widgets → Set up embedding → Install: copy the pk_live_… key, and add app:// (and your website hosts) to Allowed domains.
3. The SDK — install and initialise: configure it once at launch with the key, and put the bar on screen.
4. Open the bar. The launcher appears in your design; tap it and the agent greets you. Nothing appears? app:// is missing or the key is wrong — Troubleshooting.

WhatsApp-style calls end to end: a checklist

• iOS: Push Notifications, Background Modes Audio and Voice over IP, the microphone string; enableVoIPPushes() at every launch.
• Android: Firebase in the app — the SDK registers for pushes itself (an app with its own messaging service forwards the token and every message to the SDK); notifications asked for on Android 13+.
• Workspace settings → In-app calling: the APNs key and the Firebase service account, Checked and working. — create your credentials.
• Agent → Calls & scheduling: Name on the incoming call, who may book, the limits, quiet hours; the agent's Calling Window.
• identify() after sign-in, with the identifier Who is the user? names.
• The user calls the agent: startCall(reason:) — how.
• The agent calls the user: book one (the agent, the booking sheet, or your team), or test with Ring now — how.
• The prompt handles who_called (customer, scheduled, agent) and call_reason.
• Optional: calls over WebRTC — the module in the build (iOS, Android) or the build switch (React Native, Flutter); the agent's In-app call audio on WebRTC (recommended) — how.

What's new

0.10.1 (React Native 0.44.1, calls 0.5.1):

• On Android the SDK registers for pushes itself. Add Firebase to the app (google-services.json, its Gradle plugin and the messaging library) and the SDK's own messaging service rings every call push and receives every new token — no messaging service to write. An app that has its own FirebaseMessagingService keeps handing Graine's pushes and tokens over (handlePush, onNewToken). Changelog.

0.10.0 (React Native 0.44.0, calls 0.5.0):

• The SDK asks for call permissions. requestCallPermissions() asks for the microphone, notifications (Android 13+) and the full-screen ring (Android 14+); callPermissions reads each one and openCallSettings() opens the page to change it. Permissions.
• A setup check. callSetupProblems lists what is still missing for calls to ring — a capability, the microphone sentence, a push token, a permission, push credentials not uploaded — each with the exact fix.
• React Native: an Expo plugin adds the microphone sentence, the background modes and the push entitlement; webrtc: true turns on WebRTC calls.

0.9.0 (React Native 0.43.0, calls 0.4.0):

• Calls over WebRTC, in both directions. Add the SDK's WebRTC module — iOS GraineInAppRTC, Android ai.graine:inapp-android-rtc, a build switch in React Native and Flutter, each platform's module in Kotlin Multiplatform — and the calls the user places and the calls Graine rings carry their audio over WebRTC: steadier on a weak network, prepared while the ring shows. A call WebRTC cannot set up continues on the WebSocket inside the same call. callTransport chooses, transport says which one ran, and the agent's In-app call audio setting can keep every call on the WebSocket. Calls over WebRTC.
• The same features on every SDK: emptying the chat on screen (clear, clearChat), a chat that says it is reconnecting or gave up, the voice captions switch, the rows a chat window draws for a chat of your own, answering a component from your own UI, the brand's design tokens and the merged prompt variables in Kotlin Multiplatform. Changelog.
• Variables over 1 KB are trimmed to fit, the biggest left off first, instead of none travelling. Variables.

0.8.0:

• The SDK's own booking sheet on every platform: presentBooking (iOS, Android, Kotlin Multiplatform), GraineBooking.show (Flutter), openBooking and <GraineBookingSheet> (React Native), GraineAgent.openBooking (website), with bookingAvailable to show your own Call me button only when booking works — and Book a call in each SDK's chat window. Booking with the SDK's sheet.
• Calls that cannot connect say so, quickly. iOS: one 20-second deadline before the conversation opens, and a clear end when the phone never gives the call its audio; Android: a dead connection ends after 50 seconds of silence, and a slow network never freezes a call. A call starts at once on the agent's settings already on the device. The messages.
• Variables travel only on the signed ticket for chats and calls. Variables.
• In-app call audio — the dashboard setting for how calls' audio travels, ready for the WebRTC calls that 0.9.0 brings.

Questions

Email support@graine.ai with your workspace name, the platform and SDK version, what you did, what you expected and what happened — a screenshot or the error code helps. We answer by email. Never email keys or credential files: push credentials are uploaded in Workspace settings → In-app calling.

What you build

No server of yours is needed for any of it: your app and your site use a publishable key and the SDKs, and Graine rings, schedules and remembers.

How it works

The whole platform, in an engineer's terms — transports, admission, data, limits, failure modes: Architecture and guarantees.

Before you start

Set up everything from scratch

The dashboard, in the order that works: the agent; Embed & Widgets → the publishable key and Allowed domains (with app://); Agent → Memory → Who is the user?; Calls & scheduling — Users, from your app, the calling window, In-app call audio; Workspace settings → In-app calling — the APNs key and the Firebase service account; the design in the Garage; the demo's agent packs; a test with the demo apps. Step by step, with screenshots: Set up everything from scratch.

Install and initialise

npm install @graineai/inapp-react-native@0.44.1 react-native-webview @graineai/inapp-react-native-calls@0.5.1
npx expo install expo-font react-native-svg
cd ios && pod install

const [open, setOpen] = useState(false);
 
<GraineProvider baseUrl="https://www.graine.ai" publishableKey="pk_live_…" navigationRef={navigationRef}
                autoConnect={false} loadFont={Font.loadAsync} svg={{ Svg, Path }}>
  <NavigationContainer ref={navigationRef}><RootNavigator /></NavigationContainer>
  <GraineVoiceLauncher webView={WebView} active={open} autoStart>
    {(api) => (open ? <GraineVoiceBar api={api} onClose={() => setOpen(false)} /> : null)}
  </GraineVoiceLauncher>
  {!open && <GraineLauncherButton onPress={() => setOpen(true)} style={{ position: "absolute", right: 16, bottom: 24 }} />}
  <CallsBridge />
</GraineProvider>

When it works: the launcher appears in your design; open it and the agent greets you. Nothing appears? app:// or your domain is missing from Allowed domains, or the key is wrong — Troubleshooting.

Use cases by SDK

Every use case, with the exact code on every platform — the functions to call in order, what they read or set and what to expect at each step, from setting up to cleaning up — plus the dashboard settings it needs and a troubleshooting table:

The same rows against every platform, each cell opening that platform's code: Use cases by SDK.

Identity and memory

Pass the signed-in user with the identifier your Who is the user? setting names — user_id by default, or email, phone, or a field of your own such as customer_id — and whether they allow memory. Sign-out is identify(null).

• The identifier is never a prompt variable. Graine stores the identifier your app sends so your team can see who each conversation was with — Call History shows User ID · u_8812 — and the memory service only ever receives a one-way key derived from it. Every other trait (name) is masked on the device and becomes a prompt variable.
• With the same field and value on your app and your website, they are one user: memory and scheduled calls follow them. A phone caller is the same user only when the field is Phone number.
• No identifier, a placeholder such as guest, or a device past the user's limit means no memory for that conversation — never a shared one.
• Conversations continue. For an identified user with memory on, Graine keeps their last 50 messages with each agent, for 7 days after the latest. When they come back, the chat opens on the conversation — the earlier messages, a voice call as one row, a date line where the day changes — and the agent picks up where it left off; a new call still opens with a greeting, and the agent knows what was said. newConversation() — or New conversation in the chat's header — starts a fresh thread and keeps the memories; a successful forgetMemory() deletes both.

The code on every platform: Identify the user · the rules: Identity and users · Memory.

Variables

What your app can tell the agent — traits from identify, variables at start-up and while the app runs, a call's reason — reaches the prompt's placeholders ({name}, {plan}, {call_reason}). Chats and calls carry them in the signed ticket that opens the conversation: 12 variables, 200 characters each, about 1 KB in all (on a call, who_called and call_reason first; past 1 KB the SDKs leave off the biggest values first); a call over WebRTC carries the same set; the voice bar's WebRTC audio allows 40 of 300 characters, then drops the biggest values first. Keys starting with graine_ are Graine's own and never reach the agent from an app. In full, with what happens when a set is too big: Variables.

Chat, voice and components

What a user gets is the dashboard's What visitors get: the call, the chat, or both with a switch. One conversation runs at a time.

• Voice — the microphone is declared by your app and asked for when a call starts (the voice bar).
• Chat — typed, with the same screen context, actions and components, at the Garage's Window size — Compact, Large or Full screen — or the size your code asks for (chat).
• Components — lists, plans, slots and choices drawn in your design; a tap is the user's next turn (components).
• Several agents — a support agent in Help, a sales agent on Plans: each its own key, design, chat and actions; who the user is, shared (several agents).

Calls like WhatsApp

Two directions, one call engine in your app. The user calls the agent from a button — startCall(reason:), and the agent hears who_called = customer (how). The agent calls the user: Graine rings their phone when a booked call is due, through your push credentials, and the agent hears who_called = scheduled with the booking's reason (how). Both directions carry their audio over WebRTC when your app includes the SDK's WebRTC module — steadier on a weak network — and over the WebSocket otherwise (how).

What your users see

When a call cannot connect

A call that cannot connect ends failed, with a message in its outcome and on the call screen:

With the WebRTC module, a call first has up to 12 seconds to connect over WebRTC; one that cannot does not end — it continues on the WebSocket inside the same call, and these messages are what is left when neither can connect.

A call starts at once on the agent's settings the SDK already has — this launch's, or the ones kept on the device — and refreshes them behind the call. On Android a slow network never freezes a call: at most 300 ms of the user's speech waits, the oldest dropped first, and hanging up lets go of the microphone at once.

The call screen's look, words and controls are the Garage's Call tab; the setup per platform is In-app calling and Permissions.

Scheduled calls and the booking sheet

A scheduled call is for a user — the one your Who is the user? field identifies — and rings that user's newest app device, in their time zone, within the agent's Calling Window and outside quiet hours.

There is no repeating schedule: for a daily check-in, the agent offers and books the next call at the end of each conversation, or the user books from the sheet.

The booking sheet is the SDK's own "Call me at…": the day, the time, the phone's time zone, what it is about and Book call, in your agent's design, with every refusal in plain words. Offer it where bookingAvailable is true — Graine rings this phone, the agent lets users book, and the user is identified; on a website only the last two count, and the sheet says "We'll ring you in the app". It returns the booked call, or nothing when the user closed it. Booking with the SDK's sheet · the scheduled-calls list.

Design

One design, chosen in the Garage, drawn everywhere: the launcher, the bar, the chat window, components, the booking sheet and the call screen, on your website and in every SDK. A saved change reaches a website on its next page load and an app the next time it starts. Nothing in your code names a colour or a font. Design in the Garage.

Data and privacy

Privacy and security · Architecture and guarantees

Error codes

Each SDK raises these as a typed error with a code and a message — which method raises which is on your platform's SDK reference, and every code with its fix on Errors.

Troubleshooting

QA script

Run it on an iPhone, two Android phones and your website, signed in as a test user whose identifier you know.

Go-live checklist

Dashboard

• An agent per surface; keys in the builds; app:// and every site, staging included, in Allowed domains
• The design saved on all three Garage surfaces; Setup saved
• Actions declared and saved; components ticked; friction tuned
• Memory → Settings: the same Who is the user? field on the app's and the website's agents
• Calls & scheduling: call name, quiet hours, who may book, limits; the agent's Calling Window
• In-app calling credentials Checked and working. on both platforms
• The prompt handles who_called and call_reason, and offers call-backs when it should

Apps

• The microphone declared on every platform; requestCallPermissions() at onboarding (the microphone, and notifications on Android 13+)
• iOS: Push Notifications, Background Modes Audio and Voice over IP; enableVoIPPushes at every launch
• Android: Firebase in the app — the SDK registers for pushes itself (an app with its own messaging service forwards the token and every message, handlePush first)
• identify() after sign-in and at every launch once your sign-in is restored; identify(null) on sign-out
• Call me buttons shown only where bookingAvailable is true
• Store submissions: Play's foreground-service and full-screen-intent declarations, App Store review notes, no development launcher (Expo: expo-dev-client) in the store build — Permissions → Store review
• Calls over WebRTC — the module or build switch in the release build, WebRTC in your open-source licences
• Debug logging off in release builds

Website

• The snippet on every page the agent belongs on; identify() on sign-in

Tested

• The QA script above, on every platform

The fuller list, with what each failure means: Going live.