Skip to main content
A conversation is a continuing health thread. A visit is one provider engagement inside that conversation. A conversation can return to IDLE after a visit or canceled request and can be resumed with send_message.

​
Conversation states

​
Start or resume a conversation

start_conversation requires contextMessage and the patient’s current physical region as an ISO 3166-2 code. list_conversations can find a relevant thread to resume with send_message. When a patient has moved, pass the current region on send_message. It applies to the next provider request, not a request already in flight. A patient’s home address in update_patient_info is separate from their current care region.

​
Triage and messaging

start_conversation returns without waiting. Call wait_for_reply for the triage response. send_message waits for a reply by default; set waitForReply: false to send without waiting and call wait_for_reply separately. wait_for_reply is resumable. When it returns stillWaiting, call it again with the same conversation ID. Use afterMessageId to wait after a reply already handled. Connector hosts support about 55 seconds per call; agent runtimes default to 240 seconds and support up to 600 seconds with maxWaitSeconds. Without a progress token or logging capability, the wait is capped at 300 seconds. Read conversation state with get_conversation. Set includeNotes: true to include provider notes for past visits that have notes; includeNotes defaults to false.

​
Payment gate

At PAYMENT_REQUIRED, relay paymentGate.consultationSummary and offer paymentGate.paymentUrl. The patient approves a temporary hold on the Stripe page; there is no card setup. The hold is captured when a doctor joins and released if no doctor joins. Once approved, the conversation moves to MATCHING. send_message does not send while the payment gate is pending. cancel_request can dismiss the gate and return the conversation to IDLE.

​
Provider visit and cancellation

At WITH_PROVIDER, the patient and provider exchange asynchronous messages. Use send_message to respond and wait_for_reply to await the next provider message or visit event. When the provider ends the visit, the conversation returns to IDLE; get_conversation can include closing notes, and get_prescriptions can read prescription orders. cancel_request stops requests in TRIAGING, MATCHING, or PAYMENT_REQUIRED. Canceling in MATCHING releases the hold. A request with a connected provider cannot be canceled through this tool. In EMERGENCY, advise the patient to call 911 or seek emergency care.

​
Safe retries

Agent hosts advertise idempotencyKey on start_conversation and send_message. Reuse the key only when retrying the same intended action.