NexHealth Integration

What the AI can do

Summary

NexHealth Integration connects NexHealth (dental and healthcare practice management platform) with Newo Platform.

It enables:

• Checking available appointment slots with intelligent provider, operatory, and appointment type matching
• Booking appointments with automatic patient record search and creation
• Cancelling existing appointments
• Multi-location support with AI-powered location selection
• Dynamic filtering by operatories and appointment types
• Auto-configuration of booking/cancellation scenarios on the agent canvas

This integration is designed for dental clinics and healthcare practices who need automated appointment scheduling through a conversational AI agent (voice or chat).

Common use cases

• When a patient asks about available slots → AI selects location, provider, operatory, and appointment type, then returns open time slots
• When a patient wants to book an appointment → Search or create patient record, match slot, and create appointment in NexHealth
• When a patient wants to cancel an appointment → Cancel the appointment via NexHealth API
• When a clinic has multiple locations → AI matches patient's natural language to the correct location
• When a new patient books → Automatically create patient record in NexHealth before booking
• When a conversation starts → Clinic locations are fetched and injected into the agent's context

Features at a glance

Feature	Supported	Notes
Check Availability	✅	Date/time/location with provider + operatory + type filtering
Book Appointment	✅	With automatic patient creation if needed
Cancel Appointment	✅	Requires booking_id from prior booking
Multi-Location Support	✅	AI-powered location matching from conversation
Provider Selection	✅	AI matches appointment preferences to providers
Operatory Filtering	✅	AI matches preferences to treatment rooms
Appointment Type Filtering	✅	AI matches preferences + new patient flag
Patient Search	✅	By phone number via NexHealth API
Patient Creation	✅	Auto-creates during booking flow
Canvas Scenario Setup	✅	Auto-adds booking/cancellation scenarios
Token Auto-Refresh	✅	OAuth bearer token with automatic 401 retry
Reschedule Appointment	❌	Cancel + rebook as workaround
Historical Data Import	❌	Only new events after activation

Before You Start

Before installation:

• Active NexHealth account with API access
• NexHealth API key for OAuth authentication
• NexHealth subdomain (institution identifier)
• At least one location configured in NexHealth

Setup

Create the Newo project

If this project already exists in Newo Builder, skip this subsection and continue with the integration-specific settings below.

1. In Newo Builder, open the projects list and click Create Project (or Create New Project from the top-right menu).

2. Fill IDN and Title. The exact names do not matter; use any clear names your team will recognize.
3. In Registry, choose the release channel:
   • staging — the newest module fixes appear here first. Use it when you need the latest fix, but expect possible unfinished changes.
   • production — the final stable version for live projects.
4. In Module, select the module for this integration.

5. Leave Module version on Latest version unless support tells you to pin a specific version, then click Create.

3.1 Step 1 — Get API Credentials

1. Log in to your NexHealth account
2. Navigate to API settings or developer section
3. Generate or locate your API key
4. Note your subdomain (institution identifier in NexHealth)

3.2 Step 2 — Connect in Platform

1. Open Newo → Projects
2. Set the following attributes in Builder / Attributes:

Attribute	Required	Description
nexhealth_api_key	✅	NexHealth API key for OAuth
nexhealth_subdomain	✅	Institution subdomain in NexHealth
nexhealth_base_url	❌	API base URL (default: https://nexhealth.info)
nexhealth_enable_slot_check	❌	Enable availability checks (default: True)
nexhealth_enable_booking	❌	Enable appointment creation (default: True)
nexhealth_enable_cancellation	❌	Enable cancellations (default: True)
nexhealth_enable_filter_slots_by_operatories	❌	Filter slots by operatories (default: True)
nexhealth_enable_filter_slots_by_appointments_type	❌	Filter slots by appointment types (default: True)
nexhealth_setup_scenarios	❌	Auto-add booking/cancellation scenarios to canvas (default: True)
nexhealth_override_agent_attributes	❌	Override SuperAgent attribute schemas (default: True)

3. Click Save + Publish All
4. On publish, the SetupFlow automatically:
   • Exchanges the API key for an OAuth bearer token
   • Prepares the connections for API and token operations
   • Registers availability, booking, and cancellation tools with the agent
   • Injects payload schemas for the ConvoAgent tool calling framework

How to use the integration

This section explains how the integration works, how to configure automation, and how to test it.

4.1 How the Integration Works

The integration uses NexHealth's REST API (v2) for appointment management, patient records, and clinic data. Slot checking involves a multi-stage AI-powered selection pipeline: location → providers → operatories → appointment types → slots. The OAuth bearer token is auto-refreshed on 401 responses.

• A Trigger is a system event that starts a flow
• An Action is the API operation performed in NexHealth

Where to test

Testing can be done through the Newo conversation interface (voice or chat). Each flow (Availability, Booking, Cancellation, StaticData) has a dedicated webhook test endpoint for connectivity validation.

How to test that everything works

To test the integration:

1. Setup: Publish the project and verify token exchange succeeds (check nexhealth_access_token is populated)
2. Locations: Start a conversation — verify locations are loaded (agent should know about available clinics)
3. Availability: Ask "What slots are available on Monday?" — verify slots returned with correct times
4. Booking: Complete a booking conversation — verify appointment appears in NexHealth dashboard
5. Cancellation: Request cancellation of a booked appointment — verify status changed in NexHealth

If no action occurs:

• Ensure nexhealth_api_key and nexhealth_subdomain are set correctly
• Verify nexhealth_access_token was obtained (check it's not empty after setup)
• Confirm the relevant feature flags are enabled (nexhealth_enable_booking, nexhealth_enable_slot_check, nexhealth_enable_cancellation)
• Check that locations were fetched on session start
• Re-publish the project if credentials were changed

Note: This integration performs real operations in NexHealth. Appointments created or cancelled through the agent are reflected in the live NexHealth system.

FAQ

Q: How does the agent select the right provider and operatory? A: The integration uses a multi-stage AI pipeline. After location selection, it fetches all providers, operatories, and appointment types, then uses LLM (Gemini/GPT-4) with low temperature (0.2) to match each against the patient's stated appointment preferences and new patient status. Only active, online-bookable options are considered.

Q: How many days of availability does the agent check? A: By default, 5 days starting from the requested date. The API call uses days=5 parameter.

Q: What patient information is required for booking? A: First name, last name, phone number (E.164 format), and date of birth are required. Email is optional. If the phone number is not available, the agent will ask the patient for it before proceeding.

Q: What happens if the OAuth token expires? A: The UtilsFlow automatically detects 401 responses and refreshes the token using the API key. The original request is retried up to 3 times. This is transparent to the conversation flow.

Q: Does the integration support operatory and appointment type filtering? A: Yes, both are enabled by default. You can disable them individually via nexhealth_enable_filter_slots_by_operatories and nexhealth_enable_filter_slots_by_appointments_type attributes.

Q: What scenarios are auto-added to the canvas? A: When nexhealth_setup_scenarios=True (default), the integration adds booking and cancellation scenarios with corresponding intents to the agent canvas on setup. This includes step-by-step conversation flows for scheduling and cancelling appointments.

Q: Which LLM models are used? A: Gemini 2.5 Flash for most operations (location selection, provider matching). GPT-4 for operatory filtering, appointment type matching, and scenario generation. Gemini 2.5 Pro for patient lookup processing.