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:

import { AgentforceService } from "@salesforce/react-native-agentforce";

await AgentforceService.configure({
  type: "service", // or 'employee'
  // ... mode-specific fields
});

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

Example

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

Employee Agent Configuration

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

Configuration Fields

Example: Direct Token

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

Example: With Mobile SDK Auth

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

import { AgentforceService, loginForEmployeeAgent } from "@salesforce/react-native-agentforce";

// Login via Mobile SDK
const creds = await loginForEmployeeAgent();

// Configure with obtained credentials
await AgentforceService.configure({
  type: "employee",
  instanceUrl: creds.instanceUrl,
  organizationId: creds.organizationId,
  userId: creds.userId,
  agentId: "0Xxxx0000001234AAA",
  accessToken: creds.accessToken,
});

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:

// Read stored agent ID
const storedId = await AgentforceService.getEmployeeAgentId();

// Set a new agent ID
await AgentforceService.setEmployeeAgentId("0Xxxx0000005678AAA");

warning: 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.

Feature Flags

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

interface FeatureFlags {
  enableMultiAgent: boolean; // default: true
  enableMultiModalInput: boolean; // default: false
  enablePDFUpload: boolean; // default: false
  enableVoice: boolean; // default: false
  enableCustomViewProvider: boolean; // default: false
}

Flag Details

Setting Feature Flags

Inline with configure():

await AgentforceService.configure({
  type: "service",
  serviceApiURL: url,
  organizationId: orgId,
  esDeveloperName: devName,
  featureFlags: {
    enableMultiAgent: true,
    enableMultiModalInput: true,
    enablePDFUpload: false,
    enableVoice: false,
    enableCustomViewProvider: false,
  },
});

Independently (persisted):

// Save flags -- they take effect the next time configure() is called
await AgentforceService.setFeatureFlags({
  enableMultiAgent: true,
  enableMultiModalInput: true,
  enablePDFUpload: true,
  enableVoice: false,
  enableCustomViewProvider: false,
});

// Read current flags
const flags = await AgentforceService.getFeatureFlags();
console.log(flags.enableMultiModalInput); // true

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

Flag Resolution Order

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

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

Configuration Lifecycle

A typical configuration lifecycle:

1. Set delegates (logger, navigation, view provider) - optional, but do before configure()
2. Set hidden prechat fields - optional, Service Agent only, before launch
3. Call configure() - required
4. Check isConfigured() - optional verification
5. Call launchConversation() - opens UI
6. Call setAdditionalContext() - optional, after launching
7. Call closeConversation() or startNewConversation() - as needed
8. 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

// Check if configured
const isConfigured = await AgentforceService.isConfigured();

// Get detailed configuration info
const info = await AgentforceService.getConfigurationInfo();
if (info.configured) {
  console.log(`Configured in ${info.mode} mode`);
}

See Also

• Conversations
• Delegates
• Employee Agent Authentication
• Troubleshooting