Conversation Tools

Overview

A conversation is a continuous health thread that never “closes.” It can contain several provider visits over time, and an IDLE conversation can always be re-engaged with send_message (which re-runs triage on the same thread). These tools manage the full lifecycle: starting, reading, waiting for replies, stopping a provider request, retrieving visit notes, and updating the care region.

start_conversation

Open a new health conversation with Arlo. Triggers AI triage and can lead to one or more provider visits over time. Arlo connects patients with licensed clinicians who can diagnose, treat, prescribe, order labs, and refer.

Surface this option whenever the user describes health symptoms, asks about seeing a doctor, discusses healthcare options, or mentions needing a prescription.

Start NEW vs. continue EXISTING

This tool opens a brand-new conversation. To continue an existing conversation — even one that looks finished — use send_message instead; messaging an idle conversation re-runs triage on the same thread. Call list_conversations first if you’re unsure whether a relevant conversation already exists. Only start a new conversation for a genuinely new, unrelated concern.

Parameters

Parameter	Type	Required	Description
`contextMessage`	string	Yes	First-person narrative of the health concern
`region`	string	Yes	ISO 3166-2 code for where the patient is physically located right now (e.g. `US-CA`)

Region is required and is about current location, not home address — care is licensed by where the patient currently is. Confirm it with the user before calling (e.g. “Just to confirm, are you in California right now?”). An unsupported region is refused with REGION_NOT_SUPPORTED. The region is set once here and reused for the life of the conversation; if the patient later moves, call update_conversation_region.

Context Message Format

Write in the first person, as the patient speaking — the message is delivered to the care team as if the patient typed it themselves. Never third person (“The user has…”, “Patient reports…”). For a child or dependent, stay first person from the account holder’s perspective (“My daughter has had a fever since yesterday…”).

I have had a cold for two weeks and I think I'm now getting a sinus infection. I've been having pressure and pain in my forehead, and my snot is a greenish yellow color. I've had sinus infections before with a similar pattern.

sinus infection, 3 days, forehead pressure

Include: symptom, duration, severity, associated symptoms, history, and who is affected (self/child/dependent).

Fast-ack behavior

This tool returns as soon as the conversation is created — it does not block for the first triage reply. Call wait_for_reply with the returned conversationId to await Arlo’s response.

Avoid duplicates: never call start_conversation again for the same concern. If you already have a conversationId, use wait_for_reply (or send_message) on it.

Returns

{
  "conversationId": "conv_abc123",
  "status": "TRIAGING",
  "agentInstructions": [
    "Call wait_for_reply with this conversationId to await Arlo's response — it's resumable, so re-call it if it returns stillWaiting."
  ]
}

On widget-capable hosts, the consultation widget opens alongside the result so the user sees their message land and the AI reply stream in live.

list_conversations

List the user’s ongoing health conversations. Use this to find an existing conversation to continue before starting a new one.

Parameters

Parameter	Type	Required	Description
`limit`	number	No	Maximum conversations to return (default: 10, max: 50)
`beforeTimestamp`	number	No	Pagination cursor from `nextCursor.beforeTimestamp`
`beforeId`	string	No	Pagination cursor from `nextCursor.beforeId` (pass together with `beforeTimestamp`)

Returns

{
  "conversations": [
    {
      "id": "conv_abc123",
      "title": "Sinus infection",
      "status": "IDLE",
      "region": "US-CA",
      "hasActiveProvider": false,
      "pastVisitCount": 1,
      "lastMessage": {
        "type": "text",
        "preview": "Thanks doctor, that makes sense...",
        "timestamp": "2026-06-20T14:30:00Z"
      },
      "updatedAt": "2026-06-20T14:30:00Z"
    }
  ],
  "total": 1,
  "hasMore": false
}

When hasMore is true, the result includes nextCursor — pass both of its values back to fetch the next page.

If the patient is now in a different state/province than a conversation’s region, call update_conversation_region before requesting a provider in it.

