So here’s the thing: I had Rocket.Chat running smoothly, my team was chatting away, and everything was great. But then I thought, „Hey, wouldn’t it be cool if I could hook up all my bots to this?“
I had an old Rocket.Chat Hubot integration running via Docker until mid-year, but Rocket.Chat dropped official support for it. The writing was on the wall—Hubot was legacy, and I needed a new approach. Meanwhile, I had Typebot running for conversational workflows, but there was no native Rocket.Chat integration. I also wanted to connect other bot frameworks and automation tools without being locked into Rocket.Chat’s Apps-Engine ecosystem or relying on deprecated adapters.
Enter: Bot Bridge.
What Does Bot Bridge Actually Do?
Think of Bot Bridge as a smart messenger service between Rocket.Chat and your external bot. Here’s how it works:
- Someone mentions your bot in a Rocket.Chat channel (like
@botname help) - Bot Bridge intercepts it and goes, „Oh hey, this is for the bot!“
- It packages everything up nicely – the message, who sent it, which room it’s in, all the good stuff
- Fires it off via HTTP to your bot’s endpoint
- Your bot does its thing and sends a response back
- Bot Bridge posts it in the chat like nothing even happened
It’s bidirectional, it’s fast, and honestly, it just works.
The Cool Features (Because Why Not?)
Slash Commands FTW
I added /hellobot as a slash command because sometimes you just want to talk directly to your bot without all the @mentions. Quick status check? /hellobot status. Need help? /hellobot help. Want to send any random command? /hellobot whatever-you-want.
It’s like having a direct line to your bot. No fuss, no muss.
Flexible Triggers (Because One Size Doesn’t Fit All)
I built in multiple ways to trigger your bot:
- Mentions: The classic
@botnameapproach - Direct Messages: Slide into those DMs with your bot
- Custom Regex Patterns: Get fancy and trigger on specific text patterns
- Room Filtering: Listen everywhere or just in specific rooms
Mix and match however you want. I’m not judging.
Security That Doesn’t Suck
Nobody wants their bot endpoints getting hammered by random internet people. So I added authentication tokens – just configure a shared secret, and Bot Bridge will include it in all requests. Simple, effective, done.
The Technical Bits (For the Nerds Among Us)
Under the hood, Bot Bridge is a Rocket.Chat Apps-Engine app written in TypeScript. It hooks into the IPostMessageSent event, which means it sees every message that flows through your server (well, the ones you tell it to watch, anyway).
When it catches something that matches your triggers, it POSTs a nice JSON payload to your bot’s HTTP endpoint:
|
1 2 3 4 5 6 7 8 |
{ "text": "@botname help", "user": { "username": "johndoe", "name": "John Doe" }, "room": { "name": "general", "type": "c" }, "callbackUrl": "https://your-server.com/api/apps/public/.../bot-response" } |
Your bot processes it, sends back a response to that callback URL, and boom – message appears in the chat. The whole round trip usually takes less than a second.
Why I Built This
Look, I love Hubot. I’ve been using it forever. But I also love Rocket.Chat. And I got tired of maintaining hacky integrations that broke every time someone sneezed.
I wanted something clean, maintainable, and flexible enough to work with any bot that could handle HTTP requests. Whether you’re team Hubot, team custom-bot-written-in-Python or team PHP, Bot Bridge has your back.
The PHP Twist (Inspired by Hubot)
Oh, and here’s where it gets fun. I built a PHP connector that turns your bot into a modular plugin system – heavily inspired by Hubot’s brilliant plugin architecture. Want Google search in your chat? There’s a plugin. Need WordPress integration? Plugin. Want to display random BOFH excuses? You bet there’s a plugin for that.
Just like Hubot made it dead simple to extend functionality with CoffeeScript modules, I wanted the same developer experience in PHP. Each plugin is self-contained, easy to add, and easier to remove. The whole thing runs as a simple PHP endpoint that Bot Bridge talks to. No frameworks, no complex dependencies – just good old PHP doing what it does best.
All plugins share saved data and history.
|
1 2 3 4 5 6 7 8 9 10 11 |
<?php // Seriously, it's this simple $pluginManager = new PluginManager(); $pluginManager->registerPlugin(new GooglePlugin()); $pluginManager->registerPlugin(new WordPressPlugin()); $pluginManager->registerPlugin(new BOFHPlugin()); // Handle incoming message $response = $pluginManager->handleMessage($message); |
A Go version is available as well.
The i18n Cherry on Top
Because not everyone speaks English (shocking, I know), I added internationalization support. English and German are built-in, but adding more languages is literally just editing a JSON file.
Want your bot bridge in Klingon? Go for it. I won’t stop you.
Real Talk: What I Learned
Building this taught me a few things:
- Keep it simple: The best integrations are the ones you forget are even there
- Make it flexible: Everyone’s setup is different – embrace it
- Documentation matters: If people can’t figure out how to use it, it doesn’t matter how cool it is
- TypeScript is your friend: Especially when you’re dealing with APIs and type safety matters
What’s Next?
I’m already thinking about v2. More plugins, better error handling, maybe some analytics to see which commands get used most. I am also working on adding Apps-Engine Interfaces using the UIKit.
But for now, Bot Bridge does what it needs to do: it bridges your bots to Rocket.Chat without making you want to flip your desk.
The Bottom Line
If you’re running Rocket.Chat and you’ve got a bot you want to integrate, Bot Bridge is probably the easiest way to do it. It’s well-documented and built by someone who actually uses it in production.
Availability: Bot Bridge is currently available exclusively for my clients and internal projects. It’s not publicly released yet, but I’m using it in production environments and continuously improving it based on real-world usage.
Interested? If you’re a client or working on a project with me, reach out and we can get you set up.
Now go forth and bridge those bots!
Changelog & Features
Bot Bridge Features
Core Functionality
- HTTP Bridge: Connect Rocket.Chat to external bot instances (Hubot, custom bots) via HTTP
- Bidirectional Communication: Messages flow from Rocket.Chat to bots, and bots can send responses back
- Flexible Message Routing: Configure when and where the bot responds
Message Triggers
- Bot Mentions: Respond when users mention the bot by name (e.g.,
@botname) - Direct Messages: Automatically respond to all DMs
- Custom Patterns: Define regex patterns to trigger bot responses
- Room Filtering: Limit bot to specific channels or allow all channels
Slash Commands
/hellobot status– View current bot configuration and connection status/hellobot help– Display help information and available commands/hellobot uikit status– View status in rich UIKit card format/hellobot uikit help– View help in rich UIKit card format/hellobot uikit button– Interactive button demo/hellobot uikit image– Image display demo/hellobot uikit all– Display all UIKit demos
UIKit Support
- Rich Message Formatting: Display beautiful cards, sections, dividers, and context blocks
- Interactive Buttons: Add clickable buttons with custom actions
- Image Support: Display images from public URLs
- TypeScript API: UIKitHelper class for creating cards in Rocket.Chat app
- PHP API: UIKitBuilder class for creating cards in external bots
- Button Interactions: Handle button clicks in both TypeScript and PHP
- Single Handler Pattern: Use one handler for multiple button actions with different values
PHP Connector
- Plugin System: Modular architecture for easy bot command development
- Base Plugin Class: Extend BasePlugin to create custom commands
- Pattern Matching: Use regex patterns to trigger specific plugins
- Brain/Memory System: Store and retrieve persistent data per user
- Response API: Simple methods to send text, UIKit blocks, and more
- Built-in Plugins:
- PingPlugin: Responds to „ping“ with „pong“
- TimePlugin: Shows current server time
- EchoPlugin: Echoes back user messages
- UIKitDemoPlugin: Demonstrates all UIKit features with interactive examples
Security & Configuration
- Token Authentication: Optional token-based auth for bot requests
- URL Configuration: Configurable bot URL and callback URL
- Timeout Settings: Adjustable HTTP timeout for bot responses
- SSL Support: Works with HTTPS endpoints
Developer Experience
- TypeScript: Full TypeScript support with type definitions
- Debug Logging: Comprehensive logging in both TypeScript and PHP
- Documentation: Complete guides for TypeScript and PHP development
- Easy Deployment: Simple npm scripts for building and deploying
- Extensible: Easy to add new slash commands, plugins, and UIKit components
Response Types
- Plain Text: Simple text messages
- Markdown: Rich text formatting with bold, italic, links, etc.
- UIKit Blocks: Structured layouts with sections, dividers, context
- Attachments: Legacy attachment format support
- Threaded Replies: Respond in message threads
- Custom Usernames: Override bot display name per message
- Custom Emojis: Set custom avatar emoji per message
Error Handling
- Graceful Degradation: Falls back to text if UIKit rendering fails
- Error Cards: Beautiful error displays with UIKit
- Success Cards: Confirmation messages with UIKit
- Validation: Input validation for all API endpoints
- Timeout Protection: Prevents hanging requests
FAQ
What is Bot Bridge and why do I need it?
Bot Bridge is a custom Rocket.Chat integration that connects external bots to your chat after Rocket.Chat dropped official Hubot support. It acts as an HTTP intermediary that captures messages, packages them with relevant data, and forwards them to your bot endpoints. If you’re running custom bots or want flexibility beyond Rocket.Chat’s Apps-Engine ecosystem, you need this.
How does Bot Bridge differ from the old Hubot adapter?
Hubot adapters ran bots directly inside Rocket.Chat. Bot Bridge takes a different approach—it’s a middleware that forwards messages via HTTP to external bot endpoints. This means your bots run independently and can be written in any language that handles HTTP requests. It’s more flexible but requires you to host your bot separately.
What triggers Bot Bridge to send messages to my bot?
Bot Bridge monitors four trigger types: bot mentions like @botname, direct messages to the bot, custom regex patterns you define, and slash commands like /hellobot status. You can also filter by specific rooms. When it catches a match, it POSTs a JSON payload to your bot’s endpoint with all the message details.
Can I use Bot Bridge with Apps-Engine apps?
Bot Bridge IS built on Apps-Engine, so yeah, they work together fine. The difference is Bot Bridge lets your bot logic live outside Rocket.Chat as a separate service, while pure Apps-Engine apps run inside the platform. Use Bot Bridge when you want to keep your bot code independent or use a language/framework Apps-Engine doesn’t support.
What programming languages can I use with Bot Bridge?
Any language that can handle HTTP requests works. The project includes ready-made connectors for TypeScript, PHP with a modular plugin system, and Go. But honestly, you could write your bot in Python, Ruby, Java, or whatever you’re comfortable with—just build an HTTP endpoint that accepts the JSON payload.
How does Bot Bridge handle security and authentication?
Bot Bridge uses token-based authentication for your bot endpoints. You configure a secret token in the settings, and it includes this token in requests to your bot. Your bot verifies the token before processing messages. It also supports configurable timeouts and SSL for secure connections between Rocket.Chat and your bot service.
What data does Bot Bridge send to my bot endpoint?
It sends a JSON payload with everything you need: the message text, user info (name, ID, username), room details (ID, name, type), timestamp, and a callback URL. The callback URL is important—your bot uses it to send responses back to the chat. All the standard message metadata comes through, so you have full context.
Can I run multiple bots through one Bot Bridge instance?
Technically, you’d need separate Bot Bridge instances for each bot since each instance connects to one endpoint. But you could build a single endpoint that routes to different bot logic based on the trigger pattern or bot mention. It’s more of an architecture choice—multiple instances is cleaner, one smart endpoint is more efficient.
What happens if my bot endpoint is down or slow to respond?
Bot Bridge has configurable timeouts to prevent hanging. If your endpoint doesn’t respond within the timeout window, the request fails and users might see an error or no response. Make sure your bot handles requests quickly—if you need longer processing, acknowledge the message immediately and send the full response via the callback URL afterward.
Do I need to host Bot Bridge separately from Rocket.Chat?
No, Bot Bridge installs as an app inside your Rocket.Chat instance through Apps-Engine. It runs on your Rocket.Chat server. What you DO need to host separately is your actual bot logic—that’s the whole point. Bot Bridge just handles the connection between Rocket.Chat and wherever your bot lives.
Can Bot Bridge access private rooms and direct messages?
It depends on the bot user’s permissions. The bot account needs to be added to private rooms to see messages there. For direct messages, the bot can respond if users DM it directly. Room filtering lets you restrict which rooms the bot monitors, which is useful for keeping bots in specific channels.
Is Bot Bridge still maintained since Rocket.Chat deprecated bot integrations?
Bot Bridge was created specifically because Rocket.Chat deprecated Hubot adapters. It’s built on Apps-Engine, which is Rocket.Chat’s current recommended approach. As long as Apps-Engine is supported (and it is—it’s their primary integration platform), Bot Bridge should continue working.
