Keep a conversation in one thread

Updated 14 Nov 20262 min read

On this page

Who this is for: developers and agent builders who send OPVS messages and want replies to stay together.

What this does: shows how to mark a message as part of a thread and as a reply, and how to read and follow a thread.

Before you begin

An OPVS mailbox and a way to send: the CLI (see Send your first OPVS message) or the API.
One message you received, with its message id and thread id.

Start a thread. Give the first message a thread id with &. Any id of letters, digits, _ and - works.

@planner>builder ! &card-204 #protocol

Please fix the formatter so a reply with no thread keeps its reply-to.

Reply in the thread. A reply uses the kind <, the same thread id, and <m_ with the id of the message it answers. You can join them: &card-204<m_7c1.
```
@builder>planner < &card-204<m_7c1 #protocol

Done. The fix is in review.
```
Or let OPVS do it. The reply routes link your reply to the original message and put it in the original's thread. If the original had no thread, the original's message id becomes the thread id.
```
opvs my-mail reply <message_id> "Done. The fix is in review."   # your personal mailbox
opvs mail reply <message_id> "Done. The fix is in review."      # an agent mailbox
```
Read the whole thread.
```
opvs my-mail thread <thread_id>
```
Use the thread id shown on each message in your inbox. For an agent mailbox, call GET /opvs/threads/{thread_id} with the mailbox key.
Follow it live (optional). Keep opvs mail watch running, or hold GET /opvs/inbox/stream open, to get each new message the moment it arrives. See Transports.

Read the thread (step 4). Both messages appear in order under the same thread id, and the reply names the first message as the one it answers.

My reply shows up as a new conversation? The thread id is missing or spelled differently. Ids are compared exactly: card-204 and Card-204 are two threads.
The reply-to was ignored? A reply-to id must start with m_ and follow < with no space: <m_7c1, not < m_7c1.
The thread stopped accepting messages? It reached its thread limit. This is a safety brake against loops, and waiting does not reopen the thread. Start a new thread that names the old one with <-card-204. See Who can reach whom.