Voor ontwikkelaars

Ring AI API

Beheer de instellingen en de prompt van uw AI-telefonist en haal gesprekken met samenvatting en transcript op, rechtstreeks vanuit uw eigen systemen. Zo automatiseert u de belangrijkste instellingen uit het dashboard.

Overzicht

Basis-URL: https://ringai.nl/api. Alle verzoeken en antwoorden zijn JSON (UTF-8), alle tijden zijn ISO 8601 in UTC.

OnderdeelWat u ermee doetToegang
Beheer-APIInstellingen, prompt en gesprekken beheren met een vaste sleutel, zonder wachtwoord. Bedoeld voor koppelingen.Beheersleutel (Business)
Instellingen en promptNaam, stem, taal, prompt, begroeting, openingstijden, meldingsadres en webhook lezen en wijzigenInlogtoken (beheerder)
GesprekslogsGesprekken zoeken, transcript ophalen, afvinken en notities zettenInlogtoken
ConnectorGesprekken ophalen en bijwerken met een vaste sleutel, zonder wachtwoordConnector-sleutel
WebhookRing AI stuurt na elk gesprek de gegevens naar uw eigen URLUw eigen sleutel

Beheersleutel (Business)

Met een beheersleutel beheert uw eigen systeem de instellingen, de prompt en de gesprekken, zonder wachtwoord en zonder token dat verloopt. Dit is de aanbevolen manier voor koppelingen.

  1. Log in op het dashboard met het hoofdaccount en ga naar het blok API-beheer.
  2. Klik op Beheersleutel aanmaken. De sleutel (begint met rk_) wordt maar een keer getoond. Ring AI bewaart hem zelf niet en kan hem dus ook niet terughalen.
  3. Stuur de sleutel mee in de header X-API-Key bij elk verzoek naar https://ringai.nl/api/v1/....
Alleen Business. De beheersleutel is beschikbaar in het Business-abonnement. Stapt u over naar een ander abonnement, dan werkt de sleutel direct niet meer (402). Een nieuwe sleutel maken laat de vorige meteen vervallen. Intrekken kan altijd in het dashboard.
curl -s https://ringai.nl/api/v1/me -H "X-API-Key: rk_..."
{"tenant": "Voorbeeld BV", "tenant_id": "a146...", "plan": "business"}

Routes van de beheer-API

Alle routes gebruiken de header X-API-Key. Verzoeken, antwoorden en velden zijn gelijk aan de routes met inlogtoken die verderop staan beschreven.

RouteWatZie
GET /api/v1/meWelk bedrijf en abonnement bij de sleutel horen
GET /api/v1/configInstellingen en prompt lezenvelden
PUT /api/v1/configInstellingen en prompt wijzigen (alleen meegestuurde velden)velden
GET/PUT /api/v1/klantbevestigingWhatsApp-bevestiging aan de belleruitleg
GET/PUT /api/v1/klantherkenningTerugkerende bellers herkennenuitleg
GET /api/v1/callsGesprekken. Parameters limit (max 200), offset, q en sincevelden
GET /api/v1/calls/{id}Eén gesprek met transcriptvelden
POST /api/v1/calls/{id}/annotateAfvinken en/of notitie zettenbody
POST /api/v1/calls/{id}/followup/doneTerugbelverzoek afgehandeld
GET /api/v1/statsTotalen en openstaande terugbelverzoekenvoorbeeld
GET /api/v1/stats/daily?days=30Per dag, maximaal 90 dagenvoorbeeld
GET /api/v1/usage/monthly?months=6Gesprekken en minuten per maand, maximaal 24 maandenvoorbeeld

Alleen nieuwe gesprekken ophalen

Met since (ISO 8601, bijvoorbeeld 2026-11-20T08:00:00Z) krijgt u alleen gesprekken die op of na dat moment begonnen. Bewaar het tijdstip van uw vorige ophaalronde en geef dat mee.

curl -s "https://ringai.nl/api/v1/calls?since=2026-11-20T08:00:00Z&limit=200" \
  -H "X-API-Key: rk_..."

Prompt wijzigen

curl -s -X PUT https://ringai.nl/api/v1/config \
  -H "X-API-Key: rk_..." -H "Content-Type: application/json" \
  -d '{"system_prompt": "Je bent Emma, de telefonist van Voorbeeld BV. ...", "greeting": "{begroeting}, u spreekt met Emma, de AI-assistent van Voorbeeld BV."}'
