Version: 0.5.0 Last Updated: January 2026

Complete guide to setting up and using integrations and webhooks in nself-chat.

1. Overview
2. Supported Integrations
3. Slack Integration
4. Discord Integration
5. Telegram Integration
6. GitHub Integration
7. Jira Integration
8. Incoming Webhooks
9. Outgoing Webhooks
10. Webhook Queue System
11. Database Schema
12. API Reference

nself-chat provides a comprehensive integration system that supports:

• OAuth-based integrations with popular services
• Bidirectional message sync between platforms
• Incoming webhooks to receive events from external services
• Outgoing webhooks to send events to external services
• Webhook queue with retry logic and rate limiting
• Import wizards for bulk message/channel imports

┌─────────────────┐
│  nself-chat     │
│  ┌───────────┐  │       ┌──────────┐
│  │ Outgoing  │──┼──────>│ External │
│  │ Webhooks  │  │       │ Services │
│  └───────────┘  │       └──────────┘
│                 │             │
│  ┌───────────┐  │             │
│  │ Incoming  │<─┼─────────────┘
│  │ Webhooks  │  │
│  └───────────┘  │
│                 │
│  ┌───────────┐  │       ┌──────────┐
│  │Integration│<─┼──────>│  Redis   │
│  │  Queue    │  │       │  Queue   │
│  └───────────┘  │       └──────────┘
└─────────────────┘

1. Create Slack App:

   • Go to https://api.slack.com/apps
   • Click "Create New App"
   • Choose "From scratch"
   • Enter app name and workspace

2. Configure OAuth:

   • Navigate to "OAuth & Permissions"
   • Add redirect URL: https://your-domain.com/api/auth/oauth/callback
   • Add scopes:
     • channels:history
     • channels:read
     • chat:write
     • files:read
     • users:read
     • users:read.email

3. Install App:

   • Install to workspace
   • Copy OAuth tokens

4. Setup Webhook (Optional):

   • Navigate to "Event Subscriptions"
   • Enable events
   • Set Request URL: https://your-domain.com/api/webhooks/slack
   • Subscribe to bot events:
     • message.channels
     • reaction_added
     • channel_created

import { createSlackProvider } from '@/lib/integrations/slack/slack-client'

const provider = createSlackProvider({
  clientId: process.env.SLACK_CLIENT_ID!,
  clientSecret: process.env.SLACK_CLIENT_SECRET!,
  redirectUri: 'https://your-domain.com/api/auth/oauth/callback',
})

// Import history
const result = await provider.importHistory(credentials, {
  channelIds: ['C1234567890'],
  startDate: '2024-01-01',
  endDate: '2024-12-31',
})

• Messages posted in nself-chat → forwarded to Slack
• Messages posted in Slack → received via webhook → posted to nself-chat

1. Create Discord Application:

   • Go to https://discord.com/developers/applications
   • Click "New Application"
   • Enter application name

2. Configure Bot:

   • Navigate to "Bot" section
   • Create bot user
   • Copy bot token
   • Enable required intents:
     • Presence Intent
     • Server Members Intent
     • Message Content Intent

3. Configure OAuth2:

   • Navigate to "OAuth2" section
   • Add redirect URL: https://your-domain.com/api/auth/oauth/callback
   • Select scopes: bot, identify, guilds
   • Select bot permissions: Read Messages, Send Messages, etc.

4. Invite Bot:

   • Use OAuth2 URL generator to create invite link
   • Invite bot to your Discord server

import { createDiscordProvider } from '@/lib/integrations/discord/discord-client'

const provider = createDiscordProvider({
  clientId: process.env.DISCORD_CLIENT_ID!,
  clientSecret: process.env.DISCORD_CLIENT_SECRET!,
  botToken: process.env.DISCORD_BOT_TOKEN!,
  redirectUri: 'https://your-domain.com/api/auth/oauth/callback',
})

// Import history
const result = await provider.importHistory(credentials, {
  guildIds: ['123456789012345678'],
  channelIds: ['987654321098765432'],
  startDate: '2024-01-01',
})

