{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://www.helpvox.ai/ucp/schemas/2026-09-11/assisted-order.json","version":"2026-09-11","title":"HelpVox assisted-order capability","description":"place_order starts a HelpVox assisted-order conversation. It does NOT create an order. The customer opens conversation_url, the assistant collects the name, phone and delivery address, reads the order back, and only an explicit confirmation creates it. Until then order_created is false. HelpVox has no cart, no checkout and no payment: payment is on delivery, collected by the merchant, and HelpVox is not the merchant of record.\n\nTwo clocks, and they are not the same one. session_ttl_seconds (720) is how long the customer has to open the signed conversation_url and start talking; it runs from the moment the session is created and opening the page does not extend it. conversation_ttl_seconds (7200) starts when the customer actually starts the conversation, and from then on it is the only one that applies: a live conversation is never cut off because the handoff link aged. Read them from handoff_expires_at and conversation_expires_at, which is why the response carries both instead of one ambiguous expires_at. conversation_expires_at is null until the conversation starts — there is no conversation yet to expire.","type":"object","required":["semantics","order_created_by","operations","channels","accepts_personal_data","payment","states"],"properties":{"semantics":{"const":"asynchronous_handoff","description":"The operation returns a conversation to open, not a completed transaction."},"order_created_by":{"const":"customer_confirmation_in_conversation","description":"Nothing is created from the API call. Silence or an unclear answer is not a confirmation."},"operations":{"type":"array","description":"Callable operations. Their request and response shapes are in the OpenAPI document.","items":{"type":"object","required":["operation_id","method","path"],"properties":{"operation_id":{"type":"string","enum":["place_order","get_assisted_order"]},"method":{"type":"string","enum":["POST","GET"]},"path":{"type":"string","description":"Relative to the service endpoint in the profile."},"summary":{"type":"string"},"required_headers":{"type":"array","description":"Rejected with VALIDATION_ERROR before the body is read.","items":{"type":"string"}},"returns":{"type":"array","items":{"type":"string"}}}}},"channels":{"type":"object","description":"Which conversation channels this storefront can actually open.","properties":{"voice":{"type":"boolean"},"text":{"type":"boolean"}}},"accepts_personal_data":{"const":false,"description":"The initial request must not carry a name, phone, email, address or payment details. Sending them is rejected with VALIDATION_ERROR and they are not stored or logged."},"payment":{"type":"object","description":"Cash on delivery, collected by the merchant. No money passes through HelpVox.","properties":{"collected_by":{"const":"merchant_on_delivery"},"processed_by_helpvox":{"const":false}}},"states":{"type":"array","description":"The session state machine. Only states HelpVox can actually observe are written: creation, the customer opening the conversation, expiry, and completion — which is derived from a real order record, never asserted.","items":{"type":"string","enum":["requires_interaction","conversation_started","collecting_customer_data","awaiting_confirmation","processing","completed","cancelled","expired","failed"]}},"session_ttl_seconds":{"type":"integer","description":"Seconds the customer has to open the signed conversation_url and start the conversation. Counted from when the session is created; opening the page does not extend it. Surfaced per session as handoff_expires_at."},"conversation_ttl_seconds":{"type":"integer","description":"Seconds a conversation stays live once the customer has actually started it, counted from that moment. From then on it replaces session_ttl_seconds entirely: a started conversation is not cut off because the handoff link aged. Surfaced per session as conversation_expires_at."}}}