Consultation Lifecycle

​

Overview

​

Status Flow

• EMERGENCY — Triage detects urgent symptoms → advise 911 (terminal)
• Back to IDLE — cancel_request at any point before a provider connects

​

Status Definitions

​

IDLE

• Entry: A visit wraps up, a request is canceled, or the payment gate is dismissed
• Exit: send_message re-runs triage on the same thread → TRIAGING

• The full thread and visit history are retained
• get_visit_notes returns notes from past visits
• No cleanup is ever needed — to walk away, the user simply does nothing

• To follow up on prior care, send_message into the existing conversation (don’t start a new one)
• Only start_conversation for a genuinely new, unrelated concern

​

TRIAGING

• Entry: start_conversation, or send_message into an IDLE conversation
• Duration: Varies based on complexity (typically 2-5 minutes of active conversation)
• Exit: Assessment completes → PAYMENT_REQUIRED, or emergency detected → EMERGENCY

• AI asks follow-up questions about symptoms
• Agent responds with send_message; wait_for_reply awaits each reply
• When available, the informationNeed checklist lists everything triage still needs — batch all answers into one send

• Relay questions to the user
• Send natural first-person responses via send_message
• Richer context = fewer questions = faster triage

​

PAYMENT_REQUIRED

• Entry: AI triage has gathered sufficient information
• Exit: User confirms → MATCHING; or cancel_request dismisses the gate → back to AI-only chat

• The paymentGate object contains a consultation summary — a best-effort analysis of what the provider may be able to help with
• Clinical decisions remain at the provider’s discretion once connected
• The conversation is paused: send_message will not send while the gate is up

1. Present consultationSummary to the user
2. Confirm the user wants to proceed
3. Card on file (get_payment_status → ACTIVE): call confirm_provider_connection
4. No card: create_payment_setup → user saves a card → poll get_payment_status → confirm
5. User declines: cancel_request (the gate can re-surface later)

​

MATCHING

• Entry: User confirmed via confirm_provider_connection
• Duration: Typically minutes, but can vary based on demand
• Exit: Provider accepts → WITH_PROVIDER

• Inform user they’re in queue
• wait_for_reply returns the moment a provider joins (resumable)
• cancel_request still works here if the user changes their mind

​

WITH_PROVIDER

• Entry: Provider joins the conversation
• Duration: Varies (minutes to hours)
• Exit: Provider wraps up the visit → IDLE

• Provider reviews triage information, asks questions, makes clinical decisions
• Provider can prescribe medications and order lab tests
• All messaging is asynchronous

• Relay provider messages to the user; send responses via send_message
• Use wait_for_reply to await the provider’s next message
• The visit must be wrapped up by the provider — cancel_request is refused here

​

EMERGENCY

• Entry: AI triage detects emergency indicators
• Terminal: this conversation cannot be re-engaged

• Immediately inform user to call 911 or go to ER
• Do not attempt to continue with Arlo
• Start a new conversation only if the user has a different, non-emergency concern

​

Transition Summary

​

Region

​

Waiting vs Webhooks

​

Within a session: resumable waits

// send_message defaults to waitForReply: true — send and await in one call
let result = await sendMessage({ conversationId, messages: ["..."], lastSeenMessageId });

// If the wait times out, the message IS sent — keep waiting, never re-send
while (result.stillWaiting) {
  result = await waitForReply({ conversationId });
}

​

Across sessions: webhooks (agent runtimes)

app.post("/webhook/arlo", async (req, res) => {
  res.status(200).send(); // Acknowledge immediately

  const { conversationId } = req.body;
  const conversation = await getConversation({ conversationId });
  // process updates
});