Configure the Agentforce SDK for React Native

Learn how to configure the Agentforce Mobile SDK for your React Native application. The SDK supports two modes: Service Agent for anonymous customer support, and Employee Agent for authenticated internal use.

Overview

The configure() method accepts a configuration object with a type field that determines the SDK’s operating mode:

1import { AgentforceService } from "react-native-agentforce";
2
3await AgentforceService.configure({
4  type: "service", // or 'employee'
5  // ... mode-specific fields
6});

Both modes share organizationId and optional featureFlags. Other fields are specific to each mode.

Service Agent Configuration

Service Agent mode is for anonymous/guest access, typically for customer-facing support scenarios. No OAuth authentication is required.

Configuration Fields

Field	Type	Required	Description
`type`	`'service'`	Yes	Must be `'service'`
`serviceApiURL`	`string`	Yes	The Service API URL for your deployment. Found in Setup > Embedded Service Deployments > Settings. Must be a valid URL (for example, `https://your-site.salesforce.com`).
`organizationId`	`string`	Yes	Your Salesforce Organization ID. Found in Setup > Company Information. Can be 15 or 18 characters.
`esDeveloperName`	`string`	Yes	The developer name of your Embedded Service deployment. Found in Setup > Embedded Service Deployments.
`featureFlags`	`FeatureFlags`	No	Optional feature flags. If omitted, persisted flags (or defaults) are used.

Example

1await AgentforceService.configure({
2  type: "service",
3  serviceApiURL: "https://mycompany-support.my.salesforce-scrt.com",
4  organizationId: "00Dxx0000001234EAA",
5  esDeveloperName: "My_Service_Agent",
6});

Employee Agent Configuration

Employee Agent mode is for authenticated, internal-use scenarios. Users must be authenticated with a valid Salesforce OAuth token.

Configuration Fields

Field	Type	Required	Description
`type`	`'employee'`	Yes	Must be `'employee'`
`instanceUrl`	`string`	Yes	Your Salesforce instance URL (for example, `https://myorg.my.salesforce.com`).
`organizationId`	`string`	Yes	Salesforce Organization ID.
`userId`	`string`	Yes	The Salesforce User ID of the authenticated user (for example, `005xx0000001234`).
`agentId`	`string`	No	The Agentforce Agent ID. If omitted and `enableMultiAgent` is true, the SDK picks the first available agent.
`agentLabel`	`string`	No	A display label shown in the conversation UI title bar (Android).
`accessToken`	`string`	No	OAuth access token. Can be provided directly or obtained via Mobile SDK auth.
`featureFlags`	`FeatureFlags`	No	Optional feature flags.

Example: Direct Token

1await AgentforceService.configure({
2  type: "employee",
3  instanceUrl: "https://myorg.my.salesforce.com",
4  organizationId: "00Dxx0000001234EAA",
5  userId: "005xx0000001234AAA",
6  agentId: "0Xxxx0000001234AAA",
7  accessToken: "your_oauth_access_token",
8});

Example: With Mobile SDK Auth

When using the Mobile SDK for authentication, obtain credentials first and then pass them to configure():

1import { AgentforceService, loginForEmployeeAgent } from "react-native-agentforce";
2
3// Login via Mobile SDK
4const creds = await loginForEmployeeAgent();
5
6// Configure with obtained credentials
7await AgentforceService.configure({
8  type: "employee",
9  instanceUrl: creds.instanceUrl,
10  organizationId: creds.organizationId,
11  userId: creds.userId,
12  agentId: "0Xxxx0000001234AAA",
13  accessToken: creds.accessToken,
14});

See Employee Agent Authentication for details on the Mobile SDK auth integration.

agentId Behavior

The agentId field determines which agent the conversation uses:

If agentId is provided, the conversation starts with that specific agent.
If agentId is omitted and enableMultiAgent is true (the default), the SDK bootstraps and picks the first available agent.
If agentId is omitted and enableMultiAgent is false, the conversation will likely fail. A warning is logged on both platforms.

You can read and write the agentId independently of configuration:

