Appointments API (CRM integration)

If you run your own CRM, ERP, or booking screen, you can drive Conviro appointments from it over a simple REST API. API bookings use the same engine as in-chat booking: availability is recomputed server-side against your working hours and your connected calendar (Google, Outlook, or an ICS feed), the customer gets the confirmation e-mail with a calendar file and a self-service manage link, and your team receives the usual notifications.

Prerequisites

1. Appointments configured for your assistant: Dashboard -> Assistants -> [your bot] -> Setup -> Scheduling.
2. A calendar backend connected — Google Calendar, Outlook / Microsoft 365, an ICS feed (Apple/iCloud, Fastmail, Nextcloud, ...), or the built-in internal calendar.
3. An API key with the right scopes: Dashboard -> Settings -> API Keys, tick Appointments Read and/or Appointments Write.

Authentication

Send your key in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Base URL: https://api.conviro.io

1. List open slots

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments/slots?chatbotId=CHATBOT_ID&date=2026-07-15"

• date (optional) — a local date (YYYY-MM-DD) in the assistant's time zone; omit it for the next available day.
• serviceId (optional) — one of the services returned in the response.

The response contains timeZone, your services, and slots as { start, end } pairs in UTC ISO format.

2. Book an appointment

Requires the appointments:write scope. API bookings are trusted — no e-mail OTP is sent, because your system already owns the customer's identity.

curl -X POST "https://api.conviro.io/v1/api/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "startIso": "2026-07-15T09:00:00.000Z",
    "contactEmail": "[email protected]",
    "contactName": "Jane Doe",
    "contactPhone": "+31 6 00000000"
  }'

Use a startIso taken from the slots endpoint. The server re-validates the slot before booking — if it was taken in the meantime you get a 400 ("no longer available"): refresh the slots and retry.

3. List appointments

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments?status=confirmed&limit=50"

Filters: status (e.g. confirmed, cancelled), limit (max 200), offset. Requires appointments:read.

4. Cancel an appointment

curl -X DELETE "https://api.conviro.io/v1/api/appointments/APPOINTMENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Requires appointments:write. Cancelling also removes the event from the connected calendar and notifies your team.

Webhooks — keep your CRM in sync

Subscribe under Dashboard -> Developers -> Webhooks to:

• appointment.booked — fires for every confirmed booking (chat, booking widget, or API)
• appointment.cancelled — fires whenever a booking is cancelled

The payload includes appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone and channel — everything you need to mirror the booking into your CRM.

Calendar options at a glance

> Tip: API keys are rate-limited per key. If you sync large volumes, prefer webhooks over polling the list endpoint.