tai conversations config-delete
Delete a per-target conversation config by (target_kind, target_name).
Example: tai conversations config-delete agent assistant
tai conversations config-get
Show one per-target conversation config by (target_kind, target_name).
Example: tai conversations config-get agent assistant
tai conversations config-list
List the per-target conversation configs (multichannel opt-in + first-contact greeting).
Example: tai conversations config-list
tai conversations config-set
Create or replace a per-target conversation config.
An UPSERT — a config for that (target_kind, target_name) is REPLACED if it exists
(created is false for a replace). The target must EXIST. --greeting-template
may reference at most the {pairing_code} placeholder; omit it (or pass an empty
value is refused) for no greeting.
Example: tai conversations config-set agent assistant --multichannel \ --greeting-template 'Hi! Pair another channel with {pairing_code}'
tai conversations create
Create or replace a conversation route.
An UPSERT — a name that already exists is REPLACED, rebinding its execution_key
along with everything else (created is false for a replace). A door=api
route’s callback_secret is minted server-side and shown ONCE in the result; it
signs the delivery callback and is never re-readable. There is no check that you can
run the target — the execution key’s live grants bound the turn. A tool target may
map the message to the tool kwargs (--payload-expr) and the result to the reply
(--reply-expr); a tool reply of null/blank sends nothing.
Example: tai conversations create chat-line --door channel --target-name relay \ --execution-key svc --channel twilio --identity +15550001111
tai conversations delete
Delete a conversation route by name.
Example: tai conversations delete chat-line
tai conversations delete-person
Erase a linked person ENTIRELY — its aggregated bridge:@person:<id> thread (agent
checkpoint, answer records, thread indexes and mode override across every route it spans),
its person row, and every address→person index mapping.
Idempotent: erasing an already-gone person is not an error (erased: false), and its
aggregated checkpoint is forgotten regardless. A turn in flight on the aggregated thread is
refused (409, retry once it drains). The same write grant that forgets a thread erases a
person.
Example: tai conversations delete-person 4f1c0e2a-...
tai conversations delete-thread
Forget one conversation thread — its agent checkpoint, its answer records and its
thread indexes — so a later message on the same address starts a fresh memory.
Forgetting is absolute: a valid id on its own route always succeeds, reporting
removed: 0 when nothing was left to clear (an aged-out or never-seen thread), never a
404 — the agent memory is forgotten regardless. A route-keyed id must carry the route’s
bridge:<route_name>: prefix, else it is refused (400); a person thread not on the named
route is a 404. A turn in flight on the thread is refused (409, retry once it drains). The
same write grant that creates a route lets you delete routes and forget threads.
The thread id rides the query string, so an api-door id — which carries a percent-encoded
principal — reaches the door spelled exactly as the listing showed it.
Example: tai conversations delete-thread chat-line bridge:chat-line:+15550001111
tai conversations failed
List answer records whose delivery ended failed (admin only).
Example: tai conversations failed
tai conversations get
Show one conversation route by name (its callback_secret is withheld).
Example: tai conversations get chat-line
tai conversations get-message
Read one conversation answer record. Any holder of the conversations read grant reads
any record on the route, whichever door it arrived through; a non-admin caller gets the
caller-safe projection, with the internal error detail withheld.
Example: tai conversations get-message chat-line 4f1c...
tai conversations get-person
Read a person — its identity, folded addresses and stored locale (the BCP 47 tag
the rendering layer resolves text against, or null when none is known).
Example: tai conversations get-person 4f1c0e2a-...
tai conversations list
List conversation routes (each row’s callback_secret is withheld).
Example: tai conversations list
tai conversations mode-get
Show a thread’s control mode and where it comes from (a per-thread override, or the
route’s default).
Example: tai conversations mode-get chat-line bridge:chat-line:+15550001111
tai conversations mode-set
Set a thread’s control mode override.
agent runs the target turn on the next inbound message; manual suppresses it so an
operator answers by hand, while platform control turns (pairing, greeting) still run. The
same write grant that forgets threads sets a thread’s mode.
Example: tai conversations mode-set chat-line bridge:chat-line:+15550001111 manual
tai conversations search
Search a route’s answer records by text, across all its threads (admin only).
Matches an inbound message or an answer containing q. A bounded server-side scan, so a
page that spent its budget reports truncated: true (matches may lie beyond it).
Example: tai conversations search chat-line --q widget
tai conversations send
Send a message BY HAND into one thread, delivered as the route identity — no turn runs.
Allowed in either mode and it never flips the mode. A route-keyed id must carry the
route’s bridge:<route_name>: prefix (else 400); a person thread not on the named route
is a 404. --address picks the send target on a linked person’s aggregated thread and
must be one of the person’s addresses; without it the target is the thread’s newest
record, and an empty person thread with no --address is a 400. A target that keeps
thread memory gets the message appended to that memory as an assistant reply; a target
with no thread memory skips it.
The thread id rides the body, so an api-door id — which carries a percent-encoded
principal — reaches the door spelled exactly as the listing showed it.
Example: tai conversations send chat-line bridge:chat-line:+15550001111 --text 'On it.'
tai conversations set-person-locale
Set (or clear) a person’s stored locale — the operator override the rendering layer
resolves text against, winning over the channel-seeded value on every later turn. Omit
locale to clear it back to no-locale-known. The same write grant that forgets a thread
sets a person’s locale.
Example: tai conversations set-person-locale 4f1c0e2a-... he-IL
tai conversations threads
List a route’s conversation threads, newest activity first (admin only).
--status and --address filter the listing with a bounded server-side scan; a page
that spent its scan budget reports truncated: true (matches may lie beyond it). An
unknown --status is refused (400).
Example: tai conversations threads chat-line --page 1 --status failed
tai conversations transcript
Read one thread’s transcript. Any holder of the conversations read grant reads any
thread’s transcript on the route; an unknown thread or route is a plain 404.
--order asc (the default) reads oldest first; --order desc reads newest first,
so page 1 always holds the latest messages — the order a live tail wants. The window
pages that order from its own end. --q filters to matching records with a bounded
server-side scan; a page that spent its budget reports truncated: true, and under
--q a thread with no match reads as an empty page rather than a 404.
The thread id rides the query string, so an api-door id — which carries a
percent-encoded principal — reaches the door spelled exactly as the listing showed it.
Example: tai conversations transcript chat-line bridge:chat-line:+15550001111