AI-melding verplicht. Sinds 2 augustus 2026 moet de beller horen dat hij met een AI spreekt (artikel 50 AI-verordening). Een nieuwe greeting via de beheer-API moet dat daarom vermelden, bijvoorbeeld "u spreekt met Emma, de AI-assistent van Voorbeeld BV". Zonder die vermelding volgt 422. Een lege begroeting mag: dan gebruikt Ring AI de standaardbegroeting, die de AI-melding al bevat.

Maximaal 120 verzoeken per minuut. Daarboven volgt 429 met de header Retry-After.

Authenticatie

Naast de beheersleutel kent de API twee andere manieren van toegang.

1. Inlogtoken (voor instellingen, prompt en gesprekken)

Log in met het e-mailadres en wachtwoord van uw Ring AI-account. U krijgt een access_token (24 uur geldig) en een refresh_token waarmee u een nieuw token haalt zonder opnieuw het wachtwoord te sturen. Stuur het token mee in de header Authorization: Bearer <access_token>.

POST/api/auth/logingeen
curl -s -X POST https://ringai.nl/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "beheer@uwbedrijf.nl", "password": "uw-wachtwoord"}'
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "role": "admin"
}
POST/api/auth/refreshgeen
curl -s -X POST https://ringai.nl/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOi..."}'

Het antwoord heeft dezelfde vorm als bij inloggen: een nieuw access-token en een nieuw refresh-token.

Rollen. Instellingen wijzigen kan alleen met het hoofdaccount (rol admin). Een extra gebruiker, zoals een gedeelde balie-login (rol balie), kan gesprekken inzien maar krijgt bij instellingen een 403. Maak voor een koppeling bij voorkeur geen gebruik van een persoonlijk wachtwoord dat vaak wijzigt.

2. Connector-sleutel (alleen gesprekken)

Een vaste sleutel per bedrijf, zonder wachtwoord en zonder verloopdatum. Geschikt voor CRM-koppelingen die gesprekken ophalen. U vindt de sleutel in het dashboard onder Odoo / Connector-key. Stuur hem mee in de header X-Connector-Key. Zie Connector.

Behandel beide als wachtwoord: niet in een website of app-code zetten die anderen kunnen inzien.

Foutcodes

CodeBetekenis
401Ongeldig of verlopen token of sleutel. Bij een verlopen access-token: vernieuw via /api/auth/refresh.
402De functie hoort niet bij uw abonnement (bijvoorbeeld de beheersleutel buiten Business).
403De header Authorization ontbreekt, het account is gedeactiveerd, of deze actie is alleen voor de beheerder.
404Gesprek of configuratie niet gevonden.
409Kan nu niet, bijvoorbeeld omdat een voorwaarde nog niet is ingericht. Zie detail.
422Het verzoek klopt niet (verkeerd veldtype of ontbrekend veld).
429Te veel verzoeken. Wacht het aantal seconden uit de header Retry-After.

Een fout komt altijd terug als {"detail": "uitleg"}.

Instellingen en prompt

GET/api/bot/configinlogtoken, beheerder
curl -s https://ringai.nl/api/bot/config \
  -H "Authorization: Bearer $TOKEN"
{
  "id": "9c1e...",
  "bot_name": "Emma",
  "voice": "marin",
  "language": "nl",
  "company_info": "Installatiebedrijf in Utrecht, werkt in de hele provincie.",
  "system_prompt": "Je bent Emma, de telefonist van ...",
  "greeting": "{begroeting}, u spreekt met Emma, de AI-assistent van Voorbeeld BV.",
  "tools_enabled": {"app_na_afloop": false},
  "after_hours_message": "Wij zijn nu gesloten. Ik noteer uw vraag en we bellen u morgen terug.",
  "office_hours": {"ma": ["08:30", "17:30"], "di": ["08:30", "17:30"]},
  "notification_email": "info@uwbedrijf.nl",
  "webhook_url": null,
  "webhook_api_key": null,
  "webhook_enabled": false,
  "updated_at": "2026-11-20T09:12:44Z"
}
PUT/api/bot/configinlogtoken, beheerder

Stuur alleen de velden mee die u wilt wijzigen. Velden die u weglaat, blijven zoals ze waren. Het antwoord is de volledige, bijgewerkte configuratie. Een wijziging geldt vanaf het eerstvolgende gesprek.

