Halaxy Setup Integration Guide

Halaxy Setup

Connect your Halaxy practice management system to QuackChat for live appointment availability. Halaxy uses a FHIR-compliant API, making integration straightforward and self-service.

Prerequisites

• A QuackChat account on the Pro plan or above
• The Halaxy account owner (only the owner can buy the API add-on)
• A practice on Halaxy's Australian service. Practices on Halaxy's UK or EU service are not supported yet

QuackChat's Halaxy connection is read-only: it shows live availability in the chat and sends patients to your Halaxy booking page to confirm. It never creates or changes appointments.

Step 1: Purchase the API Add-on

Halaxy's API access is a paid add-on subscription:

1. Log in to Halaxy as the account owner
2. Navigate to Settings > Add-ons > Group Add-ons
3. Click Add a Subscription and choose Purchase Halaxy API

The add-on costs 150 Halaxy credits a month and comes with a 30-day free trial (Guide to Halaxy API). It is billed separately from your main Halaxy subscription.

Step 2: Create an API Key

1. Go to Settings > Integrations, then the External tab
2. Click Create New Key
3. Name it something descriptive (e.g. "QuackChat Integration")

The owner can let another user manage keys via Settings > Users > API Key Manager.

Step 3: Configure Permissions

Each key has Retrieve, Create and Update toggles per resource. QuackChat needs Retrieve on three resources, and nothing else:

Principle of least privilege: leave Create and Update off. QuackChat never writes to your Halaxy data. The connection test fails with a clear message if Healthcare Services is missing.

Step 4: Copy Your Credentials

After creating the API key, you will see:

• Client ID: a unique identifier for your API key
• Client Secret: a secret value (shown only once)

Important: Copy the Client Secret immediately. Halaxy only shows it once during creation. If you lose it, you'll need to create a new API key.

Step 5: Enter Credentials in QuackChat

1. Open your bot's workspace in QuackChat
2. Go to Integrations and create a new PMS connection
3. Select Halaxy as the provider
4. Set the connection mode to Live Availability
5. Enter your credentials:
   • Client ID: paste the Client ID from Halaxy
   • Client Secret: paste the Client Secret from Halaxy
6. Set your practice's time zone. This is required for Halaxy: Halaxy returns appointment times in UTC, and QuackChat converts them to your clinic's clock. A practice spanning more than one time zone will see the other locations offset
7. Under Booking & Contact, add your Halaxy booking page link so the assistant can send patients there to confirm
8. Save the connection

Step 6: Test the Connection

1. Click Test Connection in QuackChat to verify connectivity
2. A successful test will show a green "Healthy" status
3. Try asking your bot about appointment availability to confirm end-to-end functionality

Step 7: Configure Webhooks (Optional)

Webhooks allow Halaxy to notify QuackChat of changes in real-time (e.g., cancelled appointments):

1. In Halaxy, go to Settings > Integrations > Webhooks
2. Click Add Webhook
3. Enter the QuackChat webhook URL (provided in your integration settings)
4. In the Authentication Header field, paste the webhook secret QuackChat showed when the connection was created (contact support if you need it re-issued. Rotating it invalidates the old value immediately)
5. Select the events you want to receive notifications for:
   • Appointment created
   • Appointment updated
   • Appointment cancelled
6. Save the webhook

Webhooks are optional but recommended for keeping availability data fresh without polling. The authentication header lets QuackChat verify deliveries really come from your Halaxy account. Without it, the events are ignored.

Halaxy FHIR API Details

Halaxy implements the HL7 FHIR R4 standard. QuackChat uses the following FHIR resources:

• Slot: available appointment time slots
• Schedule: practitioner schedules and availability windows
• Practitioner: clinician details
• PractitionerRole: practitioner-location-service associations
• HealthcareService: appointment types and service categories
• Appointment: existing appointments (for conflict detection)

Troubleshooting

"401 Unauthorized" errors

• Verify your Client ID and Client Secret are correct
• Confirm the API add-on subscription is active in Halaxy Settings
• Check that you haven't exceeded API rate limits

"403 Forbidden" on specific resources

• Review the key's permissions under Settings > Integrations > External in Halaxy
• Ensure Retrieve is on for Practitioners, Appointments and Healthcare Services

Times look hours out

• Check the time zone set on the QuackChat connection matches your practice

No available slots returned

• Verify practitioners have schedules configured in Halaxy and online bookings are allowed for their appointment types
• Check that appointment types are set up and linked to practitioners
• Ensure the Halaxy calendar has availability for the dates being queried

Connection test passes but bot shows no availability

• Confirm at least one practitioner has open slots in the Halaxy calendar
• Check that services are configured and associated with practitioners
• Verify the operating hours in QuackChat align with your Halaxy schedule settings

API add-on expired

• If the Halaxy API add-on subscription lapses, all API calls will fail
• Renew the subscription in Settings > Add-ons and the connection will resume

Auto-disabled connection (5 consecutive failures)

• The connection will auto-disable after 5 consecutive sync failures
• Fix the underlying issue, then re-enable the connection using the Active toggle
• Click Test Connection to verify before re-enabling