Collaboration, 2026.5

Collaboration API Guide

The Collaboration API in FirstSpirit extends the platform’s built-in commenting functionality, which is already available to users via the ContentCreator. While editors can create and manage discussions directly in the UI, the API provides developers with a structured way to programmatically access and enhance this functionality.

Using the API, conversations can be created and managed in a context-specific manner, allowing discussions to be attached to precise content elements such as pages or sections. This ensures that feedback and communication remain closely tied to the relevant content, while enabling custom integrations and advanced collaboration workflows beyond the standard UI capabilities.

The Collaboration API supports the following core functionalities:

Creating and managing of comment threads
Adding and retrieving messages within a conversation
Contextual linking of discussions to specific content elements
Full lifecycle management, including create, read, update, archive, and unarchive operations
Multi-language support, enabling language-specific conversations
Real-time updates via WebSockets
Validation and error handling to ensure robust integrations

The following examples are based on the Collaboration API (

) .

Example use cases

Creating a conversation and adding a message

The example below demonstrates the basic usage of the Collaboration API in FirstSpirit by creating a new conversation and adding a message to it. The script first initializes the API via the CollaborationAgents entry point and constructs a ConversationPath to define the exact content context where the conversation should be attached. Using this path, it creates a new conversation thread and then adds a message to that conversation as the current user.

// Imports: FirstSpirit Imports
import de.espirit.firstspirit.agency.SpecialistsBroker;

// Imports: Collaboration API Imports
import com.crownpeak.firstspirit.modules.collaboration.agency.CollaborationAgents;
import com.crownpeak.firstspirit.modules.collaboration.agency.ConversationAgent;
import com.crownpeak.firstspirit.modules.collaboration.agency.IdentifierAgent;
import com.crownpeak.firstspirit.modules.collaboration.agency.MessageAgent;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Conversation;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.ConversationPath;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Message;

// Required: SpecialistsBroker
//  You can obtain a SpecialistsBroker using a Connection (connection.getBroker())
//  or you can use 'context' in FirstSpirit scripts
SpecialistsBroker broker = /* ... */;

// Required: Project ID
long projectId = /* ... */;

// Obtain CollaborationAgents instance - This is the entry point for the Collaboration Java API
CollaborationAgents collaborationAgents = CollaborationAgents.create(broker);

// Create Conversation Path - used to locate a Conversation on an IDProvider
IdentifierAgent identifierAgent = collaborationAgents.getIdentifierAgent(projectId);
ConversationPath path = identifierAgent.createPathBuilder(/* IDProvider */)
		.language(/* Language Code, e.g. "DE" */)
		.editor(/* Editor Name, e.g. "pt_headline" */)
		.build();

// Shows how to post a new Conversation using the ConversationPath we built earlier
//  All messages will be posted as the current User
ConversationAgent conversationAgent = collaborationAgents.getConversationAgent(projectId);
Conversation conversation = conversationAgent.create(path, "Hello, World!");

// Shows how to post a new Message in our Conversation
MessageAgent messageAgent = collaborationAgents.getMessageAgent(projectId);
Message message = messageAgent.addMessage(conversation.getId(), "It's a wonderful day for Collaborating!");

Retrieving conversations and their messages

This example demonstrates how to retrieve and inspect existing conversations and their messages for a specific content element using the Collaboration API in FirstSpirit. The script initializes the required agents, resolves the unique identifier (GID) of an IDProvider (such as a page), and fetches all associated conversations for a given language and archive state. It then iterates through each conversation and retrieves its messages, outputting details such as the author and message content.

// Imports: FirstSpirit Imports
import de.espirit.firstspirit.access.store.IDProvider;
import de.espirit.firstspirit.agency.SpecialistsBroker;
import de.espirit.firstspirit.common.GidAgent;

// Imports: Collaboration API Imports
import com.crownpeak.firstspirit.modules.collaboration.agency.CollaborationAgents;
import com.crownpeak.firstspirit.modules.collaboration.agency.ConversationAgent;
import com.crownpeak.firstspirit.modules.collaboration.agency.MessageAgent;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Conversation;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Message;

import java.util.*;

// Required: SpecialistsBroker
//  You can obtain a SpecialistsBroker using a Connection (connection.getBroker())
//  or you can use 'context' in FirstSpirit scripts
SpecialistsBroker broker = /* ... */;

// Required: Project ID
long projectId = /* ... */;

// Obtain CollaborationAgents instance - This is the entry point for the Collaboration Java API
CollaborationAgents collaborationAgents = CollaborationAgents.create(broker);

// Obtains the Collaboration API Agents
ConversationAgent conversationAgent = collaborationAgents.getConversationAgent(projectId);
MessageAgent messageAgent = collaborationAgents.getMessageAgent(projectId);

// Shows how to retrieve all Conversations for an IDProvider
IDProvider idProvider = ...; // The IDProvider, e.g., a PageRef
String language = ...; // e.g. "DE"
boolean archived = false; // Whether to fetch archived Conversations or non-archived Conversations

// Obtain the Gid of the IDProvider using GidAgent. The Collaboration API uses the Gid to find the IDProvider.
GidAgent gidAgent = broker.requireSpecialist(GidAgent.TYPE);
UUID elementGid = gidAgent.getGid(idProvider);

// Get the Conversations for the Element
List<Conversation> conversations = conversationAgent.getConversations(elementGid, language, archived);
System.out.println("Got " + conversations.size() + " conversations.");

// Iterate through all Conversations and show their Messages
for (Conversation conversation : conversations) {
	System.out.println("Conversation:");

	// Get Messages for Conversation and output their contents
	List<Message> messages = messageAgent.getMessages(conversation.getId());
	System.out.println("Conversation has " + messages.size() + " messages.");
		for (Message message : messages) {
		System.out.println("Message");
		System.out.println(message.getAuthor().getDisplayName() + ":");
		System.out.println(message.getContent());
		System.out.println();
	}
}