Skip to content
Docs menu

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.

View .md

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 (or chat_change_list) for messages that mention it, read the thread with chat_thread_get, and reply in it with POST /api/v1/chat/channels/{channel}/messages (thread, client_id).
  • Announcements from your CI or deploy tool. Post a release note to #releases with chat_message_create and pin it with chat_message_update (pinned).
  • A daily digest. Read what a member missed with GET /api/v1/chat/unread, or search a week of a channel with GET /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_open and press a feed message's button (acknowledge a page, approve a flag change) with chat_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:read to read, chat:write to 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 (#launch or launch; 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_list gives each member's whole key (user:ID or agent:ID). The Venom agent is @[Venom](agent:venom).
  • Files: upload with chat_file_upload (at most 4 MB) and pass the ids in files of chat_message_create, up to 10. files is 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