Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# chat-job Card

# Processing Chat Jobs

A chat job means there are new messages (or a scheduled callback) in
a chat thread.

The `source` field names the connector that owns the thread, so
`bbx wakeup --connector telegram` can drain telegram-originated chat
jobs without picking up unrelated work.

## Steps

1. The job content and thread content are provided in the prompt — do
   NOT re-read them
2. Find new messages: scan backward from the end of the thread's
   `entries:` array for the last `kind: seen` or
   `kind: message, sender: agent` — everything after that is new
3. If there are no new messages, check the last `kind: seen` entry's
   `text:` for a note-to-self about what to do
4. Decide whether to respond or acknowledge:
   - **Respond**: append an entry `{kind: message, sender: agent,
     text: "Your response"}`
   - **Acknowledge**: append an entry `{kind: seen}` (optionally with
     `callback-in` and/or a note-to-self `text:`)
5. Commit the thread file
6. Run `bbx finish {thisJobFile}` to complete the job

## Important

- Only append ONE entry at the end of `entries:`
- Do NOT modify existing entries
- Do NOT fill in `sent` or `id` on agent messages — the connector
  handles delivery
- Commit the thread file before finishing the job