Discord primarily uses Gateway WebSocket for bot events, but you can also use channel webhooks:

# Create Discord webhook
curl -X POST "https://your-domain.com/api/webhooks/discord" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello from external service!"}'

1. Create Bot:

   • Message @BotFather on Telegram
   • Send /newbot command
   • Follow prompts to create bot
   • Copy bot token

2. Setup Webhook:

   curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
     -d "url=https://your-domain.com/api/webhooks/telegram&secret_token=<YOUR_SECRET>"

3. Configure in nself-chat:

   • No OAuth needed (uses bot token directly)
   • Store bot token in environment variable

⚠️ Limitations:

• Telegram Bot API cannot fetch historical messages
• Bots can only see messages sent after they were added to the chat
• For full history import, you'd need MTProto API (user account)
• Messages sync in real-time via webhook

import { createTelegramProvider } from '@/lib/integrations/telegram/telegram-client'

const provider = createTelegramProvider({
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
  webhookUrl: 'https://your-domain.com/api/webhooks/telegram',
})

// Send message to chat
await provider.forwardMessage(
  credentials,
  -1001234567890, // Chat ID
  'Hello from nself-chat!'
)

1. Create GitHub OAuth App:

   • Go to https://github.com/settings/developers
   • Click "New OAuth App"
   • Set Authorization callback URL: https://your-domain.com/api/auth/oauth/callback

2. Setup Webhook:

   • Go to repository settings
   • Navigate to Webhooks
   • Add webhook URL: https://your-domain.com/api/webhooks/github
   • Select events: push, pull_request, issues, etc.
   • Add secret for signature verification

• push - Code pushed to repository
• pull_request - PR opened, closed, merged
• issues - Issues created, updated, closed
• issue_comment - Comments on issues/PRs
• pull_request_review - PR reviews
• release - New release created
• deployment - Deployment events

const client = provider.getClient(credentials)
const issue = await client.createIssue('owner', 'repo', {
  title: 'Bug report from chat',
  body: 'Issue details from message...',
  labels: ['bug', 'from-chat'],
})

1. Create Jira OAuth App:

   • Go to https://developer.atlassian.com/console/myapps/
   • Create new app
   • Configure OAuth 2.0
   • Add callback URL: https://your-domain.com/api/auth/oauth/callback

2. Setup Webhook:

   • Log in to Jira as admin
   • Go to Settings > System > WebHooks
   • Create webhook with URL: https://your-domain.com/api/webhooks/jira
   • Select events: issue created, updated, etc.

• jira:issue_created
• jira:issue_updated
• comment_created
• worklog_created
• sprint_started
• sprint_closed

const client = provider.getClient(credentials)
const issue = await client.createIssue('PROJECT', {
  summary: 'Task from chat',
  description: 'Details...',
  issueType: 'Task',
})

Incoming webhooks allow external services to POST messages to nself-chat channels.

import { getIncomingWebhookManager } from '@/lib/webhooks/incoming-webhooks'

const manager = getIncomingWebhookManager()
const webhook = manager.createWebhook({
  name: 'External Service Webhook',
  targetChannelId: 'channel-uuid',
  enabled: true,
})

// Webhook URL
const url = `https://your-domain.com/api/webhooks/incoming/${webhook.token}`

curl -X POST "https://your-domain.com/api/webhooks/incoming/<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from external service!",
    "username": "External Bot",
    "icon_url": "https://example.com/icon.png"
  }'

Outgoing webhooks send nself-chat events to external services.

import { getOutgoingWebhookManager } from '@/lib/webhooks/outgoing-webhooks'

const manager = getOutgoingWebhookManager()
const webhook = manager.createWebhook({
  name: 'External Service',
  url: 'https://external-service.com/webhook',
  secret: 'your-secret-key',
  events: ['message.created', 'channel.created', 'user.joined'],
})

import { triggerWebhookEvent } from '@/lib/webhooks/outgoing-webhooks'

