Bot Platform Plugins

Add custom messaging-platform bots to PraisonAI via Python entry points

Bot platform adapters now ship in the praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.

from praisonaiagents import Agent

agent = Agent(name="platform-bot", instructions="Use platform-specific bot plugins.")
agent.start("Enable Telegram and Discord plugins for this bot.")

Third-party bot packages can register via Python entry points to extend PraisonAI with custom messaging platforms.

The user installs a third-party bot package; entry points register new platforms alongside built-in channels.

Quick Start

1. Programmatic Registration

   Register a bot platform directly in your code:

   from praisonai.bots._registry import register_platform
   
   class MyBot:
       def __init__(self, **kwargs):
           self.kwargs = kwargs
       
       async def start(self):
           print("Starting MyBot...")
       
       async def stop(self):
           print("Stopping MyBot...")
   
   register_platform("mybot", MyBot)
   
2. Entry-point Plugin

   Create a pip-installable plugin using pyproject.toml:

   # pyproject.toml
   [project.entry-points."praisonai.channels"]
   mybot = "my_pkg.bot:MyBot"
   

   After installation, use the bot platform:

   from praisonai.bots import Bot
   
   bot = Bot("mybot", agent=my_agent)
   await bot.start()
   

---

How It Works

The bot platform registry provides a central point for managing bot implementations:

Operation	Description	When Called
Discovery	Entry points auto-loaded on registry access	Import time
Registration	Bot platforms registered by name	Plugin installation
Creation	Bot instances created on demand	Bot() constructor
Availability	Platform dependencies checked	Before execution

---

Configuration

The bot platform registry supports both programmatic and entry-point registration:

Function	Purpose
register_platform(name, cls, capabilities=None)	Register at runtime (optional PlatformCapabilities descriptor)
get_platform_capabilities(name)	Get the capabilities descriptor for a registered platform
list_platforms()	List all registered platform names
resolve_adapter(name)	Get class for a platform name
get_platform_registry()	Backward-compat: returns dict[name, class] of all platforms
get_default_bot_registry()	Get the process-default BotPlatformRegistry (advanced)

Built-in Platforms

PraisonAI includes these built-in bot platforms:

• telegram - Telegram bot integration
• discord - Discord bot integration
• slack - Slack bot integration
• whatsapp - WhatsApp bot integration
• linear - Linear issues integration
• email - Email bot integration
• agentmail - AgentMail integration

Entry-point Groups

Group	Purpose
praisonai.channels	Recommended for new packaged connectors — idiomatic, zero-config auto-registration
praisonai.bots	Legacy group — still scanned for backward compatibility

Both groups are scanned by BotPlatformRegistry on startup. A connector that would shadow a built-in platform is skipped with a warning.

Discovery via entry points (praisonai.channels)

Plugin channels are accepted on both praisonai bot serve and praisonai gateway start (from PR #3019 / PraisonAI 2026-07-14). Older gateway builds only accepted the built-in six platforms at runtime and silently warned on plugin platforms.

The praisonai.channels entry-point group is the idiomatic way to distribute a bot connector as a pip-installable package. Once installed, the platform is available with no extra Python code:

# pyproject.toml of your connector package
[project.entry-points."praisonai.channels"]
irc = "praisonai_irc:IRCBot"

After pip install praisonai-irc:

from praisonai.bots import Bot

bot = Bot("irc", agent=my_agent, server="irc.libera.chat")
await bot.start()

List all registered platforms — built-in, entry-point, and custom — with the CLI:

praisonai gateway channels --available
# => telegram, discord, slack, whatsapp, linear, email, agentmail, irc

Or in Python:

from praisonai.bots._registry import list_platforms

print(sorted(list_platforms()))

praisonai.channels is preferred over praisonai.bots for new packages. Both entry-point groups continue to work.

Plugin channel on the gateway runtime

Register a plugin platform, then reference it in gateway.yaml:

# my_plugin.py
from praisonai.bots._registry import register_platform

class MattermostBot:
    def __init__(self, **kwargs): self.cfg = kwargs
    async def start(self): ...
    async def stop(self): ...

register_platform("mattermost", MattermostBot)

# gateway.yaml
agents:
  assistant:
    instructions: "You are a helpful assistant."
channels:
  mattermost:
    token: ${MATTERMOST_TOKEN}

python -c "import my_plugin" && praisonai gateway start --config gateway.yaml
# Before PR #3019: WARNING 'mattermost' not a known platform, gateway starts, channel dead.
# After PR #3019:  gateway starts, mattermost channel runs.

---

Common Patterns

Declare Platform Capabilities

from praisonaiagents.bots import PlatformCapabilities
from praisonai.bots._registry import register_platform

register_platform(
    "mybot",
    MyBot,
    capabilities=PlatformCapabilities(
        max_message_length=2000,
        length_unit="codepoints",
        supports_edit=True,
        markdown_dialect="markdown",
    ),
)

Capabilities let PraisonAI’s shared delivery layer chunk, stream, and rate-limit messages correctly for your platform — see Bot Platform Capabilities for the full field list.

Override a Built-in Platform

Registry uses last-write-wins with lower-cased keys:

from praisonai.bots._registry import register_platform

class CustomSlackBot:
    def __init__(self, **kwargs):
        self.token = kwargs.get('token')
    
    async def start(self):
        # Custom Slack implementation
        pass
    
    async def stop(self):
        pass

# Override built-in Slack bot
register_platform("slack", CustomSlackBot)

Lazy Heavy Imports

Follow the pattern used by built-ins to avoid import-time failures:

class HeavyFrameworkBot:
    def __init__(self, **kwargs):
        self.config = kwargs
        self._client = None
    
    async def start(self):
        # Only import when actually starting
        import heavy_networking_sdk
        self._client = heavy_networking_sdk.Client(
            token=self.config.get('token')
        )
        await self._client.connect()
    
    async def stop(self):
        if self._client:
            await self._client.disconnect()

Multi-tenant Isolation

Construct your own BotPlatformRegistry to avoid leaking between tenants:

from praisonai.bots._registry import BotPlatformRegistry

# Each tenant gets their own registry
tenant_registry = BotPlatformRegistry()
tenant_registry.register("custom-slack", TenantSpecificSlackBot)

---

Best Practices

Use Lazy Imports

Never import heavy networking SDKs at module top level:

# ❌ Bad - imports at module level
import heavy_sdk

class BadBot:
    def __init__(self, **kwargs):
        self.client = heavy_sdk.Client()

# ✅ Good - lazy imports
class GoodBot:
    async def start(self):
        import heavy_sdk
        self.client = heavy_sdk.Client()

Implement Proper Protocol

Follow the expected bot lifecycle pattern:

class ProperBot:
    def __init__(self, **kwargs):
        # Store config, don't establish connections yet
        self.config = kwargs
        self.running = False
    
    async def start(self):
        # Establish connections, start listening
        self.running = True
    
    async def stop(self):
        # Clean shutdown
        self.running = False

Handle Errors Gracefully

Use logging instead of raising on initialization:

import logging
logger = logging.getLogger(__name__)

class RobustBot:
    def __init__(self, **kwargs):
        self.config = kwargs
        
    async def start(self):
        try:
            # Connection logic here
            pass
        except Exception as e:
            logger.error(f"Failed to start bot: {e}")
            # Don't re-raise, let caller handle

---

Related

Bot Platform Capabilities

Declare streaming, chunking, and rate-limit behaviour

Framework Adapter Plugins

Learn about extending PraisonAI with custom execution frameworks

Messaging Channels Strategy

See our roadmap for supported messaging platforms