1// Read stored agent ID
2const storedId = await AgentforceService.getEmployeeAgentId();
3
4// Set a new agent ID
5await AgentforceService.setEmployeeAgentId("0Xxxx0000005678AAA");

Platform Difference

On iOS, calling setEmployeeAgentId() with a different agent ID triggers an immediate conversation close and client cleanup. The new agent ID takes effect right away.

On Android, the method only persists the value. The change takes effect on the next configure() or launchConversation() call.

Warning

Feature Flags

Feature flags control optional SDK capabilities. They can be provided inline with the config or set independently.

1interface FeatureFlags {
2  enableMultiAgent: boolean; // default: true
3  enableMultiModalInput: boolean; // default: false
4  enablePDFUpload: boolean; // default: false
5  enableVoice: boolean; // default: false
6  enableCustomViewProvider: boolean; // default: false
7}

Flag Details

Flag	Default	Description
`enableMultiAgent`	`true`	When true and no `agentId` is specified, the SDK bootstraps and picks from available agents. When false, an `agentId` must be provided.
`enableMultiModalInput`	`false`	Enables camera and image attachment capabilities in the conversation UI. Requires camera/photo permissions.
`enablePDFUpload`	`false`	Enables PDF file upload in the conversation.
`enableVoice`	`false`	Enables voice input (microphone) in the conversation UI. Requires microphone permission.
`enableCustomViewProvider`	`false`	Enables the custom view provider system. When true and a `ViewProviderDelegate` is registered, the SDK delegates rendering of matched component types to your React Native components.

Setting Feature Flags

Inline with configure():

1await AgentforceService.configure({
2  type: "service",
3  serviceApiURL: url,
4  organizationId: orgId,
5  esDeveloperName: devName,
6  featureFlags: {
7    enableMultiAgent: true,
8    enableMultiModalInput: true,
9    enablePDFUpload: false,
10    enableVoice: false,
11    enableCustomViewProvider: false,
12  },
13});

Independently (persisted):

1// Save flags -- they take effect the next time configure() is called
2await AgentforceService.setFeatureFlags({
3  enableMultiAgent: true,
4  enableMultiModalInput: true,
5  enablePDFUpload: true,
6  enableVoice: false,
7  enableCustomViewProvider: false,
8});
9
10// Read current flags
11const flags = await AgentforceService.getFeatureFlags();
12console.log(flags.enableMultiModalInput); // true

Changing feature flags via setFeatureFlags() does not take effect immediately. You must call configure() again (or restart the app) for changes to apply.

Note

Flag Resolution Order

When configure() is called, feature flags are resolved in this order:

If featureFlags is provided in the configure() call, those values are used.
If featureFlags is omitted, the bridge reads persisted flags from native storage.
If no persisted flags exist, hard-coded defaults are used (enableMultiAgent: true, all others false).

Configuration Lifecycle

A typical configuration lifecycle:

Set delegates (logger, navigation, view provider) - optional, but do before configure()
Set hidden prechat fields - optional, Service Agent only, before launch
Call configure() - required
Check isConfigured() - optional verification
Call launchConversation() - opens UI
Call setAdditionalContext() - optional, after launching
Call closeConversation() or startNewConversation() - as needed
Call destroy() - on app shutdown

When switching between modes (for example, from Service to Employee), calling configure() again with a different type automatically cleans up the previous client and conversation.

Checking Configuration Status

1// Check if configured
2const isConfigured = await AgentforceService.isConfigured();
3
4// Get detailed configuration info
5const info = await AgentforceService.getConfigurationInfo();
6if (info.configured) {
7  console.log(`Configured in ${info.mode} mode`);
8}

Configure the Agentforce SDK for React Native

Overview

Service Agent Configuration

Configuration Fields

Example

Employee Agent Configuration

Configuration Fields

Example: Direct Token

Example: With Mobile SDK Auth

agentId Behavior

Feature Flags

Flag Details

Setting Feature Flags

Flag Resolution Order

Configuration Lifecycle

Checking Configuration Status

See Also