curl -s -X PUT https://ringai.nl/api/bot/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"greeting": "{begroeting}, u spreekt met Emma, de AI-assistent van Voorbeeld BV. Waarmee kan ik helpen?"}'
VeldTypeUitleg
bot_nametekstNaam waarmee de telefonist zich voorstelt.
voicetekstStem: marin, cedar, alloy, ash, ballad, coral, echo, sage, shimmer of verse.
languagetekstTaalcode van twee letters (nl, en, de, ...) of auto om de taal van de beller te volgen.
company_infotekstAchtergrondinformatie over uw bedrijf: diensten, werkgebied, prijzen, veelgestelde vragen.
system_prompttekstDe instructie voor de telefonist: hoe hij zich gedraagt en wat hij doet. Leeg laten betekent: de standaardinstructie van Ring AI op basis van uw bedrijfsgegevens.
greetingtekstEerste zin bij opnemen. {begroeting} wordt vervangen door goedemorgen, goedemiddag of goedenavond.
after_hours_messagetekstExtra instructie buiten de openingstijden.
office_hoursobjectOpeningstijden per dag, zie hieronder.
notification_emailtekstAdres dat na elk gesprek de samenvatting krijgt.
webhook_urltekstUw URL voor de webhook.
webhook_api_keytekstSleutel die Ring AI meestuurt naar uw webhook.
webhook_enabledtrue/falseWebhook aan of uit.

Openingstijden

Per dag een begin- en eindtijd (Nederlandse tijd), met de dagsleutels ma, di, wo, do, vr, za en zo. Een dag die ontbreekt, geldt als gesloten. Laat u office_hours helemaal leeg, dan bent u altijd open.

{"office_hours": {
  "ma": ["08:30", "17:30"], "di": ["08:30", "17:30"], "wo": ["08:30", "17:30"],
  "do": ["08:30", "17:30"], "vr": ["08:30", "16:00"]
}}
Gebruik precies dit formaat. Andere schrijfwijzen, zoals "monday": {"open": ..., "close": ...}, worden niet herkend en gelden als gesloten.

Klantbevestiging (WhatsApp naar de beller)

GET/api/bot/klantbevestiginginlogtoken, beheerder
{"aan": false, "beschikbaar": true, "module_gekocht": false, "module_prijs": "9,95",
 "plan": "business", "vereist_plan": "professional", "afzender_klaar": true, "afzender": "+3185..."}
PUT/api/bot/klantbevestiginginlogtoken, beheerder
curl -s -X PUT https://ringai.nl/api/bot/klantbevestiging \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"aan": true}'

Geeft 402 als uw abonnement de functie niet heeft, en 409 als uw nummer nog niet als WhatsApp-afzender is ingericht.

Klantherkenning (terugkerende bellers)

GET/api/bot/klantherkenninginlogtoken, beheerder
{"aan": true, "aan_sinds": "2026-11-17T10:02:11+00:00", "beschikbaar": true, "proef": false,
 "plan": "business", "pro_prijs": "78,51", "bellers_90d": 214, "terugkerend_90d": 41,
 "gesprekken_terugkerend_90d": 117, "gesprekken_90d": 380}
PUT/api/bot/klantherkenninginlogtoken, beheerder

Body {"aan": true} of {"aan": false}. Geeft 402 als uw abonnement de functie niet heeft.

Gesprekslogs

GET/api/calls/inlogtoken

Lijst van gesprekken, nieuwste eerst.

ParameterStandaardUitleg
limit50Aantal gesprekken per pagina.
offset0Aantal over te slaan gesprekken, voor de volgende pagina.
qZoekterm in naam, nummer, samenvatting, notitie en transcript.
curl -s "https://ringai.nl/api/calls/?limit=20&q=offerte" \
  -H "Authorization: Bearer $TOKEN"
[{
  "id": "3f0b...",
  "caller_number": "+31612345678",
  "caller_name": "J. de Vries",
  "started_at": "2026-11-20T08:41:02Z",
  "ended_at": "2026-11-20T08:43:15Z",
  "duration_seconds": 133,
  "summary": "Vraagt een offerte voor een warmtepomp, wil teruggebeld worden.",
  "needs_followup": true,
  "followed_up": false,
  "user_note": null,
  "notification_sent": true,
  "direction": "inbound",
  "to_number": "+31851234567",
  "outbound_status": null
}]
GET/api/calls/{id}inlogtoken

Eén gesprek met alle velden uit de lijst, plus transcript (lijst van uitspraken van beller en telefonist), caller_history (maximaal 5 eerdere gesprekken van dezelfde beller) en caller_total_count.

POST/api/calls/{id}/annotateinlogtoken

Vink een gesprek af en/of zet een eigen notitie. Beide velden zijn optioneel.

