Codakey
Play
← Back to howdyai/botkit

How to Deploy & Use howdyai/botkit

# Botkit Deployment & Usage Guide

Complete guide to building, running, and deploying chatbots with Botkit (TypeScript).

## Prerequisites

- **Node.js**: v16.x LTS or higher (v18+ recommended)
- **npm**: v8.x or higher (or Yarn v1.22+)
- **Git**: For cloning the repository
- **Platform Accounts**: 
 - Slack workspace (for Slack bots) - requires Admin access to install apps
 - Webex Teams account (for Webex bots) - developer access at [developer.webex.com](https://developer.webex.com)
 - Facebook Developer account (for Messenger bots) - access to Facebook App Dashboard
- **ngrok** (for local development): Public URL tunneling for webhook testing
 ```bash
 npm install -g ngrok
 # or
 brew install ngrok

Installation

1. Clone and Setup

# Clone the repository
git clone https://github.com/howdyai/botkit.git
cd botkit

# Install dependencies (monorepo - installs all packages)
npm install

# Build TypeScript packages
npm run build

2. Create Your Bot Project

# Create a new project directory
mkdir my-bot && cd my-bot

# Initialize and install core dependencies
npm init -y
npm install botkit botbuilder

For specific platforms, install the appropriate adapter:

# Slack
npm install botbuilder-adapter-slack

# Webex Teams
npm install botbuilder-adapter-webex

# Facebook Messenger
npm install botbuilder-adapter-facebook

# Web (for custom web chat)
npm install botbuilder-adapter-web

Configuration

Environment Variables

Create a .env file in your project root:

# General
NODE_ENV=development
PORT=3000

# Slack Adapter (if using Slack)
SLACK_CLIENT_SIGNING_SECRET=your-slack-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_REDIRECT_URI=https://your-domain.com/oauth

# Webex Adapter (if using Webex)
WEBEX_ACCESS_TOKEN=your-webex-bot-token
WEBEX_SECRET=your-webhook-secret
WEBEX_PUBLIC_ADDRESS=https://your-domain.com/

# Facebook Adapter (if using Messenger)
FACEBOOK_VERIFY_TOKEN=your-verify-token
FACEBOOK_APP_SECRET=your-app-secret
FACEBOOK_ACCESS_TOKEN=your-page-access-token

Bot Configuration (TypeScript)

Create bot.ts:

import { Botkit } from 'botkit';
import { SlackAdapter } from 'botbuilder-adapter-slack';
// import { WebexAdapter } from 'botbuilder-adapter-webex';
// import { FacebookAdapter } from 'botbuilder-adapter-facebook';
import * as dotenv from 'dotenv';

dotenv.config();

// Configure Adapter
const adapter = new SlackAdapter({
    clientSigningSecret: process.env.SLACK_CLIENT_SIGNING_SECRET,
    botToken: process.env.SLACK_BOT_TOKEN,
    clientId: process.env.SLACK_CLIENT_ID,
    clientSecret: process.env.SLACK_CLIENT_SECRET,
    redirectUri: process.env.SLACK_REDIRECT_URI,
    // For multi-team apps, use getTokenForTeam instead of botToken
});

// Initialize Botkit
const controller = new Botkit({
    webhook_uri: '/api/messages',
    adapter: adapter,
    // Optional: configure storage (default is MemoryStorage - not for production)
    // storage: new MongoDbStorage({...})
});

// Define conversation handlers
controller.on('message', async (bot, message) => {
    await bot.reply(message, 'I heard you say: ' + message.text);
});

// Start server
controller.ready(() => {
    console.log('Botkit app started');
});

Build & Run

Development Mode

# Compile TypeScript
npx tsc bot.ts --esModuleInterop --outDir ./dist

# Run with auto-reload (optional)
npm install -g ts-node
ts-node bot.ts

Webhook Testing with ngrok

Since messaging platforms require public HTTPS URLs:

# Terminal 1: Start your bot
node dist/bot.js
# Server starts on port 3000

# Terminal 2: Expose to internet
ngrok http 3000

# Copy the https URL (e.g., https://abc123.ngrok.io)
# Configure in platform:
# Slack: Event Subscriptions → Request URL: https://abc123.ngrok.io/api/messages
# Webex: Webhook URL: https://abc123.ngrok.io/api/messages
# Facebook: Webhooks → Callback URL: https://abc123.ngrok.io/api/messages

Production Mode

# Set environment
export NODE_ENV=production

# Build optimized version
npm run build

# Start
node dist/bot.js

Critical Production Requirements:

  • Replace MemoryStorage with persistent storage (MongoDB, Redis, etc.)
  • Use proper SSL/TLS termination (platforms require HTTPS webhooks)
  • Set webhook_uri to your production domain path (e.g., /api/messages)

Deployment

Heroku (Recommended for quick deployment)

# Install Heroku CLI and login
heroku create my-botkit-app

# Set environment variables
heroku config:set SLACK_CLIENT_SIGNING_SECRET=xxx
heroku config:set SLACK_BOT_TOKEN=xxx
heroku config:set NODE_ENV=production

# Deploy
git push heroku main

# Configure webhooks in platform to point to:
# https://my-botkit-app.herokuapp.com/api/messages

Procfile:

web: node dist/bot.js

Docker

Create Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/bot.js"]

Build and run:

docker build -t botkit-app .
docker run -p 3000:3000 --env-file .env botkit-app

AWS (Elastic Beanstalk)

  1. Create package.json with start script: "start": "node dist/bot.js"
  2. Zip your code (excluding node_modules)
  3. Upload to EB with Node.js platform
  4. Configure environment variables in EB Console → Configuration → Software

Azure

Use Azure App Service with Node.js runtime:

  • Runtime stack: Node 18 LTS
  • Startup command: node dist/bot.js
  • Enable WebSockets (for real-time features)
  • Configure Application Settings for environment variables

Troubleshooting

Webhook Verification Failures

Issue: Platform returns "challenge failed" or 403 errors

  • Slack: Verify clientSigningSecret matches Slack App's "Signing Secret"
  • Facebook: Ensure verify_token matches exactly; check app_secret for signature validation
  • Webex: Confirm secret matches the webhook secret configured in Webex developer portal

"Cannot find module" Errors

# Rebuild TypeScript after changes
npm run build

# For monorepo development, ensure all packages are built
cd /path/to/botkit
npm run build

Storage Warnings

Warning: MemoryStorage is not recommended for production

  • Solution: Implement persistent storage:
import { MongoDbStorage } from 'botbuilder-storage-mongodb';
// or Redis, Azure Blob, etc.

const controller = new Botkit({
    storage: new MongoDbStorage({ url: process.env.MONGO_URI }),
    // ...
});

Port Binding Issues

Error: EADDRINUSE or platform cannot reach bot

  • Ensure PORT environment variable matches what your platform expects (Heroku assigns ports dynamically)
  • Check firewall rules for port 3000 (local) or 443 (production)

Message Format Errors

Issue: Messages appear malformed on platform

  • Verify adapter version matches Botkit core version
  • Check platform-specific message formats (Slack blocks vs Facebook templates)

Debug Mode

Enable detailed logging:

DEBUG=botkit* node dist/bot.js

This outputs all internal routing, message processing, and adapter translation logs.

← Project overviewView alternatives to howdyai/botkit →