Gateway & Bot Module

Build chat bots and gateway integrations for messaging platforms

Build powerful chat bots and gateway integrations for Slack, Discord, and other messaging platforms.

Quick Start

1. Create a Bot

   import { BotConfig, BotProtocol } from 'praisonai';
   
   const config: BotConfig = {
     name: "MyBot",
     token: process.env.BOT_TOKEN,
     prefix: "!",
     channels: ["general", "support"]
   };
   
2. Handle Messages

   class MyBot implements BotProtocol {
     name = "MyBot";
     config: BotConfig;
     
     constructor(config: BotConfig) {
       this.config = config;
     }
     
     async connect() {
       console.log("Bot connected!");
     }
     
     async disconnect() {
       console.log("Bot disconnected!");
     }
     
     async sendMessage(channel: string, content: string) {
       // Send message to channel
       return { id: "msg-1", content, ... };
     }
     
     onMessage(handler: (msg: BotMessage) => void) {
       // Register message handler
     }
   }
   

---

Bot Types

BotConfig

interface BotConfig {
  name: string;              // Bot name
  token?: string;            // Authentication token
  prefix?: string;           // Command prefix (e.g., "!")
  channels?: string[];       // Allowed channels
  allowedUsers?: string[];   // Allowed user IDs
  metadata?: Record<string, any>;
}

BotUser

interface BotUser {
  id: string;                // User ID
  name: string;              // Username
  displayName?: string;      // Display name
  isBot?: boolean;           // Is this a bot?
  metadata?: Record<string, any>;
}

BotChannel

interface BotChannel {
  id: string;                // Channel ID
  name: string;              // Channel name
  type: 'text' | 'voice' | 'dm' | 'group';
  metadata?: Record<string, any>;
}

BotMessage

interface BotMessage {
  id: string;                // Message ID
  content: string;           // Message content
  author: BotUser;           // Message author
  channel: BotChannel;       // Channel
  timestamp: Date;           // When sent
  attachments?: Array<{
    url: string;
    type: string;
    name?: string;
  }>;
  metadata?: Record<string, any>;
}

---

Bot Protocol

interface BotProtocol {
  name: string;
  config: BotConfig;
  
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  
  sendMessage(channel: string, content: string): Promise<BotMessage>;
  onMessage(handler: (message: BotMessage) => void | Promise<void>): void;
  
  getUser(userId: string): Promise<BotUser | null>;
  getChannel(channelId: string): Promise<BotChannel | null>;
}

---

Gateway Types

GatewayConfig

interface GatewayConfig {
  url: string;               // Gateway URL
  apiKey?: string;           // API key
  timeout?: number;          // Request timeout (ms)
  retryAttempts?: number;    // Retry count
  retryDelay?: number;       // Delay between retries (ms)
  metadata?: Record<string, any>;
}

GatewayMessage

interface GatewayMessage {
  id: string;
  type: 'request' | 'response' | 'event' | 'error';
  payload: any;
  timestamp: Date;
  correlationId?: string;
  metadata?: Record<string, any>;
}

GatewayEvent

interface GatewayEvent {
  type: string;              // Event type
  data: any;                 // Event data
  timestamp: Date;
  source?: string;           // Event source
  metadata?: Record<string, any>;
}

---

Gateway Protocol

interface GatewayProtocol {
  config: GatewayConfig;
  
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  isConnected(): boolean;
  
  send(message: GatewayMessage): Promise<void>;
  receive(): Promise<GatewayMessage | null>;
  
  onEvent(handler: (event: GatewayEvent) => void | Promise<void>): void;
  onError(handler: (error: Error) => void): void;
}

---

Failover Manager

Handle provider failover for high availability:

import { FailoverManager, FailoverConfig, ProviderStatus } from 'praisonai';

const config: FailoverConfig = {
  providers: ["openai", "anthropic", "google"],
  maxRetries: 3,
  retryDelay: 1000,
  healthCheckInterval: 30000
};

const manager = new FailoverManager(config);

// Get next available provider
const provider = manager.getNextProvider();

// Mark provider as failed
manager.markFailed("openai");

// Check provider status
const status = manager.getStatus("openai");
// Returns: ProviderStatus.HEALTHY | DEGRADED | FAILED

---

Autonomy Levels

import { AutonomyLevel } from 'praisonai';

AutonomyLevel.NONE        // No autonomous actions
AutonomyLevel.LOW         // Minimal autonomy
AutonomyLevel.MEDIUM      // Moderate autonomy
AutonomyLevel.HIGH        // High autonomy
AutonomyLevel.FULL        // Full autonomy

---

Sandbox Types

import { SandboxStatus, SandboxResult, SandboxProtocol } from 'praisonai';

// Sandbox status
SandboxStatus.IDLE
SandboxStatus.RUNNING
SandboxStatus.COMPLETED
SandboxStatus.FAILED
SandboxStatus.TIMEOUT

// Sandbox result
interface SandboxResult {
  status: SandboxStatus;
  output?: string;
  error?: string;
  executionTime?: number;
  metadata?: Record<string, any>;
}

---

Common Patterns

Slack Bot

import { BotProtocol, BotConfig, BotMessage, Agent } from 'praisonai';

class SlackBot implements BotProtocol {
  name = "SlackBot";
  config: BotConfig;
  private agent: Agent;
  
  constructor(config: BotConfig) {
    this.config = config;
    this.agent = new Agent({
      name: "SlackAssistant",
      instructions: "Help users in Slack"
    });
  }
  
  onMessage(handler: (msg: BotMessage) => void) {
    // When message received
    this.handleMessage = async (msg) => {
      if (msg.content.startsWith(this.config.prefix!)) {
        const query = msg.content.slice(1);
        const response = await this.agent.start(query);
        await this.sendMessage(msg.channel.id, response);
      }
    };
  }
}

Gateway Client

import { GatewayProtocol, GatewayConfig, GatewayMessage } from 'praisonai';

class WebSocketGateway implements GatewayProtocol {
  config: GatewayConfig;
  private ws: WebSocket | null = null;
  
  constructor(config: GatewayConfig) {
    this.config = config;
  }
  
  async connect() {
    this.ws = new WebSocket(this.config.url);
    await new Promise((resolve) => {
      this.ws!.onopen = resolve;
    });
  }
  
  async send(message: GatewayMessage) {
    this.ws?.send(JSON.stringify(message));
  }
  
  isConnected() {
    return this.ws?.readyState === WebSocket.OPEN;
  }
}

---

API Reference

BotProtocol

Bot protocol interface

GatewayProtocol

Gateway protocol interface

---

Best Practices

Use failover for reliability

Configure multiple providers with FailoverManager for high availability.

Handle disconnections gracefully

Implement reconnection logic in your bot’s connect() method.

Rate limit message handling

Add rate limiting to prevent overwhelming your agent with messages.

---

Related

Slack Bot

Build Slack integrations

Voice

Voice-enabled agents