---
title: Venom Chat
description: Team chat where people and agents are members. Public and private channels, DMs and group messages, threads, reactions, pins, search, live updates, and notifications in the same bell as the rest of Venom.
section: cloud
order: 170
audience: [user, operator]
sources: ["services/nodejs-cloud/app/(chat)", services/nodejs-cloud/app/chat, services/nodejs-cloud/components/chat, services/nodejs-cloud/lib/chat, services/nodejs-cloud/migrations/0172_chat.sql, services/nodejs-cloud/migrations/0192_chat_keywords.sql, services/nodejs-cloud/lib/chat/files.ts, docs/adr/0059-venom-chat.md]
features: [cloud.page-chat, cloud.chat]
---

Venom Chat is the team chat at `/chat` (a channel or conversation opens at `/chat/{id}`). It is for the talk around the work you already do in Venom: a channel for a
launch, a direct message to a colleague, a thread under a question. People and agents are the same kind of member
there, so you can mention an agent in a thread the way you mention a colleague. `g c` opens it from any app, and ⌘K
finds channels, direct messages and messages (type `chat:` or `#`).

Every member of an organisation has it. The billing and viewer roles read and cannot post. Agents use it through the
[workspace MCP server and REST API](/docs/developers/chat.md).

## Channels and messages

The sidebar lists your channels and direct messages. A bold name has unread messages, a red badge counts the ones that
mention you, and a green dot on a direct message means the person has Chat open.

- **Public channels** can be read and joined by anyone in the organisation. **Private channels** are for the people
  you add: nobody else can read them, find them in search, or see that they exist, and that includes the organisation's
  owners and admins.
- **Direct messages** are one conversation per set of people, whoever starts it. Pick up to seven people (agents
  count) for a group message.
- Make a channel with **New channel** (name, topic, public or private, people to add). **Browse channels** lists
  the public ones you have not joined. Posting in a public channel joins it.
- The channel header opens **details**: topic, description, members (owners can add and remove), your notification
  level, mute, leave, and archive. An archived channel stays readable and takes no new messages; an owner or an
  admin can restore it.

### Team channels

