Manage Conversations

This document provides implementation guidelines and best practices for developers on how to generate conversation IDs and use these IDs to create, close, and query conversations.

A messaging conversation represents a communication exchange between a messaging user—also known as the customer—and a service rep, an Agentforce agent, an Einstein bot, or a combination of them.

The lifetime of a conversation is broken down into four stages:

  1. Creation–A new messaging conversation between a messaging user and a service rep, Agentforce agent, or Einstein bot starts.
  2. Session–One or more messaging sessions occur within that conversation. Ending a session does not end the conversation. For example, clicking the End Chat button ends only the current session; it doesn’t end the conversation. See the Enhanced Chat and Messaging Glossary for precise definitions.
  3. Closing–The messaging conversation is explicitly closed. When a conversation is closed, the status of the conversation changes to closed and no new messages can be sent.
  4. Persistence–The conversation history is preserved, and the historical conversation data can be queried at any time for analysis using the Conversation Query API.

Each conversation has a unique, randomly-generated ID that persists for the conversation’s entire lifetime and links all messages and participants in that thread.

The Enhanced In-App SDK uses these conversation IDs to track and manage message conversations throughout their entire lifecycle.

A valid conversation ID must be:

  • A randomly-generated (version 4) universally unique identifier (UUID v4).
  • Completely independent of business logic or customer data.
  • Used only for conversation tracking and management.

Never substitute conversation IDs with customer IDs or any other business identifiers.

Consider the following limitations with conversation IDs:

  • Conversation IDs can’t be moved from a staging org to a production org.
  • Conversation IDs can’t be transferred between verified and unverified users.
  • Conversation IDs created in an unverified session can’t be migrated to another device.
  • Conversation IDs are tied to user verification; if the local database or app is deleted, unverified conversations become inaccessible.

The Enhanced In-App SDK can generate UUIDs automatically, or you can manually generate the IDs yourself:

Follow these guidelines when generating conversation IDs:

  • The conversation ID must be a randomly-generated (version 4) universally unique identifier (UUID v4)
  • The conversation ID must be generated with the system’s UUID mechanism.
  • The conversation ID must be unique across all conversations.
  • The conversation ID must be stored and managed by your application.

To keep one ongoing conversation, you need:

  • A valid and unique conversation ID (UUID).
  • Proper initialization of the conversation object.
  • Persistent storage for the ID.
  • Logic to manage conversation state.

Use the Conversation Query API to access and display multiple conversations. See Conversation Lists for more information.

Follow these best practices when generating conversation IDs:

  • Store and retrieve conversation IDs systematically.
  • Use pagination for large result sets.
  • Implement retries and error handling.
  • Cache conversations when appropriate.
  • Prefer verified users for multi-conversation workflows.

Consider the following recommended approaches when managing conversations.

Developer manages conversation IDs

Follow best practices when managing conversation IDs. Some aspects to consider when managing conversation IDs include:

  • Generating and storing the unique conversation ID (UUID).
  • Persisting the conversation ID securely (e.g., Keychain / encrypted database).
  • Handling the conversation ID’s lifecycle.
  • Using verified conversations for anything beyond quick one-offs.

Developer leverages SDK queries

Use the Enhanced In-App SDK queries to take full advantage of your conversation data. For example,

  • Use the Conversation Query API to look up existing conversations.
  • Implement robust error handling.
  • React to state changes (e.g., closed, archived).

Follow these implementation guidelines to create, close, and query conversations.

To create a new conversation, build a configuration object and instantiate a ConversationClient (Core SDK), or create an Interface view (UI SDK).

To close a conversation, call the closeConversation method on the ConversationClient, or call the closeConversation method on the CoreClient.

Using ConversationClient:

Using CoreClient:

To query a conversation, refer to the Conversation List documentation for query examples and pagination details.