Conversations

A conversation is a continuous health thread that can contain multiple provider visits. A finished or canceled request leaves the thread in IDLE, where send_message can resume it.

`start_conversation`

Starts a conversation with the patient’s health concern and current physical region.

Parameter	Type	Required	Details
`contextMessage`	string	Yes	First-person description of the concern and known details
`region`	string	Yes	ISO 3166-2 code for the patient’s physical location at care time
`idempotencyKey`	string	No	Available on agent hosts for safe retries

Confirm the patient’s current location before calling. Read supported region codes from the live start_conversation tool description. To resume an existing thread, use send_message with its conversation ID.

`list_conversations`

Lists the account’s conversations, including their id, status, region, activity, and visit counts.

Parameter	Type	Details
`limit`	number	Maximum number returned; defaults to 10 and is capped at 50
`beforeTimestamp`	number	Unix timestamp cursor for pagination
`beforeId`	string	Conversation ID cursor; pass with `beforeTimestamp`

The result includes conversations, total, and hasMore. When more results exist, it includes nextCursor and nextPageInstructions.

Example response

{
    "conversations": [
        {
            "id": "conversation_example",
            "title": "Example conversation",
            "status": "WITH_PROVIDER",
            "region": "US-CA",
            "hasActiveProvider": true,
            "pastVisitCount": 1,
            "lastMessage": {
                "type": "text",
                "preview": "Example message.",
                "timestamp": "2026-01-01T00:00:00.000Z"
            },
            "lastActivityAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z"
        }
    ],
    "total": 1,
    "hasMore": false
}

`get_conversation`

Reads current status, region, messages, provider visit details, past visits, and any payment gate.

Parameter	Type	Details
`conversationId`	string	Required conversation ID
`includeMessages`	boolean	Defaults to `true`
`includeNotes`	boolean	Defaults to `false`; returns provider notes as `visitNotes`
`messageLimit`	number	Defaults to 30 newest messages; use `0` for the full thread
`sinceMessageId`	string	Return messages after the last message already seen

pastVisits[].hasNotes indicates which visits have notes. Reading the conversation with messages also satisfies the read-first requirement for a later send_message.

Visit payment gate

At PAYMENT_REQUIRED, the conversation result includes a paymentGate with a summary and paymentUrl. Relay the summary and offer that Stripe page for the patient’s approval. The page collects any missing visit identity details and asks the patient to approve a temporary hold; there is no card setup. The hold is captured only if a doctor joins and released otherwise. After approval, the conversation moves to MATCHING.

`cancel_request`

Stops a request in TRIAGING, MATCHING, or PAYMENT_REQUIRED and returns the conversation to IDLE. It does not end the thread. A matching request cancellation releases the visit hold. A request cannot be canceled after a provider joins. The result includes success, conversationId, previousStatus, newStatus, userMessage, and note.

Example response

{
    "success": true,
    "conversationId": "conversation_example",
    "previousStatus": "MATCHING",
    "newStatus": "IDLE",
    "userMessage": "The request was canceled.",
    "note": "The conversation remains open."
}

`wait_for_reply`

Waits for a triage reply, provider connection, or provider message. It is resumable: if the result has stillWaiting: true, call it again with the same conversation ID. Use afterMessageId to wait beyond a reply already handled.

Parameter	Type	Details
`conversationId`	string	The conversation to wait on. Omit when passing `jobId`
`jobId`	string	A care job to wait on instead of a conversation
`afterMessageId`	string	Optional last handled reply ID
`maxWaitSeconds`	number	Optional wait duration, capped by host capability

Connector hosts support about 55 seconds per call. Agent runtimes default to 240 seconds and allow up to 600 seconds with maxWaitSeconds; without a progress token or logging capability, the window is capped at 300 seconds. A wait in PAYMENT_REQUIRED returns the gate and payment link; IDLE and EMERGENCY have nothing pending to await. With jobId, the call holds the turn on a care job and returns the job the moment it changes (the patient decided, the care team logged a step or asked a question, the job finished). It returns at once when the job already needs the patient (needs_input) or is finished. See Care Jobs. Results can contain reply or replies, informationNeed, connected, statusChanged, paymentRequired, paymentGate, stillWaiting, and guidance fields. For a prescription event, use prescriptionOrderId with get_prescriptions.

Example response

{
    "conversationId": "conversation_example",
    "status": "TRIAGING",
    "reply": {
        "from": "ai",
        "type": "text",
        "text": "Example reply.",
        "messageId": "message_example"
    },
    "informationNeed": [
        {
            "prompt": "Example follow-up question.",
            "why": "Example reason.",
            "priority": "required",
            "redFlagGate": false
        }
    ],
    "note": "Relay the reply, then gather the requested information."
}

Overview

Tools Reference

`start_conversation`

`list_conversations`

Example response

`get_conversation`

Visit payment gate

`cancel_request`

Example response

`wait_for_reply`

Example response

​start_conversation

​list_conversations

​Example response

​get_conversation

​Visit payment gate

​cancel_request

​Example response

​wait_for_reply

​Example response

`start_conversation`

`list_conversations`

Example response

`get_conversation`

Visit payment gate

`cancel_request`

Example response

`wait_for_reply`

Example response