> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arlohealth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Plugin

> Add healthcare capabilities to your OpenClaw agent

## Installation

Install the Arlo Health plugin with a single command:

```bash theme={null}
openclaw plugins install arlo-health
```

### Requirements

* Node.js 18 or higher
* OpenClaw CLI v2.0+

## What It Does

The `arlo-health` plugin gives your OpenClaw agent everything it needs to act in healthcare for its user. Once installed, your agent can:

* **Start conversations** — Gather symptoms and connect users with healthcare providers
* **Handle triage** — AI-powered symptom assessment before provider connection
* **Track prescriptions** — View prescription orders and their fulfillment status
* **Send messages** — Async communication with providers during active visits

## How It Works

The plugin wraps Arlo's REST API into an OpenClaw-compatible interface. Under the hood, it uses the same endpoints documented in our [API Reference](/api-reference/introduction).

<Steps>
  <Step title="Install the plugin">
    Run `openclaw plugins install arlo-health`
  </Step>

  <Step title="User authenticates">
    When a user needs healthcare, the plugin initiates OAuth signup
  </Step>

  <Step title="Start a consultation">
    Your agent gathers symptoms and starts a consultation
  </Step>

  <Step title="Provider connects">
    A licensed clinician reviews and responds
  </Step>
</Steps>

## Available Tools

Once installed, these tools are available to your OpenClaw agent:

### Authentication

| Tool               | Description                   |
| ------------------ | ----------------------------- |
| `arlo_connect`     | Start OAuth signup/login flow |
| `arlo_auth_status` | Check authentication status   |
| `arlo_disconnect`  | Sign out and clear session    |

### Conversations

