In BrainSoup, Events are a unique type of message that can be injected into a chat room. They can contain data and allow agents to respond accordingly to the event.

These events originate from what is referred to as an Event Source and contain a Subject. Chat rooms within BrainSoup have the ability to subscribe to these Event Subjects, allowing them to receive and process the relevant events.

BrainSoup provides a range of built-in event sources such as OperatingSystem , Application , Timer , Clock , among others.

Custom Event

BrainSoup also provides a special event source known as Custom Events. This event source consumes all JSON files that are created in the BrainSoup Events folder, following a specific structure, and injects them as events into the chat rooms that are subscribed to its subject.

Creating a Custom Event involves creating a JSON file with any random name in the Events folder, in the structure outlined below:


"subject": "MyCustomEvent", // chat rooms can subscribe to this subject

"displayName": "My custom event", // how the event will be displayed in the chat

"message": "Hello agents!",

"data": {

// optionally, you can include useful JSON data for your agents here



In this example, MyCustomEvent is the subject chat rooms would subscribe to. Every time a new JSON file with this subject is created in the Events folder, the "Hello agents!" message and any included data would be sent as an event to all subscribed chat rooms.

JSON was chosen due to its widespread usage and approachability. Many web APIs return JSON data, making it easy to integrate their results into an event's "data" field. Thus, it provides a straightforward and efficient way to interface BrainSoup with external tools.

Looking at future updates, BrainSoup plans to offer the ability to add new Event Sources via plugins, providing increased flexibility and customization to how events can be used on the platform.