This guide explains how to connect OpenEMR to the Newo Platform, configure credentials, and enable AI-powered appointment availability checks, booking, and cancellation for medical practices and clinics.

Overview

The OpenEMR integration connects OpenEMR — an open-source electronic health records and medical practice management system — with the Newo Platform. Once configured, the AI agent can:

Check available appointment slots for a selected provider and facility
Book appointments with automatic patient record search and creation
Cancel existing appointments
Use pre-selected facility and provider settings configured during setup

OAuth2 token management is handled automatically, including token refresh on expiration.

⚠️ CAUTION

This integration performs real operations in OpenEMR. Appointments created or cancelled through the agent are reflected immediately in your live OpenEMR system. Always test with non-production data or a staging environment before going live.

Requirements

Before connecting OpenEMR to the Newo Platform, confirm the following:

An active OpenEMR instance with the REST API enabled
An OAuth2 Client ID and Client Secret registered in OpenEMR
A username, password, and email for an OpenEMR user with API access permissions for appointments and patient management
The OpenEMR instance must be accessible via HTTPS from the platform

Step 1: Get API credentials from OpenEMR

Log in to your OpenEMR instance as an administrator.
Navigate to Administration → System → API Clients.
Register a new OAuth2 client application.
Note the Client ID and Client Secret — you will need these in Step 2.
Confirm the API user has appropriate permissions for appointments and patient management.

Step 2: Connect in the Newo Platform

Open Newo → Projects and select the relevant project.
In the Builder, navigate to Attributes.
Set the following attributes:

Attribute	Required	Description
`openemr_base_url`	Yes	Base URL of your OpenEMR instance (e.g., `https://emr.example.com`)
`openemr_client_id`	Yes	OAuth2 Client ID
`openemr_client_secret`	Yes	OAuth2 Client Secret
`openemr_username`	Yes	OpenEMR username for API access
`openemr_password`	Yes	OpenEMR user password
`openemr_email`	Yes	OpenEMR user email address
`openemr_scope`	No	OAuth2 scopes (pre-configured with full access; typically does not need manual entry)
`openemr_facility`	No	Selected facility (auto-populated during setup)
`openemr_provider`	No	Selected provider (auto-populated during setup)
`openemr_enable_slot_check`	No	Enable availability checks (default: `True`)
`openemr_enable_booking`	No	Enable appointment creation (default: `True`)
`openemr_enable_cancellation`	No	Enable appointment cancellation (default: `True`)
`openemr_check_existing_client`	No	Check if a patient record exists before creating a new one (default: `True`)
`openemr_show_for_days`	No	Number of days ahead to check for available slots
`openemr_override_agent_attributes`	No	Override SuperAgent attribute schemas (default: `True`)

Click Save + Publish All.

What happens on publish

When you publish, the integration automatically:

Exchanges the provided credentials for an OAuth2 access token (password grant)
Creates HTTP connectors for API and token operations
Fetches all facilities and populates the openemr_facility dropdown
Fetches providers for the selected facility and populates the openemr_provider dropdown
Registers availability, booking, and cancellation tools with the agent
Injects the required payload schemas

Facility and provider selection

The OpenEMR integration uses a pre-selection model rather than dynamic, per-conversation selection.

During setup, all facilities are fetched and presented as an enum dropdown in the openemr_facility attribute. After you select a facility, the providers for that facility are fetched and presented similarly in openemr_provider. These selections are stored and used for all subsequent availability checks and bookings.

🗒️ NOTE

To switch to a different facility or provider, update the openemr_facility attribute and click Publish All to refresh the provider list and re-register the tools.

Patient information required for booking

When booking an appointment, the agent collects the following patient details:

Field	Required
First name	Yes
Last name	Yes
Date of birth (YYYY-MM-DD)	Yes
Sex (Male/Female)	Yes
Phone number	Yes
Middle name	No

If the phone number is not available at the start of the conversation, the agent will ask for it before proceeding with the booking.

