Threading Preservation
Relevant source files
The following files were used as context for generating this wiki page:
Threading preservation is a core feature of Matterbridge that maintains the relationship between parent messages and their replies when relaying communication across different chat protocols. By tracking message identifiers and parent-child relationships, the bridge ensures that conversations organized in threads on one platform (e.g., Slack or Discord) remain threaded on others where the protocol supports it.
Sources: README.md:86
Architecture and Data Flow
The threading logic relies on the exchange of unique message identifiers across the bridge gateway. When a message is part of a thread, it carries a reference to its parent message. This metadata is extracted by the source bridge and interpreted by the destination bridge to place the message in the correct context.
Message Identification and Linking
For threading to function, the bridge utilizes specific fields within the message data structures to identify the origin and target of a reply.
| Field | Description |
|---|---|
id | Unique ID of the message on the gateway. |
parent_id | Unique ID of a parent message, if the message is part of a thread. |
Sources: contrib/api.yaml:113-118
Information Flow Diagram
The following diagram illustrates how threading information is passed through the system from a source platform to a destination platform via the Matterbridge API/Gateway.
The diagram shows the logic path taken to determine if a message should be treated as a reply based on the availability of a parent_id.
Sources: contrib/api.yaml:94-124
Implementation Details
API Integration
The Matterbridge API facilitates threading by exposing parent_id in both incoming and outgoing message objects. This allows 3rd party integrations and native bridges to participate in threaded conversations.
- Incoming Messages: When streaming or listing messages via
/streamor/messages, theparent_idfield indicates if the message is a reply. - Outgoing Messages: When creating a message via
POST /message, providing aparent_id(the ID of a message previously seen on the gateway) allows the bridge to attempt threading on the target platforms.
Sources: contrib/api.yaml:53-124, contrib/api.yaml:143-176
Support Across Protocols
Threading preservation is dependent on the capabilities of the underlying library and protocol. For instance:
- Slack: The
slack-golibrary supportsRootfields inMessageEventto supportthread_broadcastsubtypes and general threading. - GraphQL: The system supports subscriptions and parallel execution of resolvers, which can be used to handle complex message structures including threads.
- IRC: While the IRC protocol traditionally lacks native threading, libraries like
gircfocus on simplicity while Matterbridge handles the mapping of these contexts where possible.
Sources: vendor/github.com/slack-go/slack/CHANGELOG.md:16, vendor/github.com/graph-gophers/graphql-go/README.md:16, vendor/github.com/lrstanley/girc/README.md:58
Data Structures for Threading
The following table summarizes the data model used for threading preservation within the bridge's internal API schemas.
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier used for referencing messages. |
parent_id | string | The identifier of the message this message is replying to. |
timestamp | string | Used to maintain chronological order within threads. |
Sources: contrib/api.yaml:113-122
Conclusion
Threading preservation in Matterbridge is a critical feature for maintaining conversation sanity across heterogeneous chat networks. By abstracting message and parent identifiers, the bridge allows users to follow complex discussions regardless of the platform they are currently using.
Sources: README.md:86