curl -s -X POST https://ringai.nl/api/calls/3f0b.../annotate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"followed_up": true, "user_note": "Offerte verstuurd op 20-11"}'
POST/api/calls/{id}/followup/doneinlogtoken

Markeert het terugbelverzoek als afgehandeld (needs_followup wordt false). Geen body nodig.

Statistieken

GET/api/calls/statsinlogtoken
{"total_calls": 380, "total_duration_minutes": 912.4, "avg_duration_seconds": 144.1,
 "calls_today": 7, "calls_this_week": 31, "followup_pending": 4}
GET/api/calls/stats/daily?days=30inlogtoken

Aantal gesprekken en seconden per dag, maximaal 90 dagen. Dagen zonder gesprekken staan erin met 0.

{"days": [{"date": "2026-11-19", "count": 12, "seconds": 1740}, ...]}
GET/api/calls/usage/monthly?months=6inlogtoken

Gesprekken en minuten per maand, nieuwste eerst. Maanden zonder gesprekken staan er niet in.

{"usage": [{"month": "2026-11", "calls": 210, "minutes": 498.3}, ...]}

Connector-sleutel

Voor koppelingen die alleen gesprekken nodig hebben. Werkt met de header X-Connector-Key, zonder wachtwoord. De sleutel geeft alleen toegang tot de gesprekken van uw eigen bedrijf, niet tot de instellingen.

GET/api/connector/meconnector-sleutel
curl -s https://ringai.nl/api/connector/me -H "X-Connector-Key: rc_..."
{"tenant": "Voorbeeld BV", "tenant_id": "a146...", "plan": "business"}
GET/api/connector/calls?limit=200connector-sleutel

De laatste gesprekken, nieuwste eerst. limit is standaard 200 en maximaal 500. Het transcript komt hier als tekst (JSON-string) mee.

{"tenant": "Voorbeeld BV", "count": 1, "calls": [{
  "id": "3f0b...", "caller_number": "+31612345678", "caller_name": "J. de Vries",
  "to_number": "+31851234567", "direction": "inbound",
  "started_at": "2026-11-20T08:41:02+00:00", "ended_at": "2026-11-20T08:43:15+00:00",
  "duration_seconds": 133, "summary": "Vraagt een offerte voor een warmtepomp.",
  "transcript": "[...]", "needs_followup": true, "followed_up": false, "user_note": ""
}]}
POST/api/connector/calls/{id}/followupconnector-sleutel

Body {"done": true} zet het gesprek op opgevolgd, {"done": false} draait dat terug.

POST/api/connector/calls/{id}/noteconnector-sleutel

Body {"note": "tekst"} zet de notitie. Een lege tekst wist hem.

Wilt u alleen de nieuwe gesprekken verwerken, onthoud dan het id of de started_at van het laatst verwerkte gesprek en sla bij de volgende ophaalronde alles over wat u al hebt. Ophalen eens per paar minuten is ruim voldoende. Voor directe verwerking is de webhook geschikter.

Webhook na elk gesprek

Ring AI stuurt na afloop van elk gesprek een POST met de gegevens naar uw eigen URL. Zet hem aan met PUT /api/bot/config:

curl -s -X PUT https://ringai.nl/api/bot/config \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://uwsysteem.nl/ringai", "webhook_api_key": "een-lange-geheime-tekst", "webhook_enabled": true}'

Wat uw URL ontvangt (met Authorization: Bearer <webhook_api_key> als u een sleutel hebt ingesteld):

POST https://uwsysteem.nl/ringai
Content-Type: application/json
Authorization: Bearer een-lange-geheime-tekst

{
  "event": "call_completed",
  "timestamp": "2026-11-20T08:43:15+00:00",
  "company_name": "Voorbeeld BV",
  "caller_number": "+31612345678",
  "caller_name": "J. de Vries",
  "duration_seconds": 133,
  "started_at": "2026-11-20T08:41:02+00:00",
  "ended_at": "2026-11-20T08:43:15+00:00",
  "transcript": [...],
  "summary": "Vraagt een offerte voor een warmtepomp, wil teruggebeld worden.",
  "needs_followup": true
}
  • Controleer de sleutel in de Authorization-header, zodat alleen Ring AI berichten kan afleveren.
  • Antwoord binnen 10 seconden met een 2xx-status. Ring AI probeert een mislukte aflevering niet opnieuw. Gemiste gesprekken haalt u daarna op via /api/calls/ of de connector.

Voorbeeld in Python

Met inlogtoken