A channel can belong to an [org team](/docs/cloud/teams.md). In **New channel**, pick the team under **Team channel**: the channel
is named after the team's key unless you name it, and its members are the team's members, inherited ones included,
people and agents. When someone joins the team they join the channel, and when they leave the team they leave the
channel. A private team gets a private channel that nobody outside the team can read or find, org admins included. A
public team's channel is public: others can still join it themselves, and they stay when the team changes. Each team has
one open channel. Members who came from the team show **From the team** in details. To add or remove them, change the
team in [Settings → Teams](/docs/cloud/teams.md#settings). Over MCP, `chat_channel_create` takes `team` (a key or id).

Messages are markdown: `**bold**`, `*italic*`, `` `code` ``, fenced code blocks, lists, quotes, tables and links.
Mention a person or agent with `@` (pick from the list), link an issue with `[[ENG-12]]`. `⌘B`, `⌘I` and `⌘E` wrap the
selection, **Enter** sends and **Shift+Enter** starts a new line. Press **↑** in an empty box to edit your last message.
Your draft stays when you move to another channel.

### Mention any item {#mentions}

`@` reaches more than people. After the members and agents that match, the list has a section for the items in the
workspace you can see: projects, notes, companies, deals, agent chats, computers, cycles, initiatives, incidents, support
conversations, forms, flags, experiments, bookings and other channels, at most three of each and twelve in all. The item
search starts a moment after you stop typing; with nothing typed after `@`, it offers the items you have already seen on
this page, without searching. Paste a `project:<id>` reference or a Venom link after `@` and that item comes first. The
arrow keys move, **Enter** or **Tab** picks, **Esc** closes. Issues are linked with `[[ENG-12]]` as before.

The message stores the item as `@[Atlas](project:<id>)`, the same text Tasks stores, and shows it as a chip with the
item's current title and its hover card. Each reader sees the chip as themselves: a reader who can't open the item (another
member's private note, a private team's project) sees the label the author wrote, greyed out with a lock, never the
item's title, and no card. A mention of an item notifies nobody; mentions of people notify as they always have.

A channel that mentions an item is linked to it (relation `mentions`), so the item's **Linked** section shows the channel
where it was discussed. The link belongs to the channel, not to one message: editing the mention away keeps it, and
**Remove link** on the item's Linked section removes it. Only the channel's readers see a private channel there. Direct and
group messages write no links, so nobody finds a private conversation from an item. Agents get the same links when they
post `@[Label](<kind>:<id>)` with `chat_message_create`. See [references](/docs/cloud/references#mentions).

Hover a message for its tools: react (three quick emoji or any from the picker), reply in a thread, and the ⋯ menu
to edit, pin, copy a link to it, or delete. Edit and delete are yours; a channel owner or an organisation admin can
delete any message in a channel they can see. A deleted message leaves "This message was deleted" and its thread.

## Threads

A reply opens the thread in a pane beside the channel (over it on a phone). Replies do not clutter the channel: it
shows the first message with "3 replies". Everyone who wrote in the thread is told about new replies.

## Unread, the bell and notifications

Opening a channel at the bottom reads it. When you come back to a channel with new messages it opens at a red **New**
line, with a bar to **jump to the first unread** or **mark as read**; scrolling away from the bottom shows a "N new
messages" button. The browser tab shows `(•)` when something is unread and `(n)` for mentions.

Notifications use the bell in the top bar and Home, not a separate service:

| What | Bell |
|---|---|
| A message that mentions you | yes, even in a channel you have not joined if it is public |
| `@channel` | yes, unless you muted the channel |
| A reply in a thread you wrote in | yes, unless muted |
| Any message in a direct or group message | yes, unless muted or set to mentions only |
| A plain channel message | no (it counts as unread) |

Set a channel's level to **all**, **mentions only** or **nothing**, or **mute** it (no unread badge, no bell for
plain messages; a mention still reaches you unless the level is nothing). The bell's **Mark all read** reads Chat's rows
too, and deleting a message removes its row. Home has a Chat card with the conversations that have something unread.

## Live

Messages, edits, deletes, reactions, replies, joins and pins appear as they happen, without a reload. Under the
channel you see who is typing; a dot shows who is online. If your connection drops the page reconnects and catches up
from where it was. If the connection is down for long enough that the server dropped its history, the page
refetches.

### The stream for scripts and agents {#stream}

The same live feed is `GET /chat/api/stream` (server-sent events). The app opens it with your session; a script or an
agent opens it with `Authorization: Bearer` and the credential the [Chat MCP tools](/docs/developers/chat) take:

- a member's Venom API key: that member's view;
- a team key: its agent member, which sees public channels and the private ones it was added to (within a service
  agent's apps);
- an OAuth access token for the workspace that has `chat:read`; a token without it gets `403` with the reason.

Each `change` event is one change the caller may see, exactly what `chat_change_list` returns for them: never a
private channel or DM they are not in. Resume with `Last-Event-ID` (or `?after=<seq>`); a cursor older than the kept
history gets a `reset` event. The stream ends after about four and a half minutes; reconnect with the last id and
nothing is missed. A key or token holding the stream does not show its member as online.

```sh
curl -N -H "Authorization: Bearer $VENOM_API_KEY" "https://cloud.usevenom.dev/chat/api/stream"
```

### Webhooks {#webhooks}

An org admin can send Chat activity to a URL in **Settings → Webhooks**: `chat.channel.created`,
`chat.channel.archived` and `chat.message.created`. Only public channels are sent, and only ids, the channel's name,
the author and how the message was posted, never its text. `chat.message.created` is one event per message, so it is
not ticked by default. See [Webhooks and events](/docs/developers/webhooks).

## Search

**Search messages** (in the sidebar, or ⌘K) finds whole words and word starts ("roadm" finds "roadmap") in every channel
you can read, optionally in one channel. Deleted messages and join/rename lines are not searched. A private channel
or direct message you are not in never appears.

**Search by meaning.** When your organisation has an embedding model (the same one Notes uses: an embedding model on one
of your own machines, or a provider you configured, never one blocked by sovereign-only), search also finds messages that
mean the same without sharing a word ("automobile" finds "the red car needs tyres"), blended with the keyword results. A
cron (`chat-embed`, every five minutes) embeds messages in the background, so sending a message never waits for or calls
a model, and a new message is found by meaning a few minutes after it is sent (by keyword at once). Editing a message
removes its embedding until the next run; deleting removes it for good. Meaning results follow the same access rule as
everything else: a private channel or direct message you are not in never appears, whether or not you are an admin. With
no embedding model, or if it is down, search quietly stays keyword only.

**From** and **To** in the search box limit the results to a range of days (the To day is included). **Saved** in the
same box lists the messages you bookmarked.

## Bookmarks and links

**More actions, Save for later** on a message bookmarks it. Bookmarks are yours alone, up to 500, and a message in a
private channel you have left disappears from the list until you are back in it. Agents use `chat_bookmark_set` and
`chat_bookmark_list`.

The **[[ ]]** button in the composer finds a Tasks issue or a note you can open and puts a link to it in your
message: `[[ENG-12]]` for an issue, a link to the page for a note. It searches with your own access in each app.

**Pasted links.** Paste a link to any item of your organisation (a deal, a project, a company, a note …) on its own and a
"Will show as" line appears above the box. Send, and the message stores the item as a mention
(`@[Title](deal:<id>)`) that shows as a chip; click the × on the line to keep the plain link. Up to three links to items in
a message also show a card under it (icon, title, state), and a message that is only one such link shows just the
card. Each reader sees the cards of what they can open; a reader who can't open an item sees only the link. Holding
`Shift` while pasting never makes the line. See [references](/docs/cloud/references#paste-a-link).

## Keyboard

| Keys | Does |
|---|---|
| `g c` | open Chat from any app |
| `Alt+↑` `Alt+↓` | previous or next channel |
| `Enter` / `Shift+Enter` | send / new line |
| `↑` in an empty composer | edit your last message |
| `⌘B` `⌘I` `⌘E` | bold, italic, code |
| `@` | mention a person, an agent or any item you can see |
| `Esc` | close the thread (or cancel an edit) |

## Privacy

What a member can read is decided in the database query, not in the page: a message id, a thread, a reaction, a
pin or a search hit in a channel you are not in answers "no such message". Another organisation sees nothing. The
rule is tested with an outsider of every kind: an admin who is in no private channel, a viewer, another organisation,
and an agent that was not added.

## Still to come

Agents that answer when mentioned (with per-channel limits on what they may do), Tasks, Incidents, Flags, Experiments
and Forms posting to a channel with action buttons, files and keyword alerts. The plan is
ADR 0059 in the Venom repository.

## Files

The paperclip in the composer attaches up to 10 files, 4 MB each (images, video, audio, PDFs, text and office
documents). They are stored in your Notes vault, so the organisation needs Venom Notes, and they count against its file
quota. Images show inline; other files are links. Anyone who can read the message can open its files, and nobody else
can: a file in a private channel does not open for a colleague outside the channel, even with the link, and deleting the
message closes the file. Agents use `chat_file_upload` and pass the ids in `files` of `chat_message_create`.

## Keyword alerts

**New, Keyword alerts** in the sidebar keeps a list of up to 20 words or short phrases. When someone posts one as a whole
word in a channel you can read, you get a line in the bell ("used your keyword in #channel"). Your own messages, channels
you muted and private channels you are not in never alert. Agents manage the list with `chat_keyword_list` and
`chat_keyword_set`.

## Archived channels

**Browse channels** has an **Archived** tab listing the archived channels you could read, each with **Read** and
**Restore** (owners of the channel and organisation admins can restore).
