Manage Conversations in React Native

Learn how to launch, manage, and enrich Agentforce conversations in your React Native application.

There are two methods for opening the conversation UI:

Opens the conversation UI. If an existing conversation is available, it's preserved and the user can continue where they left off.

This is the recommended method for most use cases. It avoids discarding conversation history and provides a smoother user experience.

Closes any existing conversation and starts fresh. The previous conversation is terminated and a new one is created.

Use this when you explicitly want to discard the previous conversation, for example, when the user switches accounts, resolves an issue, or navigates to a different context.

Both methods require:

1. The SDK must be configured via configure(). If not, the native module rejects with NOT_CONFIGURED.
2. On Android, a current Activity must be available. If not, the promise rejects with ERROR: Activity not available.

Terminate the current conversation and dismiss the conversation UI:

The user can also close the conversation by:

• iOS: Tapping the close button in the chat view's top bar
• Android: Tapping the back arrow in the toolbar

Understanding how conversations are managed helps you build better user experiences.

Calling launchConversation() multiple times reuses the same conversation object. This means:

• The user sees their previous messages when re-opening the chat.
• The agent retains context from the ongoing session.
• Additional context set earlier is still active.

Conversations are cleared when:

• closeConversation() is called
• startNewConversation() is called
• resetSettings() is called (clears everything)
• Switching modes (for example, calling configure() with type: 'employee' after previously configuring type: 'service')
• setEmployeeAgentId() is called with a different agent ID (iOS only)

Additional context provides contextual information to the Agentforce agent during a conversation. This helps the agent deliver more personalized and relevant responses.

The bridge validates context variables before sending them to the native SDK:

• Type names are case-sensitive. Use 'Text' not 'text', 'Boolean' not 'boolean'. Invalid types cause an error.
• Each variable must have a non-empty name and type. Missing fields cause an INVALID_CONTEXT error.
• Validation errors are thrown synchronously before the native call, so you can catch them immediately.
• The description field is only supported on Android. On iOS, it's silently ignored.

This example demonstrates all 11 context variable types:

Hidden prechat fields let you pass values to the Service Agent prechat form without displaying them to the user. Common use cases include pre-populating a ContactId, AccountId, or session token.

:::warning Android Limitation On Android, hidden prechat fields are stored but not sent to the native SDK during session initialization. This feature is fully functional on iOS only. If hidden prechat fields are critical to your use case, use iOS or wait for a future bridge update. :::

Register hidden prechat fields before calling launchConversation():

This example shows the full flow of configuring, registering hidden fields, and launching:

The conversation UI is presented differently on each platform.

The conversation UI is presented as a full-screen modal:

• Dismissal triggers onContainerClose, which calls dismiss(animated: true).
• The SDK's built-in top bar is shown.
• The chat view is a SwiftUI view created by the SDK.

The conversation UI is launched as a separate Activity:

• The user closes the conversation by tapping the back arrow.
• It displays a Material 3 Scaffold with a Salesforce-blue top app bar.
• AgentforceConversationActivity is a ComponentActivity that uses Jetpack Compose.

• Configure the SDK
• Delegates
• Limitations