Inloggen, de prompt aanpassen en de gesprekken van vandaag met een terugbelverzoek ophalen.

import requests
from datetime import datetime, timezone

API = "https://ringai.nl/api"

r = requests.post(f"{API}/auth/login",
                  json={"email": "beheer@uwbedrijf.nl", "password": "uw-wachtwoord"})
r.raise_for_status()
tokens = r.json()
h = {"Authorization": f"Bearer {tokens['access_token']}"}

# Prompt bijwerken (alleen dit veld verandert)
requests.put(f"{API}/bot/config", headers=h,
             json={"system_prompt": "Je bent Emma, de telefonist van Voorbeeld BV. ..."}).raise_for_status()

# Gesprekken van vandaag met een terugbelverzoek
vandaag = datetime.now(timezone.utc).date().isoformat()
calls = requests.get(f"{API}/calls/", headers=h, params={"limit": 100}).json()
for c in calls:
    if c["started_at"] and c["started_at"].startswith(vandaag) and c["needs_followup"]:
        print(c["caller_number"], c["summary"])

# Na 24 uur: nieuw token zonder wachtwoord
tokens = requests.post(f"{API}/auth/refresh",
                       json={"refresh_token": tokens["refresh_token"]}).json()

Met de beheersleutel

import requests
from datetime import datetime, timedelta, timezone

API = "https://ringai.nl/api/v1"
h = {"X-API-Key": "rk_..."}

# Gesprekken van het afgelopen uur
sinds = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
for c in requests.get(f"{API}/calls", headers=h, params={"since": sinds, "limit": 200}).json():
    print(c["started_at"], c["caller_number"], c["summary"])

# Openingstijden aanpassen
requests.put(f"{API}/config", headers=h, json={"office_hours": {
    "ma": ["08:30", "17:30"], "di": ["08:30", "17:30"], "wo": ["08:30", "17:30"],
    "do": ["08:30", "17:30"], "vr": ["08:30", "16:00"]}}).raise_for_status()

Vragen over de API of een koppeling: info@ringai.nl.

Veelgestelde vragen

Welk abonnement heb ik nodig?

De beheersleutel hoort bij Business. Met Pro kunt u al een webhook instellen en de gratis Odoo-koppeling gebruiken. De connector-sleutel voor het ophalen van gesprekken staat in elk dashboard. Business vraagt u aan via info@ringai.nl of 085 10 99 007.

Wat is het verschil tussen de beheersleutel en de connector-sleutel?

De connector-sleutel kan alleen gesprekken lezen, afvinken en van een notitie voorzien. De beheersleutel kan daarnaast de instellingen, de prompt en de openingstijden wijzigen. Gebruik voor een koppeling die alleen gesprekken nodig heeft bij voorkeur de connector-sleutel.

Ik ben mijn beheersleutel kwijt.

Ring AI bewaart de sleutel niet en kan hem dus ook niet terughalen. Maak in het dashboard een nieuwe; de oude werkt dan meteen niet meer. Pas daarna de sleutel aan in uw eigen systeem.

Wie kan een sleutel aanmaken?

Alleen het hoofdaccount. Een balie-inlog kan geen sleutel maken.

Wanneer gaat een wijziging in?

Een wijziging in de instellingen of de prompt geldt vanaf het eerstvolgende gesprek. Gesprekken die op dat moment lopen, gaan door met de oude instellingen.

Wat gebeurt er als ik van abonnement verander?

Stapt u over van Business naar een ander abonnement, dan geeft de beheersleutel direct 402. Gaat u weer naar Business, dan werkt dezelfde sleutel weer, tenzij u hem intussen hebt ingetrokken.

Hoe veilig is het?

Alle verkeer loopt over HTTPS. Ring AI slaat van de beheersleutel alleen een onomkeerbare afgeleide op. Het aanmaken en intrekken van sleutels en elke wijziging van de instellingen via de API worden vastgelegd, met tijdstip en de gewijzigde velden. Een sleutel geeft alleen toegang tot de gegevens van uw eigen bedrijf.

Waarom wordt mijn begroeting geweigerd?

Een begroeting via de beheer-API moet vermelden dat de beller met een AI spreekt, zoals de wet vraagt. Gebruik bijvoorbeeld "AI-assistent" of "digitale assistent" in de begroeting, of laat hem leeg voor de standaardbegroeting.

Ik loop vast.

Mail uw vraag met de route, de foutcode en het tijdstip naar info@ringai.nl, of bel 085 10 99 007. Stuur nooit uw sleutel mee.