Consultation Lifecycle

​

Overview

​

Status Flow

• EMERGENCY — Triage detects urgent symptoms → advise 911
• CANCELED — User cancels before ACTIVE state

​

Status Definitions

​

TRIAGING

• Entry: start_healthcare_consultation is called
• 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
• Richer context = fewer questions = faster triage

• Monitor for AI questions
• Relay questions to user
• Send responses via send_message

​

PAYMENT_REQUIRED

• Entry: AI triage has gathered sufficient information
• Exit: User confirms → MATCHING

• The paymentGate object contains a consultation summary — a best-effort analysis of what the provider may be able to help with
• This summary is designed to help the user decide whether to proceed
• Clinical decisions remain at the provider’s discretion once connected

• pay_per_use: Call confirm_provider_connection to proceed
• subscription_required: Set up subscription first

1. Present consultationSummary to user for informed decision-making
2. Confirm user wants to proceed
3. Call appropriate confirmation tool

​

MATCHING

• Entry: User confirmed they want to proceed
• Duration: Typically minutes, but can vary based on demand
• Exit: Provider accepts → ACTIVE

• User is added to provider queue
• Available providers see the consultation request
• First available provider accepts

• Inform user they’re in queue
• Wait for webhook notification or poll status
• No user action required

​

ACTIVE

• Entry: Provider joins the consultation
• Duration: Varies (minutes to hours)
• Exit: Provider closes → CLOSED

• Provider reviews triage information
• Provider may ask additional questions
• Provider makes clinical decisions based on their assessment
• Provider can prescribe medications if appropriate
• Provider can order lab tests if needed
• All messaging is asynchronous

• Relay provider messages to user
• Send user responses via send_message
• Handle prescription flows if needed

​

CLOSED

• Entry: Provider closes the consultation
• Default state: Notes and prescriptions available

• Provider has completed their assessment
• Clinical notes may be available
• Prescriptions (if any) are ready for pharmacy selection

• Call get_consultation_notes for summary
• Handle prescription flow if applicable
• Inform user consultation is complete

​

EMERGENCY

• Entry: AI triage detects emergency indicators
• Final state: Consultation cannot proceed through Arlo

• Symptoms indicate potential emergency
• User is advised to seek immediate care
• Consultation is terminated

• Immediately inform user to call 911 or go to ER
• Do not attempt to continue with Arlo
• This is a safety-critical state

​

CANCELED

• Entry: cancel_consultation called during TRIAGING, PAYMENT_REQUIRED, or MATCHING
• Final state: Consultation is terminated

• If payment hold was placed, it is released
• Consultation cannot be resumed

• Confirm cancellation with user
• Start new consultation if user wants to try again

​

Transition Summary

​

Cancelable States

• TRIAGING — Assessment in progress
• PAYMENT_REQUIRED — Before user confirms
• MATCHING — Before provider connects

​

Polling vs Webhooks

​

Without Webhooks (Polling)

async function monitorConsultation(conversationId) {
  let status = await getConsultationStatus({ conversationId });

  while (status.status !== "CLOSED") {
    await sleep(300000); // Poll every 5 minutes
    status = await getConsultationStatus({ conversationId });
    
    // continue and process updates
  }
}

​

With Webhooks (Recommended)

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

  const { conversationId } = req.body;
  const status = await getConsultationStatus({ conversationId });
  
  // continue and process updates
});