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
• Halaxy account with admin access
• A credit card for the Halaxy API add-on (30-day free trial available)

Step 1: Purchase the API Add-on

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

1. Log in to your Halaxy account
2. Navigate to Settings > Add-ons
3. Find the API add-on
4. Subscribe (approximately $27-33 AUD/month, with a 30-day free trial)

The API add-on is billed separately from your main Halaxy subscription.

Step 2: Create an API Key

1. Go to developers.halaxy.com
2. Log in with your Halaxy account credentials
3. Navigate to the API keys section
4. Click Create New API Key
5. Name it something descriptive (e.g. "QuackChat Integration")

Step 3: Configure Permissions

Grant the minimum required permissions for QuackChat to query availability:

Principle of least privilege: Only grant the permissions listed above. QuackChat never needs write access to your Halaxy data.

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. 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 permissions on your API key at developers.halaxy.com
• Ensure all six required resource permissions are granted (Appointment, Practitioner, PractitionerRole, HealthcareService, Schedule, Slot)

No available slots returned

• Verify practitioners have schedules configured in Halaxy
• 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