Build on Venom Chat
Read channels and DMs, post and reply in threads, react, search, and follow chat with a change cursor from code or an agent, over REST or MCP. A team key joins as an agent member.
Venom Chat is the organisation's team chat, where people and agents are both members. Channels, DMs, messages,
threads, reactions, search, bookmarks, keyword alerts, product feeds and the channel agent are MCP tools on
/workspace/mcp/chat and REST routes under /api/v1/chat.
What you can build
- A bot that answers in threads. Poll
GET /api/v1/chat/changes(orchat_change_list) for messages that mention it, read the thread withchat_thread_get, and reply in it withPOST /api/v1/chat/channels/{channel}/messages(thread,client_id). - Announcements from your CI or deploy tool. Post a release note to
#releaseswithchat_message_createand pin it withchat_message_update(pinned). - A daily digest. Read what a member missed with
GET /api/v1/chat/unread, or search a week of a channel withGET /api/v1/chat/search(since,until). - Channel setup for a new project. Create a channel with its members (
POST /api/v1/chat/channels), have Incidents or Tasks post events to it (chat_feed_set), and add the Venom agent, or a service agent of Venom Tasks, with the tools it may use and a level of read-only or post (chat_agent_set). - Triage from chat. Open a DM or group message with
chat_dm_openand press a feed message's button (acknowledge a page, approve a flag change) withchat_feed_press.
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/chat, server name venom-chat |
| Connect | claude mcp add --transport http venom-chat https://cloud.usevenom.dev/workspace/mcp/chat |
| MCP tools | 32 (13 read, 19 write) |
| OAuth scopes | chat:read chat:write |
| REST twin | 32 routes under https://cloud.usevenom.dev/api/v1 |
| Webhook events | chat.channel.created, chat.channel.archived, chat.message.created |
Authentication and scopes
Chat always acts as one member, a person or an agent:
- A personal API key acts as that member. What it posts shows "via MCP" next to the member's name. Owner, admin and developer post; billing and viewer read. An owner's or admin's key is also a Chat admin (archive any channel, delete any message in a channel they can see). A key marked read-only reads only.
- A team key has no member, so it is an agent member named after the key, with the member key
agent:key:<id>, marked Agent. It reads every public channel, joins a public channel by posting in it, and sees a private channel or DM only after a member adds it. It posts unless the key is read-only, and is never a Chat admin. - An OAuth app acts as the member who connected it:
chat:readto read,chat:writeto post, react, edit, create channels and so on, within the member's role. - A service agent that an admin scoped to some apps reaches Chat only when Chat is one of them.
Whoever the caller is, it sees only what that member may see. A private channel it is not in answers "No channel
called …" or "No such channel", the same as one that does not exist. A credential that may not write is refused in
words, with 403 over REST. chat_channel_read (mark read) works with read-only credentials.
Chat itself has no add-on gate. Two tools do: chat_feed_set answers 402 addon_required when the org does not have
the product it would feed, and chat_file_upload stores the file in Notes, so it needs the Notes add-on.
Worked example
Reply in the thread of a message that mentioned your agent, safely retried, then pick up where you left off:
curl -X POST "$VENOM_CLOUD/api/v1/chat/channels/launch/messages" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"text": "Build 482 is green. The release notes are in #releases.", "thread": "<message-id>", "client_id": "reply-to-<message-id>"}'
curl "$VENOM_CLOUD/api/v1/chat/changes?after=4812" \
-H "Authorization: Bearer $VENOM_API_KEY"The same post over MCP, from any client connected to /workspace/mcp/chat:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "chat_message_create",
"arguments": { "channel": "launch", "text": "Build 482 is green. The release notes are in #releases.",
"thread": "<message-id>", "client_id": "reply-to-<message-id>" } } }client_id makes a retry safe: the same id returns the first message instead of posting again. Derive it from the
message you answer.
Channels, mentions and formats
- Everywhere a channel is asked for, an id or the channel's name works (
#launchorlaunch; in a REST path, use the bare name). - Messages are markdown, at most 20,000 characters. Mention a person as
@[Ana](member:ID)and an agent as@[Name](agent:ID).chat_member_listgives each member's whole key (user:IDoragent:ID). The Venom agent is@[Venom](agent:venom). - Files: upload with
chat_file_upload(at most 4 MB) and pass the ids infilesofchat_message_create, up to 10.filesis on the MCP tool only, not on the REST route. - Every tool takes
format: "json"for structured output. Rate limits are the workspace server's; see Errors, limits and pagination.
Following chat with the change cursor
chat_change_list {} → Cursor 4812
chat_change_list { after: 4812 } → No changes. Cursor 4812.
… someone posts …
chat_change_list { after: 4812 } → 4813 new [212] Ana: @[Claude](agent:key:k1) status? … Cursor 4813.Call without after to get the current cursor and nothing else, then poll with the cursor each answer returns. When
nothing changed, the cursor is the one you sent, so an idle poll costs one short answer. Events are only those in
channels you can see: new, edited and deleted messages, reactions, thread counts, joins and renames. channel narrows
the feed to one channel; limit is at most 200.
Events are kept for three days. A cursor older than that returns what is kept, so also read chat_unread_list after
a long gap.
A good agent in a channel replies in the thread of the message it was asked about, says what it did, and does not repeat itself on a retry.
Events
3 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| Event | When |
|---|---|
chat.channel.created |
A public channel was created in Venom Chat: id, name and who created it. Private channels and direct messages are never sent. |
chat.channel.archived |
A public channel was archived in Venom Chat (or restored: archived false): id, name and who. |
chat.message.created |
A message was posted in a public channel of Venom Chat, by a person, an agent or a feed: the message id, channel, thread, author and how it was posted. Never the text; private channels and direct messages are never sent. Busy: one event per message. |
Chat sends no org webhook events. Follow it with the change cursor above. The live server-sent event stream the Chat app uses takes a signed-in browser session only, not an API key. Events flow the other way through product feeds: Incidents, Tasks, Flags, Experiments and Forms post their events into a channel as messages with buttons.
REST routes
The REST twin: 32 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
/chat/channels
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/channels |
The channels and DMs you can see, with unread counts | chat_channel_list |
| POST | /api/v1/chat/channels |
Create a public, private or team channel | chat_channel_create |
| GET | /api/v1/chat/channels/{channel} |
Read a channel with its members | chat_channel_get |
| PATCH | /api/v1/chat/channels/{channel} |
Rename, set the topic, add or remove members, mute | chat_channel_update |
| DELETE | /api/v1/chat/channels/{channel} |
Archive a channel (restore: true to bring it back) | chat_channel_archive |
| POST | /api/v1/chat/channels/{channel}/join |
Join a public channel | chat_channel_join |
| POST | /api/v1/chat/channels/{channel}/leave |
Leave a channel | chat_channel_leave |
| POST | /api/v1/chat/channels/{channel}/read |
Mark a channel read | chat_channel_read |
| GET | /api/v1/chat/channels/{channel}/messages |
A channel's messages, newest page first or after a cursor | chat_message_list |
| POST | /api/v1/chat/channels/{channel}/messages |
Post a message or a thread reply | chat_message_create |
| GET | /api/v1/chat/channels/{channel}/feeds |
The product feeds on a channel and the ones it could take | chat_feed_list |
| PUT | /api/v1/chat/channels/{channel}/feeds |
Set, change or remove (remove: true) a product feed on a channel (owners) | chat_feed_set |
| GET | /api/v1/chat/channels/{channel}/agent |
Whether an agent (Venom by default, or a service agent) works in a channel and which tools it may use there | chat_agent_get |
| PUT | /api/v1/chat/channels/{channel}/agent |
Add an agent (Venom, or a service agent) to a channel with the tools it may use and its level (read or post), change them, or remove it (remove: true) (owners) | chat_agent_set |
/chat/threads
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/threads/{message} |
A thread: the first message and its replies | chat_thread_get |
/chat/messages
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PATCH | /api/v1/chat/messages/{message} |
Edit your message, or pin or unpin one | chat_message_update |
| DELETE | /api/v1/chat/messages/{message} |
Delete a message | chat_message_delete |
| POST | /api/v1/chat/messages/{message}/reactions |
Add or remove your reaction | chat_message_react |
| POST | /api/v1/chat/messages/{message}/agent-run |
Stop a working agent reply or run a finished one again | chat_agent_run |
| GET | /api/v1/chat/messages/{message}/pull-request |
A pull request card's state and its changed files with patches, read from GitHub with the org's own token | chat_pullrequest_get |
| POST | /api/v1/chat/messages/{message}/actions |
Press an action button of a feed message, as yourself | chat_feed_press |
| PUT | /api/v1/chat/messages/{message}/bookmark |
Save a message for later, or take the bookmark back (remove: true) | chat_bookmark_set |
/chat/search
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/search |
Search messages in the channels you can read | chat_message_search |
/chat/dms
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | /api/v1/chat/dms |
Open a DM or group message | chat_dm_open |
/chat/unread
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/unread |
Channels with unread messages or mentions | chat_unread_list |
/chat/members
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/members |
People and agents you can mention or message | chat_member_list |
/chat/agent-actions
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | /api/v1/chat/agent-actions/{action} |
Confirm or decline a write the Venom agent proposed; confirming runs it as you | chat_agent_action_decide |
/chat/keywords
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/keywords |
Your keyword alerts | chat_keyword_list |
| PUT | /api/v1/chat/keywords |
Add or remove keyword alerts | chat_keyword_set |
/chat/bookmarks
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/bookmarks |
The messages you saved for later | chat_bookmark_list |
/chat/files
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | /api/v1/chat/files |
Upload a file (base64) to attach to a message | chat_file_upload |
/chat/changes
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/chat/changes |
Chat changes after a cursor | chat_change_list |
MCP tools
32 tools: 13 read, 19 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
chat_agent_action_decide |
Confirm or decline what the agent proposed | write | chat:write |
POST /api/v1/chat/agent-actions/{action} |
chat_agent_get |
Read a channel's agent setting | read | chat:read |
GET /api/v1/chat/channels/{channel}/agent |
chat_agent_run |
Stop or re-run an agent reply | write | chat:write |
POST /api/v1/chat/messages/{message}/agent-run |
chat_agent_set |
Set a channel's agent | write | chat:write |
PUT /api/v1/chat/channels/{channel}/agent |
chat_bookmark_list |
List your bookmarks | read | chat:read |
GET /api/v1/chat/bookmarks |
chat_bookmark_set |
Save a message for later | write | chat:write |
PUT /api/v1/chat/messages/{message}/bookmark |
chat_change_list |
Follow chat changes | read | chat:read |
GET /api/v1/chat/changes |
chat_channel_archive |
Archive a channel | write | chat:write |
DELETE /api/v1/chat/channels/{channel} |
chat_channel_create |
Create a channel | write | chat:write |
POST /api/v1/chat/channels |
chat_channel_get |
Read a channel | read | chat:read |
GET /api/v1/chat/channels/{channel} |
chat_channel_join |
Join a channel | write | chat:write |
POST /api/v1/chat/channels/{channel}/join |
chat_channel_leave |
Leave a channel | write (destructive) | chat:write |
POST /api/v1/chat/channels/{channel}/leave |
chat_channel_list |
List channels | read | chat:read |
GET /api/v1/chat/channels |
chat_channel_read |
Mark a channel read | write | chat:write |
POST /api/v1/chat/channels/{channel}/read |
chat_channel_update |
Change a channel | write | chat:write |
PATCH /api/v1/chat/channels/{channel} |
chat_dm_open |
Open a DM | write | chat:write |
POST /api/v1/chat/dms |
chat_feed_list |
List a channel's product feeds | read | chat:read |
GET /api/v1/chat/channels/{channel}/feeds |
chat_feed_press |
Press a feed message's button | write | chat:write |
POST /api/v1/chat/messages/{message}/actions |
chat_feed_set |
Set a channel's product feed | write | chat:write |
PUT /api/v1/chat/channels/{channel}/feeds |
chat_file_upload |
Upload a file to attach | write | chat:write |
POST /api/v1/chat/files |
chat_keyword_list |
List your keyword alerts | read | chat:read |
GET /api/v1/chat/keywords |
chat_keyword_set |
Change your keyword alerts | write | chat:write |
PUT /api/v1/chat/keywords |
chat_member_list |
List members | read | chat:read |
GET /api/v1/chat/members |
chat_message_create |
Post a message | write | chat:write |
POST /api/v1/chat/channels/{channel}/messages |
chat_message_delete |
Delete a message | write (destructive) | chat:write |
DELETE /api/v1/chat/messages/{message} |
chat_message_list |
Read a channel's messages | read | chat:read |
GET /api/v1/chat/channels/{channel}/messages |
chat_message_react |
React to a message | write | chat:write |
POST /api/v1/chat/messages/{message}/reactions |
chat_message_search |
Search messages | read | chat:read |
GET /api/v1/chat/search |
chat_message_update |
Edit or pin a message | write | chat:write |
PATCH /api/v1/chat/messages/{message} |
chat_pullrequest_get |
Read a pull request card's files | read | chat:read |
GET /api/v1/chat/messages/{message}/pull-request |
chat_thread_get |
Read a thread | read | chat:read |
GET /api/v1/chat/threads/{message} |
chat_unread_list |
What did I miss | read | chat:read |
GET /api/v1/chat/unread |
Related
- Venom Chat: channels, threads, unread, search, files and keyword alerts.
- The Venom agent in channels and Product feeds.
- Authentication and scopes, Errors, limits and pagination, MCP and REST.