Inbound
One item of a verified webhook batch: a message, an approval decision, a control command, or something to ignore.
A union discriminated by kind.
message
kind"message"required"message": user input that starts a run on the conversation's thread.
principalPrincipalrequiredA verified identity, normalized by the host.
addressstringrequiredConversation key; the host maps it to a thread.
item_keystringrequiredInbox dedup key, derived only from signed content.
contentInputrequiredWhat a run starts with: plain text or ordered input parts.
decision
kind"decision"required"decision": an answer to an approval card.
principalPrincipalrequiredA verified identity, normalized by the host.
addressstringrequiredConversation key; the host maps it to a thread.
item_keystringrequiredInbox dedup key, derived only from signed content.
challenge_idUuidrequiredLowercase UUID string.
decision"grant" | "deny"requiredgrant approves the challenged action; deny refuses it. It applies only if the sender may approve on that thread.
control
kind"control"required"control": a command that stops the conversation's run.
principalPrincipalrequiredA verified identity, normalized by the host.
addressstringrequiredConversation key; the host maps it to a thread.
item_keystringrequiredInbox dedup key, derived only from signed content.
command"cancel" | "stop_when_idle"requiredcancel stops the run and its children now; stop_when_idle stops it once the current work finishes. The TypeScript host consumes stop_when_idle without acting on it today.
ignore
kind"ignore"required"ignore": delivered but not for the agent (the bot's own message, a reaction, a status update). The host drops it.