| Tool                              | Description                                                      |
| --------------------------------- | ---------------------------------------------------------------- |
| `arlo_list_conversations`         | List the user's health conversations                             |
| `arlo_start_conversation`         | Begin a new conversation (requires the patient's current region) |
| `arlo_get_conversation`           | Get status and messages for a conversation                       |
| `arlo_cancel_request`             | Stop the current provider request (conversation returns to IDLE) |
| `arlo_update_conversation_region` | Change the region a conversation is licensed for                 |
| `arlo_get_visit_notes`            | Get clinical notes from provider visits                          |

### Messaging

| Tool                | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `arlo_send_message` | Send a message (read-first gate; waits for the reply by default) |
| `arlo_get_media`    | Get download URL for photos/videos                               |

### Profile & Onboarding

| Tool                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `arlo_get_profile`    | Get user profile, patient info, and onboarding funnel state |
| `arlo_update_profile` | Update patient information (data only)                      |
| `arlo_accept_terms`   | Record ToS/Privacy consent and complete onboarding          |

### Prescriptions

| Tool                     | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| `arlo_get_prescriptions` | View prescription history (with fulfillment channel) |
| `arlo_get_prescription`  | Get details of a specific prescription               |

<Note>
  Pharmacy selection is not an agent tool: US prescriptions are fulfilled by Photon Health, which texts the patient to pick a pharmacy and track the order. (Legacy Canadian orders are managed in the Arlo patient portal.)
</Note>

### Billing

| Tool                               | Description                                                                                   |
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `arlo_get_payment_status`          | Get payment status and pay-per-use options                                                    |
| `arlo_create_payment_setup`        | Create a Stripe card-setup session (saves a card; does not charge)                            |
| `arlo_confirm_provider_connection` | Confirm provider connection — places the per-visit hold (the patient's explicit confirmation) |

### Webhooks

| Tool                    | Description                        |
| ----------------------- | ---------------------------------- |
| `arlo_register_webhook` | Register webhook for notifications |

<Note>
  Tool names are prefixed with `arlo_` to avoid conflicts with other plugins.
</Note>

## Configuration

Authentication is handled per-user through OAuth 2.1 with PKCE.

### Webhook Setup (Required for Notifications)

<Warning>
  **Critical:** After a user authenticates, you must explicitly call `register_webhook` with `deliveryContext` and `conversationSessionKey`. These fields are **not** auto-populated from `openclaw.json` — without them, notifications will not be routed to the user's conversation.
</Warning>

For real-time notifications when providers respond, configure webhooks with all required fields:

```javascript theme={null}
{
  webhookUrl: "https://your-agent.com/hooks/arlo",
  webhookToken: "your-secret-token",
  deliveryContext: {
    to: "+15551234567",
    channel: "platform",
    deliver: true
  },
  conversationSessionKey: "agent:main:main"
}
```

| Field                    | Required | Description                                                              |
| ------------------------ | -------- | ------------------------------------------------------------------------ |
| `to`                     | **Yes**  | Recipient identifier (phone number, chat ID, etc.)                       |
| `channel`                | **Yes**  | Platform name (`whatsapp`, `telegram`, `discord`, etc.)                  |
| `deliver`                | No       | Whether to deliver the notification to the user                          |
| `conversationSessionKey` | **Yes**  | Session key for threading notifications back to the correct conversation |

## Notification Handling

When Arlo fires a webhook, OpenClaw wakes the agent session and delivers the notification as a system message. **The agent is then responsible for deciding what to do.**

<Note>
  Simply replying to the session is not enough — heartbeat-triggered replies don't auto-deliver to the user's channel. The agent must proactively push using its channel messaging tool (e.g. `message` action=send for WhatsApp/Telegram, a channel post for Discord, etc.).
</Note>

### Recommended Setup: hooks/wake

The simplest and most reliable approach is OpenClaw's built-in `/hooks/wake` endpoint. Register it as your webhook URL — no custom server needed.

```json theme={null}
{
  "webhookUrl": "https://your-gateway-url.com/hooks/wake",
  "deliveryContext": {
    "to": "+15551234567",
    "channel": "platform",
    "deliver": true
  },
  "conversationSessionKey": "agent:main:main"
}
```

When Arlo fires, OpenClaw wakes the agent with the notification text as a system message. The agent runs, fetches the consultation, and decides how to respond.

### Agent Prompting (Required)

`hooks/wake` requires your agent to know what to do on receipt. Add this to your `HEARTBEAT.md`, system prompt, or equivalent agent instructions:

```
When you receive an [Arlo] webhook notification:
1. Call arlo_get_conversation to fetch the latest message(s)
2. Decide if this warrants notifying the user
3. If yes — push via the appropriate channel messaging tool using the
   channel and recipient from the registered deliveryContext
4. Summarize intelligently — do not copy provider messages verbatim
5. Do NOT just reply in session — that reply will not reach the user

Notify when: provider asked a question, diagnosis/prescription is ready,
something is time-sensitive or action-required.

Stay quiet when: duplicate notification, test/debug messages,
non-urgent status the user didn't ask for.
```

<Tip>
  The `arlo_register_webhook` tool description already includes this guidance inline — any agent using the tool at runtime will see it. The prompting above reinforces it at the environment level for more consistent behavior.
</Tip>

### Alternative: Custom Endpoint

If you need custom processing (filtering, multi-channel fan-out, logging), run your own webhook server and register that URL instead. The plugin makes no assumptions about delivery — it calls whatever URL you register. See the [Webhooks](/mcp-tools/webhooks) tool reference for payload details.

## Correct Post-Connect Flow

After a user successfully authenticates, always register webhooks explicitly:

```javascript theme={null}
// User says: "I've had a sore throat for 3 days"

// 1. Check if user is authenticated
const status = await arlo_auth_status();

if (!status.authenticated) {
  // 2. Start signup flow
  const { authUrl } = await arlo_connect({
    webhookUrl: "https://your-agent.com/hooks/arlo",
    webhookToken: process.env.ARLO_WEBHOOK_SECRET
  });

  // Direct user to authUrl
  return `Please sign up first: ${authUrl}`;
}

// 3. CRITICAL: Register webhook with explicit deliveryContext + sessionKey
const webhookResult = await arlo_register_webhook({
  webhookUrl: "https://your-agent.com/hooks/arlo",
  webhookToken: process.env.ARLO_WEBHOOK_SECRET,
  deliveryContext: {
    to: currentUser.phoneNumber,  // The user's identifier
    channel: "whatsapp",
    deliver: true
  },
  conversationSessionKey: currentConversation.id  // Your session/thread ID
});

// 4. Verify webhook is properly configured
if (!webhookResult.conversationSessionKey) {
  console.error("Warning: conversationSessionKey is null - notifications won't be threaded");
}

// 5. Start the conversation with gathered context (region = patient's current location)
const { conversationId } = await arlo_start_conversation({
  contextMessage: "I've had a sore throat for 3 days...",
  region: "US-CA"
});
```

<Note>
  The `hasDeliveryContext: true` response only indicates an object exists — it does not confirm that `to` or `channel` are set. Always pass these explicitly.
</Note>

## View on npm

<Card title="arlo-health" icon="npm" href="https://www.npmjs.com/package/arlo-health">
  View package on npm for version history and changelog
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Step-by-step guide to your first consultation
  </Card>

  <Card title="Webhooks" icon="bell" href="/mcp-tools/webhooks">
    Configure real-time notifications
  </Card>

  <Card title="Consultation Lifecycle" icon="arrows-spin" href="/concepts/consultation-lifecycle">
    Understand the consultation flow
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full REST API documentation
  </Card>
</CardGroup>