Vocechat
This document was written by AI and has been manually reviewed.
The VoceChat driver bridges a self-hosted VoceChat server with the rest of your platforms. It runs an HTTP webhook endpoint that VoceChat calls for incoming messages, and sends via the Bot REST API.
No extra Python packages are needed beyond what NextBridge already uses.
Setup#
1. Create a bot and get the API key#
Log in to VoceChat as an admin and go to Settings → Bots.
Click New Bot, fill in a name and description.
Copy the generated API Key — this is your api_key config value.
2. Configure the webhook URL#
In the bot settings, set the Webhook URL to your NextBridge endpoint, e.g. https://example.com/vocechat/webhook
VoceChat will send a GET request to verify the URL returns HTTP 200. NextBridge handles this automatically.
3. Add the bot to channels#
For each channel the bot should bridge, go to the channel settings in VoceChat, click Add Bot, and select your bot.
The webhook endpoint must be reachable from the VoceChat server. Use a reverse proxy or ngrok / Cloudflare Tunnel for development.
Config keys#
Add under vocechat.<instance_id> in your config file:
| server_url | Yes | — | Base URL of the VoceChat server, e.g. "https://chat.example.com" |
| api_key | Yes | — | Bot API key from the bot settings page |
| listen_port | No | 8091 | HTTP port the webhook listens on |
| listen_path | No | "/vocechat/webhook" | HTTP path for the webhook endpoint |
| max_file_size | No | 52428800 (50 MB) | Maximum attachment size in bytes |
| proxy | No | — | Proxy URL for all VoceChat API requests (e.g., http://proxy.example.com:8080 or socks5://proxy.example.com:1080). Set to null to explicitly disable proxy for this instance (ignores global proxy setting). |
{
"vocechat": {
"vc_main": {
"server_url": "https://chat.example.com",
"api_key": "your-bot-api-key",
"listen_port": 8091
}
}
}Rule channel keys#
Exactly one of gid or uid is required per channel entry:
| gid | VoceChat group (channel) ID — integer |
| uid | VoceChat user ID for direct messages — integer |
The channel ID appears in the URL when you open the channel in VoceChat (/channel/{gid}). The user ID is visible in user profile URLs.
{
"vc_main": {
"gid": 2
}
}For direct messages:
{
"vc_main": {
"uid": 7910
}
}How it works#
Receive: VoceChat POSTs a JSON event to the webhook endpoint for each new message. The driver:
Responds immediately with HTTP 200 and dispatches processing in the background
Handles both text/plain and text/markdown content types as text
Downloads vocechat/file attachments from /api/resource/file?path={path} and forwards the bytes
Skips edits, deletions, and system events (only normal and reply types are bridged)
For direct messages, routes back using the sender’s uid as the channel
Send: For each outgoing message the driver:
Sends text to POST /api/bot/send_to_group/{gid} or /api/bot/send_to_user/{uid} with Content-Type: text/plain (or text/markdown when a rich header is present)
Uploads binary attachments first via POST /api/bot/file/upload, then sends a vocechat/file reference message
Falls back to a text label [Type: filename] when upload fails
Notes#
The x-api-key header is used for all outbound API calls.
Markdown formatting is supported by VoceChat. The rich_header prefix uses **bold** and *italic* and is sent with Content-Type: text/markdown.
Multiple bots can be added to the same channel. The driver will receive events from all users, including other bots — configure VoceChat’s bot permissions to restrict this if needed.
No extra Python packages are required — only aiohttp which NextBridge already depends on.