RN Assistant

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

@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

pnpm add @docyrus/rn-assistant
pnpm add 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:

app/_layout.tsx

import { SafeAreaProvider } from 'react-native-safe-area-context';
import { KeyboardProvider } from 'react-native-keyboard-controller';

export default function RootLayout() {
  return (
    <SafeAreaProvider>
      <KeyboardProvider>
        {/* your app */}
      </KeyboardProvider>
    </SafeAreaProvider>
  );
}

Configuration

Environment variables

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

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

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

Use when the assistant lives inside a page, tab, or routed screen.

import {
  DocyrusRNAssistantEmbedded,
  createDocyrusRNAssistantConfig,
} from '@docyrus/rn-assistant';

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

export function AssistantScreen() {
  return (
    <DocyrusRNAssistantEmbedded
      apiConfig={assistantConfig}
      agentId={process.env.EXPO_PUBLIC_ASSISTANT_AGENT_ID || ''}
      dataSourceId={process.env.EXPO_PUBLIC_ASSISTANT_DATA_SOURCE_ID}
      credentials={{
        token: auth.tokens?.accessToken,
        userId: auth.user?.id,
      }}
      userId={auth.user?.id}
      showHeader
    />
  );
}

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:

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

createDocyrusRNAssistantConfig

const assistantConfig = createDocyrusRNAssistantConfig({
  baseUrl: string,
  token?: string,
  getToken?: () => Promise<string | null> | string | null,
});

Option	Type	Required	Description
`baseUrl`	`string`	Yes	API root, e.g. `https://alpha-api.docyrus.com`
`token`	`string`	No	Direct bearer token
`getToken`	`() => Promise<string \| null>`	No	Async token provider

Troubleshooting

403 on deployment fetch

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.

RN Assistant

On this page