Afspraken-API (CRM-integratie)

Draai je een eigen CRM, ERP of boekingsscherm, dan kun je Conviro-afspraken daarvandaan aansturen via een eenvoudige REST-API. API-boekingen gebruiken dezelfde motor als boeken in de chat: beschikbaarheid wordt serverzijdig herberekend op basis van je werktijden en je gekoppelde agenda (Google, Outlook of een ICS-feed), de klant ontvangt de bevestigingsmail met agendabestand en beheerlink, en je team krijgt de gebruikelijke meldingen.

Vereisten

1. Afspraken ingesteld voor je assistent: Dashboard -> Assistants -> [je bot] -> Setup -> Scheduling.
2. Een gekoppelde agenda: Google Calendar, Outlook / Microsoft 365, een ICS-feed (Apple/iCloud, Fastmail, Nextcloud, ...) of de ingebouwde interne agenda.
3. Een API-sleutel met de juiste scopes: Dashboard -> Settings -> API Keys; vink Appointments Read en/of Appointments Write aan.

Authenticatie

Stuur je sleutel bij elk verzoek mee in de Authorization-header:

Authorization: Bearer YOUR_API_KEY

Basis-URL: https://api.conviro.io

1. Vrije tijdsloten opvragen

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

• date (optioneel) — een lokale datum (YYYY-MM-DD) in de tijdzone van de assistent; zonder deze parameter de eerstvolgende beschikbare dag.
• serviceId (optioneel) — een van de services uit het antwoord.

Het antwoord bevat timeZone, je services en slots als { start, end }-paren in UTC ISO-formaat.

2. Een afspraak boeken

Vereist de scope appointments:write. API-boekingen zijn vertrouwd — er wordt geen e-mail-OTP verstuurd, want jouw systeem kent de identiteit van de klant al.

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"
  }'

Gebruik een startIso uit het slots-endpoint. De server valideert het slot opnieuw vóór het boeken — is het intussen bezet, dan krijg je 400 ("niet meer beschikbaar"): haal de slots opnieuw op en probeer opnieuw.

3. Afspraken opvragen

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

Filters: status (bijv. confirmed, cancelled), limit (max 200), offset. Vereist appointments:read.

4. Een afspraak annuleren

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

Vereist appointments:write. Annuleren verwijdert het event ook uit de gekoppelde agenda en informeert je team.

Webhooks — houd je CRM synchroon

Abonneer je onder Dashboard -> Developers -> Webhooks op:

• appointment.booked — vuurt bij elke bevestigde boeking (chat, boekingswidget of API)
• appointment.cancelled — vuurt bij elke annulering

De payload bevat appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone en channel — alles om de boeking in je CRM te spiegelen.

Agenda-opties in één oogopslag

> Tip: API-sleutels hebben een rate-limit per sleutel. Synchroniseer je grote volumes, gebruik dan webhooks in plaats van het lijst-endpoint te pollen.