Skip to content
Docs menu

Venom Chat

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.

View .md

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.

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. 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. 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

@ 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.

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

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 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.

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

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.

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.

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.

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).