Documentation Bookings and calendars Dentally

Bookings integration

Dentally

Dentally integration overview
  • CategoryBookings
  • AuthPAT
  • Scopes5

Overview

Dentally connects on /integrations in the MessageMind dashboard. Click the Dentally card and the 'Connect Dentally' modal opens with one masked field (apiToken) and the help text 'Paste a Personal Token generated in Dentally, Settings, Developer, Personal Tokens, with the scopes appointment:read, user:read and practice:read, by a Permission Level 4 (administrator) user.' MessageMind sends only that one key on save and uses it as a bearer token on every call to the matching Dentally regional host (UK, APAC, Canada or Sandbox), discovered by probing. The token lets the AI read the practice, its sites and practitioners, check live diary availability, match the conversation's own patient and book new appointments as Pending into the practice's diary.

What MessageMind can do with it

  • Read the practice profile with its time zone and country.
  • Read sites and active practitioners (the diary columns) across the practice.
  • Check live appointment availability for a practitioner on a chosen date or date and time.
  • Create a Pending appointment on a practitioner's diary from a chosen date and time.
  • Match the conversation's own patient by the emails and phone numbers already on the contact, then read their upcoming appointments to answer 'when is my appointment?'.
  • Honour the practice's appointment reasons and length defaults from the Dentally payment plan.

Requirements

  • A Dentally practice with API access enabled on the user generating the token.
  • A Personal Token created in Dentally under Settings, Developer, Personal Tokens by a Permission Level 4 (administrator) user, with the appointment:read, user:read and practice:read scopes ticked. Booking also needs appointment:create and patient:read.
  • At least one active practitioner (diary column) on the practice.

How to connect

  1. In Dentally, open Settings, Developer, Personal Tokens and click 'Generate new token' as a Permission Level 4 (administrator) user. Tick appointment:read, user:read and practice:read. Add appointment:create and patient:read for booking. Copy the token straight away (Dentally shows it only once).
  2. In the MessageMind dashboard, open /integrations and click the Dentally card. The 'Connect Dentally' modal opens.
  3. Paste the token into the single apiToken field (placeholder 'Paste your Dentally API token'). The field is masked by default with a reveal toggle.
  4. Click Integrate. A 'Connecting to Dentally...' toast appears while MessageMind discovers the region (UK, APAC, Canada or Sandbox) by probing each host for the token, then reads the practice, sites, practitioners and a one-row appointment list to prove every scope the sync depends on.
  5. On success the toast flips to 'Dentally connected.' and the reveal toggle resets. On failure the toast carries the server message; a generic 500 reads 'Something went wrong on our side. Please contact support and mention Dentally.'

Authentication and permissions

Mechanism
Personal Token issued by a Permission Level 4 (administrator) Dentally user, sent as a bearer token on every request to the matching Dentally regional host (api.dentally.co for UK, api.apac.dentally.com, api.ca.dentally.com or api.sandbox.dentally.co). No OAuth, no refresh.
Credentials
A single bearer token plus the discovered region, stored on the MessageMind tenant. A mandatory User-Agent is sent on every call.

Required scopes

  • appointment:read
  • user:read
  • practice:read
  • appointment:create
  • patient:read

Available data and actions

Reads

  • The connected user's own record and the scopes granted on the token.
  • The practice (name, time zone, country, slug) and its sites.
  • Active practitioners across the practice (the diary columns), optionally per site.
  • Appointments on a date, with their patient id, times, practitioner, reason and status (patient data).
  • Live availability windows for a practitioner, future only.
  • Existing practice patients matched using both full name and email; additional details may be used to resolve an ambiguous match. This booking flow does not create a new patient.

Writes

  • New Pending appointments on a chosen practitioner, date and time, with a reason the patient's own words matched.
  • Updates to existing appointments (never with Dentally's double-booking override).

AI agent use cases

  • Offer the next free time for a named practitioner or an appointment type the patient asked for, in a WhatsApp, SMS or phone call thread.
  • Collect the patient's full name and email in-thread (always both, because a surname alone matches many patients), confirm the slot, and book it as Pending in the diary.
  • Answer 'when is my next appointment?' by looking up the patient from the chat's own contact details, with no new personal data entered.
  • Refuse appointment types the practice does not take over the AI (unmatched words go to reception) so the practice keeps clinical triage out of the bot.

Configuration

  • Region: UK, APAC, Canada or Sandbox, discovered at connect by probing each host; a Sandbox token is only accepted on the Sandbox host.
  • Rate limits: 3,600 requests per hour per user, with availability further capped at 200 per hour. Dentally returns these as 403 (never 429), and MessageMind reads the body to tell a rate limit from a scope refusal.
  • Double-booking override: force_changes is stripped from every create and update, so Dentally's refusal on an occupied slot stands.

Example workflows

Book a new appointment

  1. Patient asks for an appointment type the practice supports and names a practitioner or specialty.
  2. The AI checks live availability on the matching practitioner's diary for the chosen window and quotes an open slot.
  3. The AI asks for the patient's full name and email, confirms the slot back, and only then books.
  4. The appointment is written to Dentally as Pending with the matched reason, a diary note that identifies the channel (WhatsApp, SMS, phone or web chat) and the length from the Dentally payment plan default.

Limitations

  • A Dentally Personal Token lives on exactly one region. The token is refused by every other region, so the correct host is found by probing on connect.
  • Rate limits are returned as 403, not 429. A 403 can therefore mean the hourly limit, API access switched off on the user, or a missing scope; MessageMind reads the error body to tell them apart.
  • Dentally refuses a double booking (422) and the refusal is final. The AI never sends the force_changes override.
  • Appointment types the AI can take are limited to a fixed list of words the practice's own patients used; anything else is handed to reception rather than guessed at.

Troubleshooting

Submit toasts 'Please paste your Dentally API token.'

The apiToken field was empty on save. Paste the Personal Token into the single field and click Integrate again.

Connect fails because Dentally did not recognise the token on any of its regions.

The token is shown only once by Dentally. Re-generate it in Settings, Developer, Personal Tokens as a Permission Level 4 (administrator) user, and copy it whole. A revoked or deleted token also lands here.

Connect reports a missing scope.

Generate a new token in Dentally with the named scopes ticked (appointment:read, user:read and practice:read are required; appointment:create and patient:read are needed for booking) and reconnect.

Connect succeeds but booking later refuses with a scope error.

appointment:create is not proven at connect. Generate a new token with it ticked and reconnect.

The connect toast reads 'Something went wrong on our side. Please contact support and mention Dentally.'

A generic server 500. Contact MessageMind support with the time of the attempt and mention Dentally so the right logs can be pulled.

Disconnect and reconnect

  • In the MessageMind dashboard, open /integrations, select Dentally and choose Disconnect. The stored token and region are removed from the tenant.
  • Appointments already written in Dentally stay in the practice's diary; disconnecting does not cancel them.
  • To reconnect, generate a fresh token in Dentally with the required scopes and paste it into the connection form.