> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Add the Talqui chat to your React Native or Expo app. Works in Expo Go, with no native code of its own and no config plugin.

> [card] [GitHub](https://github.com/talqui-oss/talqui-sdk-reactnative)
>
> Source, issues and changelog

> [card] [npm](https://www.npmjs.com/package/@talqui-oss/talqui-sdk-reactnative)
>
> Package and versions

> [card] [Example app](https://github.com/talqui-oss/talqui-sdk-reactnative/tree/main/example)
>
> Runs in Expo Go

> [!NOTE]
>
> **Works in Expo Go.** The SDK has no native code of its own: no dev build, no config plugin, no `prebuild`.

![Unread count in the host app](https://mintcdn.com/talqui/rN_YKMK5183esTyQ/images/guides/chat-sdks/react-native/screenshot-1-unread.png?fit=max\&auto=format\&n=rN_YKMK5183esTyQ\&q=85\&s=d01462303d702af13fb346f168a1d709)

![Full screen chat with text, an image and a voice message](https://mintcdn.com/talqui/rN_YKMK5183esTyQ/images/guides/chat-sdks/react-native/screenshot-2-fullscreen.png?fit=max\&auto=format\&n=rN_YKMK5183esTyQ\&q=85\&s=58c940edaf3820d2c5b9fed835fa7e2e)

![The chat inline in a tab](https://mintcdn.com/talqui/rN_YKMK5183esTyQ/images/guides/chat-sdks/react-native/screenshot-3-inline-tab.png?fit=max\&auto=format\&n=rN_YKMK5183esTyQ\&q=85\&s=70d3059f46c43c8914de5b0d054bcb70)

## Requirements

React Native 0.73 (Expo SDK 50) or later, iOS 15, Android 7.0 (API 24).

## 1. Install

> [tab] Expo
>
> ```bash theme={null}
> npx expo install @talqui-oss/talqui-sdk-reactnative react-native-webview @react-native-async-storage/async-storage
> ```

> [tab] Bare React Native
>
> ```bash theme={null}
> npm install @talqui-oss/talqui-sdk-reactnative react-native-webview @react-native-async-storage/async-storage
> cd ios && pod install
> ```

> [!TIP]
>
> Using an AI coding agent? Point it to [`AGENT_INSTRUCTIONS.md`](https://github.com/talqui-oss/talqui-sdk-reactnative/blob/main/AGENT_INSTRUCTIONS.md): a step-by-step install it can follow and validate on its own.

## 2. Permissions

Attachments, photos and voice messages need these entries.

> [tab] Expo (app.json)
>
> ```json theme={null}
> {
>   "expo": {
>     "ios": {
>       "infoPlist": {
>         "NSCameraUsageDescription": "Take photos to send in the support chat.",
>         "NSMicrophoneUsageDescription": "Record voice messages for the support chat.",
>         "NSPhotoLibraryUsageDescription": "Choose photos to send in the support chat."
>       }
>     },
>     "android": {
>       "softwareKeyboardLayoutMode": "resize",
>       "permissions": ["android.permission.CAMERA", "android.permission.RECORD_AUDIO", "android.permission.MODIFY_AUDIO_SETTINGS"]
>     }
>   }
> }
> ```

> [tab] Bare React Native
>
> The same three keys in `ios/<App>/Info.plist`, the three permissions in `android/app/src/main/AndroidManifest.xml`, and `android:windowSoftInputMode="adjustResize"` on your main activity.

## 3. Add the provider

Wrap your app once, with the values from [Get your IDs](https://docs.talqui.chat/guides/chat-sdks/get-your-ids.md):

```tsx theme={null}
import { TalquiProvider } from '@talqui-oss/talqui-sdk-reactnative';

export default function App() {
  return (
    <TalquiProvider tenantId="YOUR_TENANT_ID" connectionId="YOUR_CONNECTION_ID">
      <Home />
    </TalquiProvider>
  );
}
```

## 4. Open the chat

From any screen below the provider:

```tsx theme={null}
import { useTalqui } from '@talqui-oss/talqui-sdk-reactnative';
import { Button } from 'react-native';

function Home() {
  const talqui = useTalqui();
  return <Button title="Talk to us" onPress={talqui.open} />;
}
```

The chat opens full screen and closes with the header button or the Android back button. The conversation keeps running while it is closed.

### Or inline, in a tab

```tsx theme={null}
import { TalquiChat } from '@talqui-oss/talqui-sdk-reactnative';
import { useIsFocused } from '@react-navigation/native';

function ChatScreen() {
  return <TalquiChat style={{ flex: 1 }} visible={useIsFocused()} hideCloseButton />;
}
```

`visible` tells the SDK whether the tab is on screen, so replies count as unread while it isn't. `hideCloseButton` removes the header's close button, which has nothing to close in a tab.

## 5. Identify the user

```ts theme={null}
await talqui.identify({
  name: 'Ana Souza',
  email: 'ana@example.com',
  phone: '+5511999990000',
  userHash: hashFromYourBackend, // optional: history across devices
});
```

The pre-chat form is skipped and your team sees who is talking. [How to compute `userHash` →](https://docs.talqui.chat/guides/chat-sdks/identify-users)

## 6. Send context

```ts theme={null}
talqui.setContactMeta({ plan: 'pro', seats: 12 });
talqui.setSessionMeta({ order_id: '4821', step: 'checkout' });
```

[Rules and where it shows up →](https://docs.talqui.chat/guides/chat-sdks/metadata.md)

## 7. Events and unread badge

```tsx theme={null}
import { useTalqui, useTalquiEvent } from '@talqui-oss/talqui-sdk-reactnative';

useTalquiEvent('messageReceived', (event) => {
  console.log(`${event.operatorName ?? 'Support'}: ${event.preview}`);
});

const { unreadCount } = useTalqui();
```

Call `talqui.preload()` early (after login, for example) so replies are counted before the user first opens the chat. [All events →](https://docs.talqui.chat/guides/chat-sdks/events.md)

## 8. Logout

```ts theme={null}
await talqui.logout();
```

Forgets the user on this device, clears everything you set, unlinks the push token and starts a fresh anonymous visitor.

## 9. Push notifications

Optional: notify the user when a reply arrives while they are away. Set up Firebase and hand the device token to the SDK. See [Push notifications for mobile apps](https://docs.talqui.chat/guides/push-notifications/mobile-apps.md).

## API reference

### `<TalquiProvider>`

| Prop | Type | |
| - | - | - |
| `tenantId` | `string` | Required. Your workspace ID. |
| `connectionId` | `string` | Required. The WebChat connection ID. |
| `onOpenUrl` | `(url: string) => void` | Handles links tapped in the chat. Default: `Linking.openURL`. |
| `renderLoading` | `() => ReactNode` | Replaces the loading spinner. |
| `renderError` | `(retry: () => void) => ReactNode` | Replaces the screen shown when the chat cannot load. |
| `debug` | `boolean` | Logs every message exchanged with the chat. |

### `useTalqui()`

| Member | |
| - | - |
| `open()` / `close()` | Show or hide the full-screen chat. |
| `preload()` | Loads the chat ahead of time so `open()` is instant and replies are counted. |
| `identify(user)` | Sets who the user is: `name`, `email`, `phone`, `userHash`. |
| `setContact(contact)` | Updates `name`, `email` or `phone`. |
| `setContactMeta(meta)` / `setSessionMeta(meta)` | Custom data, see [Metadata](https://docs.talqui.chat/guides/chat-sdks/metadata.md). |
| `prefill(text)` | Puts text in the message box. The user still decides to send it. |
| `logout()` | Forgets the user and starts a fresh visitor. |
| `setPushToken(token)` | The device's FCM token, see [Push notifications](https://docs.talqui.chat/guides/push-notifications/mobile-apps.md). |
| `handlePush(data)` | Opens the chat for a tapped Talqui notification and returns whether it was one. `isTalquiPush(data)` is also exported. |
| `unreadCount`, `isReady`, `isOpen` | Current state. |

### `useTalquiEvent(name, callback)`

Subscribes to one [event](https://docs.talqui.chat/guides/chat-sdks/events.md) for the lifetime of the component.

### `<TalquiChat>`

| Prop | Type | |
| - | - | - |
| `style` | `ViewStyle` | Usually `{ flex: 1 }`. |
| `visible` | `boolean` | Whether this screen is on screen. |
| `onCloseRequested` | `() => void` | The user tapped close in the header. |
| `hideCloseButton` | `boolean` | Hides the header's close button. Default `false`. |

## Example app

```bash theme={null}
git clone https://github.com/talqui-oss/talqui-sdk-reactnative
cd talqui-sdk-reactnative/example
npm install
npx expo start
```

Open it in Expo Go. It has an "Open chat" button with the unread count, a "Chat" tab, and buttons for identify, metadata, prefill and logout, connected to the Talqui demo workspace.

Something not working? See [Troubleshooting](https://docs.talqui.chat/guides/chat-sdks/troubleshooting.md#react-native).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.