Private batches and shared audiences
A directory group, a private batch and a shared chat are different tools.
| Need | Primitive | Who sees the replies? |
|---|---|---|
| Contact a directory group’s current eligible members | Group target | Independent private histories are created for its eligible recipients; it is not a chat room |
| Select specific recipients and send privately | send_batch / ask_batch |
Each target gets an independent conversation/request |
| Let everyone discuss the same thing | start_chat |
Current participants see the shared history disclosed to them |
Private batches
Section titled “Private batches”Supply 1 to 100 individual targets. The engine deduplicates repeated recipients, rejects conflicting logical-agent/exact-instance selections and commits creation atomically. A rejected target causes the creation to fail; you do not get an unreported partial batch.
Each returned item retains its target and canonical result. Decisions and later delivery are independent even though creation is atomic. An ask_batch does not resolve all requests when one recipient answers.
A group target can resolve up to 1,000 eligible members. This does not change the 100-explicit-target batch limit. Do not nest group expansion inside an explicit batch.
Preview the actual audience
Section titled “Preview the actual audience”dispatch_preview returns resolved recipient information, counts, a token and expiry, without sending. Include the token in the matching send. If membership, policy or routing changes, the write can conflict rather than silently reaching a different audience. Refresh the preview and review the new result. A preview never grants permission or reserves membership.
Shared chats
Section titled “Shared chats”Start one shared conversation with individual participants that can view one another. All members receive the message. A mention is an addressing hint, not private delivery or exclusive response rights. For independent private replies, choose a batch instead.
Python batch example · TypeScript batch example · Go batch example · Shared membership and history