If openemr_check_existing_client is set to True, the integration searches for an existing patient record before creating a new one.

Default appointment settings

All appointments created through the integration use the following defaults:

Duration: 15 minutes
Title: "Office Visit"

These defaults are applied automatically and do not require additional configuration.

How OAuth2 token management works

The integration handles token lifecycle automatically:

On setup, an access token is obtained using the password grant with the stored credentials.
If a request returns a 401 Unauthorized response, the integration detects the expired token and attempts a refresh.
If a refresh token is available, it uses the refresh_token grant to obtain a new access token.
If no refresh token exists, it falls back to the password grant using the stored credentials.
The original request is retried automatically up to 3 times.

No manual token rotation is required.

Test the integration

Test the integration through the Newo conversation interface (voice or chat).

Setup verification: After publishing, confirm that openemr_access_token is populated. An empty token indicates a credential or connectivity issue.
Facility check: Verify that the openemr_facility dropdown is populated with your clinics.
Provider check: Verify that the openemr_provider dropdown shows providers for the selected facility.
Availability: Ask the agent "What slots are available on Monday?" and verify that slots are returned with correct times.
Booking: Complete a booking conversation and verify that the appointment appears in the OpenEMR calendar.
Cancellation: Request cancellation of a booked appointment and verify that the appointment is removed from OpenEMR.

Troubleshooting

If the agent does not respond to availability, booking, or cancellation requests, check the following:

Confirm openemr_base_url, openemr_client_id, and openemr_client_secret are entered correctly.
Verify that openemr_username, openemr_password, and openemr_email are valid and belong to an OpenEMR user with API access.
Check that openemr_access_token is not empty after publish — an empty token means the credential exchange failed.
Ensure the relevant feature flags are enabled: openemr_enable_booking, openemr_enable_slot_check, openemr_enable_cancellation.
Verify that openemr_facility and openemr_provider were populated during setup.
Confirm that the OpenEMR REST API is enabled and accessible via HTTPS from the platform.
If credentials were changed after the initial setup, click Publish All again to re-run the token exchange and update the connectors.

Limitations

Limitation	Details
Multi-provider scheduling	Not supported. A single provider is selected during setup.
Reschedule appointment	Not supported. Cancel the existing appointment and create a new booking as a workaround.
Historical data import	Only appointments created after activation are managed by the integration.

FAQ

How does facility and provider selection work? During setup, all facilities are fetched and presented as an enum dropdown. After selecting a facility, providers for that facility are fetched and presented similarly. These selections are stored and used for all subsequent availability checks and bookings. To switch, update openemr_facility and re-publish.

What happens if the OAuth token expires? The integration detects 401 responses automatically. If a refresh token is available, it uses the refresh_token grant. If not, it falls back to the password grant with the stored credentials. The original request is retried up to 3 times.

How many days of availability does the agent check? This is configurable via the openemr_show_for_days attribute.

What is the default appointment duration? 15 minutes. The appointment title defaults to "Office Visit."

Does the integration support multiple facilities simultaneously? No. A single facility and provider are selected during setup. To switch, update openemr_facility and re-publish.

What OAuth2 scopes are required? The integration pre-configures a comprehensive scope set covering appointments, patients, practitioners, locations, and related resources. The openemr_scope attribute is auto-populated during setup and typically does not need manual configuration.

Pre-launch checklist

Before going live with the OpenEMR integration, verify the following:

OpenEMR REST API is enabled and accessible via HTTPS.
OAuth2 Client ID and Client Secret registered in OpenEMR.
openemr_base_url, openemr_client_id, openemr_client_secret, openemr_username, openemr_password, and openemr_email set in Builder Attributes.
Save + Publish All clicked and openemr_access_token confirmed as populated.
openemr_facility dropdown populated with correct clinics.
openemr_provider dropdown populated with providers for the selected facility.
Feature flags configured: openemr_enable_slot_check, openemr_enable_booking, openemr_enable_cancellation.
Test availability, booking, and cancellation verified through the conversation interface.