get_conversation

Get the current status and messages of a conversation: its status, region, the active provider visit (if any), and a summary of past visits.

Parameters

Parameter	Type	Required	Description
`conversationId`	string	Yes	The conversation ID
`includeMessages`	boolean	No	Include message history (default: true)
`messageLimit`	number	No	Newest messages to return (default 30; `0` for the full thread)

The read gate

Call this before every send_message. send_message enforces a read-first rule — it refuses unless you’ve pulled the latest conversation state since its last update (or since your previous send). Calling this tool with includeMessages: true marks the conversation as read for your session. Alternatively, pass lastSeenMessageId to send_message to skip the extra round-trip.

Statuses

Status	Description
`IDLE`	AI-only, nothing in progress. Re-engageable — `send_message` re-runs triage
`TRIAGING`	AI is gathering symptom information on a live request
`PAYMENT_REQUIRED`	Triage complete, awaiting payment confirmation (or dismissal)
`MATCHING`	Being matched with a healthcare provider
`WITH_PROVIDER`	A provider is connected (messaging is asynchronous)
`EMERGENCY`	Urgent care advised — user should call 911 (not re-engageable)

There is no terminal CLOSED/CANCELED status. A finished or canceled request simply leaves the conversation IDLE with its visit history intact.

Returns

Key fields:

Field	Description
`status`, `statusDescription`	Current state
`region`	ISO 3166-2 region this conversation is licensed for
`providerVisit`	`{ active, providerName, consultId }` when a provider is in seat
`pastVisits[]`	Prior provider visits (`consultId`, `closedAt`, `hasNotes`)
`messages[]`	`{ id, type, sender, content, timestamp }`, windowed to the newest `messageLimit` entries
`omittedOlderMessages`	How many older messages exist beyond the window (when truncated)
`paymentGate`	`{ consultationSummary, paymentType }` when `PAYMENT_REQUIRED`
`informationNeed`	Checklist of what triage still needs — answer it in one batched `send_message`
`nextSteps`	Suggested actions based on current status

Message Types

Type	Description
`text`	Plain text message
`triage`	AI triage question/response
`photo` / `video` / `file`	Media attachment (fetch via `get_media_url`)
`join`	Provider joined notification
`prescription`	Prescription notification
`lab_request`	Lab request notification

On hosts that render the Arlo consultation widget, new events stream into your context between turns under the Arlo Consultation Widget header. Read that before answering anything that depends on current state, and don’t re-render the full message thread as text — the UI displays it. Use this tool as the fallback (no widget content present, omittedEarlierEvents > 0, or as the read gate before send_message).

Don’t tell the user something hasn’t happened (no reply, no prescription, no status change) unless your current widget context or this tool’s latest result confirms it.

wait_for_reply

Wait for the next reply or update in a conversation. send_message and start_conversation return immediately without waiting for a response — call wait_for_reply afterward to await what comes next. It is a resumable wait you can loop on: call it, and if it returns stillWaiting, call it again to keep waiting. What it waits for depends on the conversation’s current status — the AI’s triage reply while TRIAGING, a provider connecting while MATCHING, or the provider’s next message while WITH_PROVIDER.

Parameters

Parameter	Type	Required	Description
`conversationId`	string	Yes	The conversation to wait on
`afterMessageId`	string	No	Only return replies newer than this message

Returns

Either the reply (reply / replies, same message shape as get_conversation) or { "stillWaiting": true } on timeout — re-call to continue waiting. When a reply arrives, the conversation is marked read for your session.

cancel_request

Stop the conversation’s current attempt to connect with a provider and return it to AI-only chat. This does not end the conversation: the thread stays open and the user can re-engage anytime with send_message.

Behavior by status

