# React Native SDK: the AI waiter in your React Native or Expo app

> Add Tamr's AI waiter to a React Native or Expo app with @tamr/waiter-react-native: install, the waiter host, signed-in diners, cart lines, voice notes and debug mode.

Source: https://tamr.link/docs/sdks/react-native

`@tamr/waiter-react-native` shows the waiter in a React Native or Expo app: in a full-screen panel at the root of your app, in a modal, or inline. It is written in TypeScript, with no dependencies beyond `react-native-webview`.

## Requirements

React Native 0.76 or later (Expo SDK 52 or later) and `react-native-webview` 13.12 to 14.x, on iOS 16+ and Android API 26+.

## Install

```sh
npx expo install @tamr/waiter-react-native react-native-webview expo-web-browser   # Expo
npm install @tamr/waiter-react-native react-native-webview                          # bare React Native
```

Bare React Native also runs `cd ios && pod install`. With Expo, use a development build (`npx expo run:ios`, `npx expo run:android`), not Expo Go, which can't add the microphone's permission text.

`expo-web-browser` is optional and gives the better checkout: with it, a payment's page opens in an in-app browser and the diner stays in your app. Without it, the page opens in the system browser.

List your app's bundle id and package name on the app key. With `expo-application` installed, the SDK sends the app's id; a key used from an app it doesn't list is logged, never refused.

## Open the waiter

Create one waiter, render one `TamrWaiterHost` at the root of your app after your screens, preload it where the waiter is likely to be opened, and open it on a tap:

```tsx
import { useEffect, useState } from "react";
import { Button } from "react-native";
import { SafeAreaProvider, useSafeAreaInsets } from "react-native-safe-area-context";
import { createWaiter, TamrWaiterHost, type Waiter } from "@tamr/waiter-react-native";

const waiter = createWaiter({
  key: "tamr_pk_test_…",
  restaurant: "your-restaurant",
  locale: "ar", // optional: branch, appearance, table, tableScan, mode, launch, debug, onLog
});

// Who the diner is, asked whenever the page needs a fresh token. Return null for "no one".
waiter.setIdentityProvider(async () => {
  const token = await myBackend.tamrToken(); // your backend signs it
  return token ? { token } : null;
});

// Orders go to your own cart ("Orders go to: the app's cart"): answer each line.
waiter.onCartAdd(async (change) => ({
  ok: true,
  lines: change.lines.map((line) => ({ lineId: line.lineId, ok: true })),
}));

// Everything the page tells you.
waiter.on("payment.completed", (paid) => console.log("paid", paid.paymentId));

export function App() {
  return (
    <SafeAreaProvider>
      <Root />
    </SafeAreaProvider>
  );
}

function Root() {
  return (
    <>
      <Navigator />
            <TamrWaiterHost waiter={waiter} insets={useSafeAreaInsets()} />
    </>
  );
}

function MenuScreen() {
  useEffect(() => waiter.preload(), []);
  return <Button title="Ask the waiter" onPress={waiter.open} />;
}
```

Call `waiter.dispose()` when the diner signs out, and create a new one for the next diner. One waiter is rendered in one place at a time.

### A sheet or an inline view instead

```tsx
<TamrWaiterSheet waiter={waiter} insets={useSafeAreaInsets()} /> // shown while open(), a Close bar on top
<TamrWaiterSheet waiter={waiter} presentation="fullScreen" insets={useSafeAreaInsets()} />
<TamrWaiterView waiter={waiter} style={{ flex: 1 }} />    // inline, shown while mounted
```

A sheet and an inline view load the chat each time they appear; the host loads it once and keeps it. A full-screen sheet has no Close bar, so create the waiter with `appearance: { showBack: true }` and the page's back arrow closes it.

## Who the diner is

`setIdentityProvider(fn)`: `fn(reason)` returns `{ token }`, `{ code }` or `null`, within 15 seconds. See [Diner identity](https://tamr.link/docs/guides/diner-identity).

## Voice notes

Optional: without them the waiter works by text. With Expo, add the plugin to `app.json` and rebuild:

```json
{
  "expo": {
    "plugins": [
      ["@tamr/waiter-react-native", { "microphonePermission": "Talk to the waiter with your voice." }]
    ]
  }
}
```

It adds the iOS microphone text and Android's `RECORD_AUDIO` and `MODIFY_AUDIO_SETTINGS`, and nothing for the camera. In bare React Native, add the same three yourself. `microphone: false` turns voice notes off.

## Payments

With Tamr Pay on, the provider's page opens outside the webview, in `expo-web-browser`'s in-app browser when your app has it or else in the system browser, and only when the link is `https`. When the diner comes back to your app, the waiter checks the payment.

## Debug mode

`debug: true` prints every message both ways, the page's loads and its own trace, to `onLog` or the console, and makes the webview inspectable in a debug build of your app (Safari's Web Inspector, `chrome://inspect`). See [Debug mode](https://tamr.link/docs/guides/debugging).

## Methods

| Method | What it does | Since |
| --- | --- | --- |
| `open()`, `close()` | Show the waiter in the host or the sheet, and hide it | 1.0.0 |
| `preload()` | Load the chat hidden, so it opens at once | 1.0.0 |
| `reload()`, `dispose()` | Load again after a failure; stop for good | 1.0.0 |
| `setIdentityProvider(fn)` | Who the diner is: { token }, { code } or null | 1.0.0 |
| `onCartAdd`, `onCartUpdate`, `onCartRemove` | Answer the waiter's cart proposals, per line | 1.0.0 |
| `on(type`, `listener)` | Everything the page tells your app | 1.0.0 |
| `setLocale`, `setAppearance`, `setText`, `setTheme`, `setContext`, `setStarters`, `setRestrictions` | Kept and sent again whenever the page loads again | 1.0.0 |
| `setGoal(goal)` | The diner's nutrition goal as your app keeps it | 1.2.0 |
| `sendCart(lines)`, `chat.send(text)`, `chat.new()`, `clearIdentity()` | One-off messages, held until the chat is ready | 1.0.0 |
| `requestReview({ orderId`, `dishes })` | After an order your backend sent: ask the diner to rate each dish | 1.2.0 |

## Known limitations

- **The microphone grant.** The webview grants a media request only to Tamr's own page. `react-native-webview` can't narrow that grant to the microphone alone: iOS grants Tamr's page whatever it asks for, and Android grants what your app's own permissions allow. The page never asks for the camera, and the plugin adds no camera permission.
- **An Expo app crashes at launch on iOS 27**, built with Xcode 27, because UIKit requires the scene life cycle and the Expo 57 template doesn't adopt it yet. Adopt Expo's `ExpoAppSceneDelegate`. This is your app's setup, not the SDK's.
