# RN Assistant
URL: /docs/native/guide/rn-assistant

Install, configure, and integrate DocyrusRNAssistant in an Expo or React Native app.

[<img src="https://img.shields.io/npm/v/%40docyrus%2Frn-assistant?label=npm&logo=npm&color=16a34a" alt="npm version" />](https://www.npmjs.com/package/@docyrus/rn-assistant)

`@docyrus/rn-assistant` is a standalone React Native assistant package for Docyrus-compatible backends. It is designed to be embedded into an existing host app without depending on app-local aliases, project-specific folders, or direct `.env` reads inside the package.

The package includes:

- Chat UI with streaming responses
- Session/thread management
- Model and reasoning selection
- File attachments and voice recording
- Built-in theme surface

## Installation

```bash tab="pnpm"
pnpm add @docyrus/rn-assistant
pnpm add react react-native expo react-native-keyboard-controller react-native-safe-area-context react-native-svg
```

```bash tab="npm"
npm install @docyrus/rn-assistant react react-native expo react-native-keyboard-controller react-native-safe-area-context react-native-svg
```

| Dependency | Version |
|---|---|
| React | 19+ |
| React Native | 0.83+ |
| Expo | 55+ |
| `react-native-keyboard-controller` | 1.20.7+ |
| `react-native-safe-area-context` | 5.6.2+ |
| `react-native-svg` | 15.15.3+ |

### Root providers

Wrap your app root with these providers:

```tsx title="app/_layout.tsx"
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { KeyboardProvider } from 'react-native-keyboard-controller';

export default function RootLayout() {
  return (
    
    
  );
}
```

## Configuration

### Environment variables

The package does not read env values itself. Your host app should read env variables and turn them into props/config.

```txt
EXPO_PUBLIC_API_BASE_URL=
EXPO_PUBLIC_ASSISTANT_AGENT_ID=
EXPO_PUBLIC_ASSISTANT_DATA_SOURCE_ID=
EXPO_PUBLIC_OAUTH2_CLIENT_ID=
EXPO_PUBLIC_OAUTH2_SCOPES=openid profile offline_access User.Read Users.Read.All DS.Read.All DS.ReadWrite.All AI.Read.All AI.ReadWrite.All
EXPO_PUBLIC_OAUTH2_CALLBACK_URL=appName://auth/callback
```

### Create assistant config

```tsx
import { createDocyrusRNAssistantConfig } from '@docyrus/rn-assistant';

const assistantConfig = createDocyrusRNAssistantConfig({
  baseUrl: process.env.EXPO_PUBLIC_API_BASE_URL || '',
  getToken: async () => auth.tokens?.accessToken || null,
});
```

You can also pass a direct `token`, but `getToken` is better for host-managed auth refresh.

### Authentication and scopes

The assistant requires a valid authenticated token from the host app.

Recommended scope set:

- `User.Read`, `Users.Read.All`
- `DS.Read.All`, `DS.ReadWrite.All`
- `AI.Read.All`, `AI.ReadWrite.All`

At minimum, assistant deployment loading requires `AI.Read.All` or `AI.ReadWrite.All`.

> If you change OAuth scopes, the user must **sign out and sign in again**. Changing env values alone does not upgrade an already-issued token.

## Usage

  
  

The host app should choose one presentation path at a time. Avoid rendering a page assistant and opening a second assistant sheet on top of it.

## iOS Permissions

If voice recording or media attachments are enabled, define native permission strings in the **host app**:

```ts title="app.config.ts"
export default {
  expo: {
    ios: {
      infoPlist: {
        NSMicrophoneUsageDescription: 'Uses the microphone for voice prompts.',
        NSCameraUsageDescription: 'Uses the camera to attach photos.',
        NSPhotoLibraryUsageDescription: 'Uses your photo library to attach images.',
      }
    }
  }
};
```

- These keys belong to the host app, not the package
- After changing permission strings, rebuild with `run:ios`
- Microphone permission is requested when recording starts, not on first render

## API Reference

  

## Troubleshooting

### 403 on deployment fetch

```txt
Client is not authorized to access this resource. One of the following scopes is required: AI.Read.All, AI.ReadWrite.All
```

Fix: add `AI.Read.All` or `AI.ReadWrite.All` to your OAuth scopes, sign out, and sign in again.

### iOS crashes on microphone access

Fix: add the required `ios.infoPlist` keys in the host app and rebuild with `run:ios`.

### Env changes do not apply

For Expo apps, restart the dev server after changing `EXPO_PUBLIC_*` values.

## Related

- [Native Installation](/docs/native/guide/installation)
- [Native Theming](/docs/native/guide/theming)
- [API Reference](/docs/guide/api-reference)