await triggerWebhookEvent(
  'message.created',
  {
    messageId: '123',
    channelId: '456',
    content: 'Hello!',
    author: { id: '789', username: 'user' },
  },
  {
    userId: '789',
    username: 'user',
  }
)

Outgoing webhooks include HMAC-SHA256 signature in X-Webhook-Signature header:

// Verify signature (Node.js example)
import crypto from 'crypto'

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
  const hmac = crypto.createHmac('sha256', secret)
  const digest = 'sha256=' + hmac.update(payload).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest))
}

Webhooks use BullMQ + Redis for reliable delivery with retry logic.

import { initializeWebhookQueue } from '@/lib/webhooks/webhook-queue'

const manager = initializeWebhookQueue({
  redis: {
    host: 'localhost',
    port: 6379,
    password: process.env.REDIS_PASSWORD,
  },
  concurrency: 10,
  maxRetries: 3,
  retryDelay: 5000, // 5 seconds
  timeout: 30000, // 30 seconds
})

• Automatic Retries: Exponential backoff (5s, 10s, 20s)
• Rate Limiting: Configurable concurrency
• Delivery Tracking: Full audit log of all attempts
• Dead Letter Queue: Failed deliveries after max retries
• Statistics: Real-time queue metrics

const stats = await manager.getStats()
console.log(stats)
// {
//   total: 1000,
//   pending: 50,
//   active: 10,
//   completed: 900,
//   failed: 40,
//   delayed: 0
// }

• nchat_integrations - Integration configurations
• nchat_integration_mappings - Resource mappings (external ↔ internal)
• nchat_outgoing_webhooks - Outgoing webhook configs
• nchat_webhook_deliveries - Delivery log
• nchat_incoming_webhooks - Incoming webhook configs
• nchat_integration_imports - Import job tracking
• nchat_integration_sync_queue - Sync operation queue

-- Get all active integrations
SELECT * FROM nchat_integrations
WHERE status = 'connected';

-- Get webhook delivery stats
SELECT
  webhook_id,
  COUNT(*) as total,
  SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as successful,
  SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failed
FROM nchat_webhook_deliveries
GROUP BY webhook_id;

-- Get pending sync operations
SELECT * FROM nchat_integration_sync_queue
WHERE status = 'pending'
AND scheduled_for <= NOW()
ORDER BY scheduled_for ASC
LIMIT 100;

• POST /api/auth/oauth/connect - Start OAuth flow
• GET /api/auth/oauth/callback - Handle OAuth callback
• POST /api/integrations/:id/disconnect - Disconnect integration
• POST /api/integrations/:id/import - Start import job
• GET /api/integrations/:id/status - Get integration status

• POST /api/webhooks/incoming/:token - Receive incoming webhook
• POST /api/webhooks/github - GitHub webhook
• POST /api/webhooks/slack - Slack webhook
• POST /api/webhooks/discord - Discord webhook
• POST /api/webhooks/telegram - Telegram webhook
• POST /api/webhooks/jira - Jira webhook

1. Always verify webhook signatures for incoming webhooks
2. Use HTTPS for all webhook URLs
3. Rotate secrets regularly
4. IP whitelist when possible
5. Rate limit webhook endpoints

1. Use webhook queue for all outgoing webhooks
2. Batch imports for large message histories
3. Set concurrency limits to avoid overwhelming external APIs
4. Monitor queue depth and adjust workers

1. Log all webhook failures with full context
2. Implement dead letter queue for manual review
3. Alert on repeated failures
4. Provide retry mechanism for transient failures

OAuth Callback Not Working:

• Verify redirect URI matches exactly
• Check OAuth app credentials
• Ensure callback endpoint is accessible

Webhooks Not Delivering:

• Check webhook queue is running
• Verify Redis connection
• Check network connectivity
• Review webhook logs

Import Failing:

• Verify API permissions/scopes
• Check rate limits
• Ensure date ranges are valid
• Review error logs

Enable debug logging:

DEBUG=integrations:* npm run dev

For issues or questions:

• GitHub Issues: https://github.com/your-org/nself-chat/issues
• Documentation: https://docs.nself-chat.com
• Community: https://community.nself-chat.com