Team Chat reply watch — an agent hears back from a person

What it is

Agents can already send on your behalf — a direct message to a teammate, or a post in a channel. What was missing was the other half: when the person wrote back, nobody told the agent. The reply sat in Team Chat until somebody happened to look.

The reply watch closes that. Sending a message arms it; the person's answer wakes the agent that asked. It is not a subscription you have to set up or remember — the act of writing is the ask.

It also means an agent can read the pictures a person attaches. Team Chat messages carry their attachments as cloud file locations, and an agent reading a message could see that screenshots were there and had no way to open them. An agent can now download one and open it.

Where to find it

Nothing to switch on. It happens in the background once an agent has sent a Team Chat message through the local control server — either the direct-message route or the channel message route.

An agent can see its own active watches, and stop one, with three routes:

• GET /team-chat/reply-watches — every conversation this session is listening to, whether it is live yet, and the last reason nothing was delivered.
• DELETE /team-chat/reply-watches/:channelId — stop listening to one conversation.
• GET /team-chat/channels/:channelId/messages/:messageId/attachments/:index/download — fetch one attachment to a temporary file and return its path.

How it behaves

What wakes the agent. Only a person. A message another agent wrote never wakes it, an ordinary automated row from another part of the product never wakes it, and neither does your own typing — you are not "a different person", and the agent already speaks for you. A message that predates the one the agent sent does not wake it either.

What arrives. The person's own words, in a clearly marked block, followed by a note from the app naming who wrote it, saying plainly that they are not you and hold no authority, and giving the exact request to answer with. If a person's text tries to close that block early and write its own note, the attempt is disarmed.

How often. Once per message. A reply is never delivered twice, even if the app is interrupted between handing it over and writing down that it did.

If the agent is busy. The reply is held, and delivered the moment the agent is free — never dropped. A few replies arriving together are read in the order they were written.

If a message cannot be delivered. The agent is not told it arrived when it did not. Nothing advances until a delivery actually succeeds.

When it stops. A watch ends when the agent's session is archived, ended or has failed — a session you have closed is never reopened to hand it a message. It also ends when you stop it by name, and in one further case: if a conversation grew so long that the app can no longer read back to where the agent last looked, the replies it can still see are delivered first and then the watch ends rather than sitting there silently. GET /team-chat/reply-watches names that ending (backlog-too-deep) and the reason it happened. There is no hidden expiry and no hidden limit beyond that one, and you are told when a watch ends for it. A paused session is not ended: its watch waits until you resume it, and a waiting watch still checks its conversation once a minute.

A watch never goes quiet on its own. Whatever happens — a reply held while the agent is busy, a conversation too long to read all the way back — the state is on the watch you can list, and the reply itself is never thrown away for a reason the app kept to itself.

Nothing goes back to the person. This feature writes nothing to Team Chat. Nothing is acknowledged, no read receipt is sent, and no reply is posted on your behalf. The person sees only what the agent deliberately sends.

Reading an attachment. The file is written to a temporary folder and its path is returned. The caller can name an attachment only by its position on a message it is allowed to read — never a file location of its own choosing — and an attachment larger than the ordinary download limit is refused before a single byte moves.

For agents

The watch is armed for you. When you send with POST /team-chat/dm or POST /team-chat/channels/:channelId/messages and your session id is on the request, a watch is recorded for that conversation — the direct-message route watches the whole conversation, the channel route watches the thread you posted in (the thread you replied to, if you passed a parentId).

The reply arrives in your session as a turn from team-chat-person, carrying the message id of the reply and the request to answer with, including the person's uid for a direct message. Nothing was sent to them; the answer is yours to choose.

GET /team-chat/reply-watches lists them, DELETE /team-chat/reply-watches/:channelId stops one — both scoped to the calling session, so one session can never stop another's watch.

One thing worth knowing: to reach a person by direct message, use POST /team-chat/dm. A channel message is watched as a thread, so if you post into a direct-message channel through the channel route, only thread replies to your message wake you, not the person's next top-level message.

Related

Agent lanes covers your agents talking to a teammate's agents, with no person in the loop. Cross-device agent messages is the same idea between your own computers. Agent messages is the general picture of how a session receives a message from anywhere. Team Chat API platform is the full set of routes an agent can drive.