Skip to main content

​
Getting Started

This guide will walk you through installing Chat SDK and creating your first bot.

​
Installation

1

Install the core SDK

First, install the core chat package:
npm install chat
2

Install platform adapters

Install adapters for the platforms you want to support:
npm install @chat-adapter/slack @chat-adapter/teams @chat-adapter/gchat
You only need to install adapters for platforms you plan to use. Each adapter is a separate package:
  • @chat-adapter/slack - Slack
  • @chat-adapter/teams - Microsoft Teams
  • @chat-adapter/gchat - Google Chat
  • @chat-adapter/discord - Discord
  • @chat-adapter/telegram - Telegram
  • @chat-adapter/github - GitHub
  • @chat-adapter/linear - Linear
3

Install a state adapter

Install a state adapter for persistence:
npm install @chat-adapter/state-redis
Use @chat-adapter/state-memory only for development and testing. It stores state in memory and will lose all data on restart. For production, use @chat-adapter/state-redis or @chat-adapter/state-ioredis.

​
Quick Start

​
Create Your Bot

Create a new file bot.ts and initialize your bot:
bot.ts
import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createRedisState } from "@chat-adapter/state-redis";

export const bot = new Chat({
  userName: "mybot",
  adapters: {
    slack: createSlackAdapter(),
  },
  state: createRedisState(),
});

// Respond to @mentions
bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post("Hello! I'm listening to this thread.");
});

// Handle messages in subscribed threads
bot.onSubscribedMessage(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});

​
Environment Variables

Configure your platform credentials via environment variables:
.env
# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret

# Microsoft Teams (optional)
TEAMS_APP_ID=your-app-id
TEAMS_APP_PASSWORD=your-app-password
TEAMS_APP_TENANT_ID=your-tenant-id

# Google Chat (optional)
GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}

# Redis
REDIS_URL=redis://localhost:6379
Adapter constructors automatically read credentials from environment variables. You can also pass them explicitly as options.

​
Set Up Webhook Handlers

Create webhook endpoints for each platform. Here’s an example using Next.js App Router:
app/api/webhooks/slack/route.ts
import { bot } from "@/lib/bot";
import { after } from "next/server";

export async function POST(request: Request) {
  return bot.webhooks.slack(request, {
    waitUntil: (p) => after(() => p),
  });
}

import { bot } from "@/lib/bot";
import { after } from "next/server";

export async function POST(request: Request) {
  return bot.webhooks.slack(request, {
    waitUntil: (p) => after(() => p),
  });
}
The waitUntil option ensures webhook responses are fast (< 3 seconds) while message processing continues in the background. This is critical for platforms like Slack that retry if responses are slow.

​
Platform Configuration

Each platform requires specific configuration:
1

Slack

  1. Create a Slack app at api.slack.com/apps
  2. Enable Socket Mode or configure Event Subscriptions
  3. Add bot scopes: app_mentions:read, chat:write, channels:history
  4. Set your webhook URL to https://your-domain.com/api/webhooks/slack
  5. Install the app to your workspace
2

Microsoft Teams

  1. Register your app in Azure AD
  2. Create a Teams app manifest with your bot ID
  3. Configure messaging endpoint: https://your-domain.com/api/webhooks/teams
  4. Upload the app to Teams
3

Google Chat

  1. Create a Google Cloud project
  2. Enable Google Chat API
  3. Create a service account and download credentials JSON
  4. Configure webhook URL: https://your-domain.com/api/webhooks/gchat
  5. Publish the app

​
Verify Installation

Test your bot by:
  1. Starting your local server
  2. Using a tool like ngrok to expose your localhost
  3. Configuring your platform webhook URL to the ngrok URL
  4. @mentioning your bot in a channel
You should see your bot respond with “Hello! I’m listening to this thread.”

​
Next Steps

Basic Usage

Learn core concepts and event handlers

Event Handlers

Handle mentions, messages, reactions, and more

AI Streaming

Stream LLM responses to your chat

Interactive Cards

Build rich UI with buttons and modals