IM Integration
Table of contents
- Supported Platforms
- Common Features
- Configuration
- Platform Comparison
- Platform-Specific Notes
- Workflow
- Message Flow
- Contributing New Integrations
- Next Steps
chat.nvim supports integration with multiple instant messaging platforms for remote AI interaction. This allows you to interact with AI assistants from your favorite messaging apps.
Supported Platforms
| Platform | Icon | Bidirectional | Features |
|---|---|---|---|
| Discord | 💬 | ✅ Yes | Full-featured bot with session binding |
| Lark | 🐦 | ✅ Yes | Feishu/Lark bot with message polling |
| DingTalk | 📱 | ✅ Yes* | Webhook (one-way) or API (two-way) |
| WeCom | 💼 | ✅ Yes* | Enterprise WeChat webhook or API |
| Weixin | 💬 | ✅ Yes* | Personal WeChat via external API |
| Telegram | ✈️ | ✅ Yes | Bot API with group/private chat support |
| Slack | 💼 | ✅ Yes | Workspace bot with message polling |
*Webhook mode is one-way only; API mode supports bidirectional communication.
Common Features
All IM integrations share these common features:
Commands
:Chat bridge <platform>- Bind current session to platform:Chat unbridge [platform]- Unbind integration (all or specific platform)/session [number|id]- Check/update session binding/list [pattern] [-p N]- List available sessions (optional pattern filter,-p Nselects page N)/clear- Clear current session messages
/list pagination
Sessions are listed 10 per page and rendered as a markdown ordered list
(1., 2., …) so chat clients display them as a real numbered list. The
numbering is global: page 2 starts at 11., it does not restart at 1.,
so a number always identifies the same session no matter which page it was
read on. That means /session 12 binds session 12 even while page 1 is still
on screen — the number comes from the last /list of the current chat, not
from the rendered page.
-p is a flag rather than a bare number because session ids are date-shaped
strings full of digits: /list 2 would be ambiguous between “page 2” and
“search for 2”.
/list # page 1 of everything
/list -p 2 # page 2
/list refactor # page 1 of the matches
/list refactor -p 2 # page 2 of the matches
The footer names the page and the neighbouring pages, and the command shown is copy-pasteable:
Total: 137 session(s)
Page 1/14 · next: /list -p 2
Patterns are matched as plain text, so a title containing +, % or ( is
searched literally instead of being interpreted as a Lua pattern.
The published numbering is per chat: two people running /list in two
different chats do not overwrite each other’s /session <n> numbering.
Bridge Semantics
One rule covers every entry point (:Chat bridge, :Chat unbridge,
/session, GET|PUT|DELETE /session/:id/bridge):
- Binding replaces. Bridging a session drops whatever that platform pointed at before, so a per-chat binding can never outlive the session it was created under.
- Unbinding clears both levels. Platform-level and per-chat bindings for the session are dropped together. After unbridging, the integration really stops replying — it is not merely hidden from the title bar.
- Display matches routing. The window title badge,
GET /session/:id/bridgeand the actual reply routing all read the same binding table, so a session that receives replies always shows as bridged. - Failures are reported.
:Chat bridgesays whether the platform is unknown, whether there is no session, or that the bridge succeeded — the same distinction the HTTP route returns (falsevsnil).:Chat unbridgewith nothing bound reports “Nothing bound to current session” instead of claiming success.
Technical Details
- Message Queue: Sequential processing to prevent race conditions
- State Persistence: JSON files in
stdpath('data') - Auto-reconnect: Automatic recovery from network issues
- Timeout Protection: 5-second request timeout
Configuration
Configure IM integrations in your chat.nvim setup:
require('chat').setup({
integrations = {
-- Discord
discord = {
token = 'YOUR_DISCORD_BOT_TOKEN',
channel_id = 'YOUR_CHANNEL_ID',
-- Optional: more guild channels (own cursor + session each)
channel_ids = { 'ANOTHER_CHANNEL_ID' },
-- Optional: register every text channel of this guild on connect
guild_id = 'YOUR_GUILD_ID',
-- Optional: private (DM) chats, one session + workspace per peer
p2p = {
enable = true,
-- Omit `allow` to serve every DM channel the bot can see.
allow = { 'USER_ID_ALLOWED_TO_DM' },
cwd_root = '/path/to/projects',
},
},
-- Telegram
telegram = {
bot_token = 'YOUR_BOT_TOKEN',
chat_id = 'YOUR_CHAT_ID',
},
-- Slack
slack = {
bot_token = 'xoxb-YOUR-BOT-TOKEN',
channel_id = 'CXXXXXXXXXX',
},
-- Lark (Feishu)
lark = {
app_id = 'YOUR_APP_ID',
app_secret = 'YOUR_APP_SECRET',
chat_id = 'YOUR_CHAT_ID',
},
-- DingTalk
dingtalk = {
webhook = 'https://oapi.dingtalk.com/robot/send?access_token=XXX',
},
-- WeCom (Enterprise WeChat)
wecom = {
webhook_key = 'YOUR_WEBHOOK_KEY',
},
},
})
Only configure the platforms you plan to use. Others can be omitted.
Platform Comparison
| Platform | Mode | Bidirectional | Setup Complexity | Message Limit |
|---|---|---|---|---|
| Discord | Bot API | ✅ Yes | Medium | 2,000 chars |
| Lark | Bot API | ✅ Yes | Medium | 30,720 chars |
| DingTalk | Webhook | ❌ No | Low | 20,000 chars |
| DingTalk | API | ✅ Yes | High | 20,000 chars |
| WeCom | Webhook | ❌ No | Low | 2,048 chars |
| WeCom | API | ✅ Yes | High | 2,048 chars |
| Telegram | Bot API | ✅ Yes | Low | 4,096 chars |
| Slack | Bot API | ✅ Yes | Medium | 40,000 chars |
Platform-Specific Notes
Discord
- Requires “Message Content Intent” enabled
- Bot must be mentioned or replied to in group chats
- Private channels require direct messages
Lark
- Requires app approval for production use
- Tenant access token is auto-refreshed
- Supports rich message types (text, cards, etc.)
DingTalk
- Webhook mode is simplest but one-way only
- API mode requires enterprise app registration
- Stream mode recommended for bidirectional communication
WeCom
- Webhook mode is simplest but one-way only
- API mode requires corporate approval
- Internal apps have more permissions
Telegram
- Works in both private and group chats
- Groups require bot to be admin for some features
- Supports inline queries and callbacks
Slack
- Bot must be invited to channels
- Requires specific OAuth scopes
- Responds to @mentions and thread replies
Workflow
The general workflow for IM integration:
- Configure the platform in your chat.nvim setup
- Open chat.nvim and create/start a session
- Run
:Chat bridge <platform>to bind the session - In the messaging app, interact with the bot
- AI response will be sent back automatically
Session Binding: The
:Chat bridgecommand connects your current chat.nvim session to the messaging platform, allowing messages from the platform to be processed by that specific session. Platforms that can address a single chat (currently Lark) may bind each conversation separately; for every other platform the whole integration is bound at once.
Message Flow
Sending Messages
- User sends message in IM platform
- Integration polls for new messages (every 3 seconds)
- Message is queued in chat.nvim
- Message is processed by the bound session
- AI response is generated
- Response is sent back to IM platform
Auto-chunking
Messages that exceed platform limits are automatically split:
- Discord: 2,000 character chunks
- Telegram: 4,096 character chunks
- Slack: 40,000 character chunks
- Lark: 30,720 character chunks
- DingTalk: 20,000 character chunks
- WeCom/Weixin: 2,048 character chunks
Contributing New Integrations
To add a new IM platform integration:
1. Create Integration Module
Create lua/chat/integrations/<platform>.lua
2. Implement Required Functions
local M = {}
-- Start listening for messages
function M.connect(callback)
-- Implementation
end
-- Stop listening
function M.disconnect()
-- Implementation
end
-- Send message
--
-- The second argument is optional and platform-specific. Only declare it
-- (and its meaning) when this platform can address a single chat, e.g.
-- Lark's `send_message(content, session)`. The shared layer passes a routing
-- hint ONLY to platforms that declare `M.bridge` with `bind_chat`/`chats`;
-- every other platform is called as `send_message(content)`. Do not repurpose
-- the second parameter for something else (weixin used it as a `user_id`),
-- or command replies will silently target the wrong recipient.
function M.send_message(content)
-- Implementation
end
-- Get current session ID
function M.current_session()
-- Implementation
end
-- Set current session
function M.set_session(session)
-- Implementation
end
-- Cleanup resources
function M.cleanup()
-- Implementation
end
return M
3. Register Integration
Update lua/chat/integrations/init.lua:
local integrations = {
discord = require('chat.integrations.discord'),
telegram = require('chat.integrations.telegram'),
-- Add your new integration
my_platform = require('chat.integrations.my_platform'),
}
4. Add Documentation
Add documentation to:
- README.md IM Integration section
- docs/integrations/
.md
Reference Implementation
Two shapes are in use, both fully supported:
- Single file —
lua/chat/integrations/telegram.luaand friends: one module for a bot that serves a fixed chat. - Module directory —
lua/chat/integrations/discord/andlua/chat/integrations/lark/: a facade (discord.lua) over per-concern submodules (util,state,http,container,discover,send,poll). This is what a platform needs when it serves several chats at once — one cursor, one session and one admission policy per container.
Start from lua/chat/integrations/discord.lua for the facade and contract, and
lua/chat/integrations/discord/container.lua for the per-chat binding model.
Next Steps
- Discord Integration - Setup Discord bot
- Telegram Integration - Setup Telegram bot
- Slack Integration - Setup Slack bot
- Lark Integration - Setup Lark/Feishu bot
- DingTalk Integration - Setup DingTalk webhook/API
- WeCom Integration - Setup WeCom webhook/API
- Weixin Integration - Setup personal WeChat via QR login
- HTTP API - HTTP API integration