Matterbridge API

Relevant source files

The following files were used as context for generating this wiki page:

• bridge/api/api.go
• contrib/api.yaml
• README.md
• bridge/mattermost/mattermost.go
• vendor/github.com/labstack/echo/v4/README.md

The Matterbridge API provides a read/write interface allowing third-party applications to interact with the chat bridge. It enables external systems to send and receive messages across all supported protocols by acting as a virtual bridge endpoint. This is particularly useful for integrating bots, games (like Minecraft), or web services that do not have native bridge support in the core project.

The API is built using the Echo web framework and supports standard RESTful HTTP requests as well as real-time streaming via WebSockets and JSON streams. It functions by enqueuing incoming messages from other bridges into a ring buffer for retrieval and forwarding messages received via the API to the central gateway for distribution to other connected platforms.
Sources: README.md:94-118, bridge/api/api.go:37-50, contrib/api.yaml:4-10

Architecture and Components

The API module is structured as a bridge implementation that satisfies the bridge.Bridger interface. It utilizes a ring buffer to manage message history and a WebSocket router for real-time bidirectional communication.

Core Data Structures

Structure	Description	Key Fields
API	Primary state controller for the API bridge.	Messages (Ring Buffer), mrouter (WebSocket router), Config
Message	The internal representation of a chat message within the API context.	Text, Username, UserID, Avatar, Gateway
config.IncomingMessage	The schema for messages sent from Matterbridge to the API client.	event, gateway, text, username, timestamp

Sources: bridge/api/api.go:21-34, contrib/api.yaml:63-108

System Flow

The following diagram illustrates how a message originates from an external API client and is propagated through the Matterbridge gateway to other protocols (e.g., Mattermost).

API Endpoints

The API is served under the /api base path. If a Token is configured, all requests must include a security key for authentication.
Sources: bridge/api/api.go:68-72, contrib/api.yaml:58-61

REST Interface

Endpoint	Method	Description
/api/health	GET	Checks if the API server is alive. Returns "OK".
/api/messages	GET	Lists and clears new messages from the internal ring buffer.
/api/message	POST	Creates a new message to be sent to the gateway.
/api/stream	GET	Streams real-time messages using application/x-json-stream.

Sources: bridge/api/api.go:76-80, contrib/api.yaml:14-57

WebSocket Interface

The API provides a WebSocket endpoint at /api/websocket using the melody library.

• Connection: Upon connection, the server sends an EventAPIConnected greeting.
• Handling: Incoming WebSocket messages are decoded and forwarded to the gateway, while also being broadcast to other connected WebSocket sessions.
  Sources: bridge/api/api.go:42-56, bridge/api/api.go:179-198

Configuration

The API bridge behavior is controlled via the matterbridge.toml file or the environment.

Option	Type	Description
BindAddress	string	The IP and port the API server listens on (e.g., 127.0.0.1:8080).
Buffer	int	The capacity of the ring buffer for storing messages.
Token	string	Security token required for KeyAuth middleware.
RemoteNickFormat	string	Format for nicknames from other bridges. Defaults to {NICK}.

Sources: bridge/api/api.go:63-75, bridge/api/api.go:82-84

Message Handling and Logic

Posting Messages

When a message is received via POST /api/message, the API bridge performs the following steps:

1. Normalization: Sets fixed values for Channel ("api"), Protocol ("api"), and a fresh Timestamp.
2. File Processing: If the Extra field contains files, it decodes Base64 data into byte slices.
3. Dispatch: Sends the final config.Message object to the Remote channel, which communicates with the Matterbridge gateway.
   Sources: bridge/api/api.go:102-132

Receiving Messages

The Send method is called when the gateway has a message for the API:

1. Filtering: Delete events (EventMsgDelete) are ignored.
2. Storage: The message is enqueued in the Messages ring buffer.
3. Broadcasting: The message is broadcasted to all active WebSocket clients via the mrouter.
   Sources: bridge/api/api.go:87-100

Summary

The Matterbridge API serves as a flexible extension point for the project. By implementing the Bridger interface and providing both REST and WebSocket endpoints, it allows users to integrate virtually any chat-capable software with the Matterbridge ecosystem without modifying the core Go source code.
Sources: README.md:112-118, bridge/api/api.go:37-80