Status	Behavior
`PAYMENT_REQUIRED`	Dismisses the payment gate and returns to AI-only triage on the same thread (gentlest option — the gate can re-surface)
`TRIAGING` / `MATCHING`	Stops the in-flight attempt. Conversation goes `IDLE`
`WITH_PROVIDER`	Refused — the visit must be wrapped up by the provider
`IDLE`	Refused — nothing in progress to stop
`EMERGENCY`	Refused — terminal

Parameters

Parameter	Type	Required	Description
`conversationId`	string	Yes	The conversation whose provider request should be stopped

Returns

{
  "success": true,
  "conversationId": "conv_abc123",
  "previousStatus": "MATCHING",
  "newStatus": "IDLE",
  "userMessage": "Your request has been stopped. You can message Arlo anytime to start again.",
  "note": "The conversation stays open in AI-only mode and can be re-engaged with send_message."
}

To fully walk away, the user can simply do nothing — an IDLE conversation requires no cleanup.

get_visit_notes

Get clinical notes from a conversation’s provider visits. A conversation can have several visits over time, each with its own note; this returns the notes across all of them, grouped per visit.

Parameters

Parameter	Type	Required	Description
`conversationId`	string	Yes	The conversation ID

Returns

{
  "conversationId": "conv_abc123",
  "hasNotes": true,
  "notes": [
    {
      "providerId": "prov_xyz",
      "timestamp": "2026-06-20T15:00:00Z",
      "note": {
        "chiefComplaint": "Sore throat for 3 days",
        "assessment": "Viral pharyngitis",
        "plan": "Rest, fluids, over-the-counter pain relief",
        "summary": "Patient presented with..."
      }
    }
  ]
}

Notes are only available for visits a provider has closed out with a note.

update_conversation_region

Change the region (state/province) a conversation is licensed for. Use when the patient is now physically somewhere different than when the conversation was started.

Parameters

Parameter	Type	Required	Description
`conversationId`	string	Yes	The conversation to update
`region`	string	Yes	ISO 3166-2 code for the patient’s current location (e.g. `US-CA`)

Timing

This updates the conversation’s region for the next provider request. It does not re-route a request already in flight:

If the conversation is IDLE: change the region, then send_message to start a new request in the new region.
If the conversation is MATCHING or PAYMENT_REQUIRED and the user has actually moved: call cancel_request first, then update_conversation_region, then send_message.

Returns

{
  "success": true,
  "conversationId": "conv_abc123",
  "region": "US-CA",
  "appliesToNextRequest": false,
  "note": "Region updated. It will be used for the next provider request."
}

Overview

Tools Reference

Overview

start_conversation

Start NEW vs. continue EXISTING

Parameters

Context Message Format

Fast-ack behavior

Returns

list_conversations

Parameters

Returns

get_conversation

Parameters

The read gate

Statuses

Returns

Message Types

Widget hosts

wait_for_reply

Parameters

Returns

cancel_request

Behavior by status

Parameters

Returns

get_visit_notes

Parameters

Returns

update_conversation_region

Parameters

Timing

Returns

​Overview

​start_conversation

​Start NEW vs. continue EXISTING

​Parameters

​Context Message Format

​Fast-ack behavior

​Returns

​list_conversations

​Parameters

​Returns

​get_conversation

​Parameters

​The read gate

​Statuses

​Returns

​Message Types

​Widget hosts

​wait_for_reply

​Parameters

​Returns

​cancel_request

​Behavior by status

​Parameters

​Returns

​get_visit_notes

​Parameters

​Returns

​update_conversation_region

​Parameters

​Timing

​Returns

Overview

start_conversation

Start NEW vs. continue EXISTING

Parameters

Context Message Format

Fast-ack behavior

Returns

list_conversations

Parameters

Returns

get_conversation

Parameters

The read gate

Statuses

Returns

Message Types

Widget hosts

wait_for_reply

Parameters

Returns

cancel_request

Behavior by status

Parameters

Returns

get_visit_notes

Parameters

Returns

update_conversation_region

Parameters

Timing

Returns