---
title: Build on Venom Chat
description: 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.
section: developers
order: 80
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/chat/mcp.ts, services/nodejs-cloud/lib/chat/tools.ts, services/nodejs-cloud/lib/chat/auth.ts, services/nodejs-cloud/lib/chat/feed.ts, services/nodejs-cloud/lib/chat/files.ts, services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/contracts/openapi/workspace-v1.json, docs/adr/0059-venom-chat.md]
features: [cloud.workspace]
---

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 {#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 {#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 {#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 {#example}

Reply in the thread of a message that mentioned your agent, safely retried, then pick up where you left off:

```bash
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`:

```json
{ "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 {#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](/docs/developers/conventions.md).

## Following chat with the change cursor {#changes}

```text
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 {#events}

3 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)).

| 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](/docs/cloud/chat-feeds.md): Incidents, Tasks, Flags, Experiments and Forms post their events into a
channel as messages with buttons.

## REST routes {#rest}

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](/docs/developers/rest)).

**/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 {#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 {#related}

- [Venom Chat](/docs/cloud/chat.md): channels, threads, unread, search, files and keyword alerts.
- [The Venom agent in channels](/docs/cloud/chat-agents.md) and [Product feeds](/docs/cloud/chat-feeds.md).
- [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md).
