Overzicht
Basis-URL: https://ringai.nl/api. Alle verzoeken en antwoorden zijn JSON (UTF-8), alle tijden zijn ISO 8601 in UTC.
| Onderdeel | Wat u ermee doet | Toegang |
|---|---|---|
| Beheer-API | Instellingen, prompt en gesprekken beheren met een vaste sleutel, zonder wachtwoord. Bedoeld voor koppelingen. | Beheersleutel (Business) |
| Instellingen en prompt | Naam, stem, taal, prompt, begroeting, openingstijden, meldingsadres en webhook lezen en wijzigen | Inlogtoken (beheerder) |
| Gesprekslogs | Gesprekken zoeken, transcript ophalen, afvinken en notities zetten | Inlogtoken |
| Connector | Gesprekken ophalen en bijwerken met een vaste sleutel, zonder wachtwoord | Connector-sleutel |
| Webhook | Ring AI stuurt na elk gesprek de gegevens naar uw eigen URL | Uw 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.
- Log in op het dashboard met het hoofdaccount en ga naar het blok API-beheer.
- 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. - Stuur de sleutel mee in de header
X-API-Keybij elk verzoek naarhttps://ringai.nl/api/v1/....
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.
| Route | Wat | Zie |
|---|---|---|
GET /api/v1/me | Welk bedrijf en abonnement bij de sleutel horen | |
GET /api/v1/config | Instellingen en prompt lezen | velden |
PUT /api/v1/config | Instellingen en prompt wijzigen (alleen meegestuurde velden) | velden |
GET/PUT /api/v1/klantbevestiging | WhatsApp-bevestiging aan de beller | uitleg |
GET/PUT /api/v1/klantherkenning | Terugkerende bellers herkennen | uitleg |
GET /api/v1/calls | Gesprekken. Parameters limit (max 200), offset, q en since | velden |
GET /api/v1/calls/{id} | Eén gesprek met transcript | velden |
POST /api/v1/calls/{id}/annotate | Afvinken en/of notitie zetten | body |
POST /api/v1/calls/{id}/followup/done | Terugbelverzoek afgehandeld | |
GET /api/v1/stats | Totalen en openstaande terugbelverzoeken | voorbeeld |
GET /api/v1/stats/daily?days=30 | Per dag, maximaal 90 dagen | voorbeeld |
GET /api/v1/usage/monthly?months=6 | Gesprekken en minuten per maand, maximaal 24 maanden | voorbeeld |
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."}'
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>.
/api/auth/logingeencurl -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"
}
/api/auth/refreshgeencurl -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.
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.
Foutcodes
| Code | Betekenis |
|---|---|
401 | Ongeldig of verlopen token of sleutel. Bij een verlopen access-token: vernieuw via /api/auth/refresh. |
402 | De functie hoort niet bij uw abonnement (bijvoorbeeld de beheersleutel buiten Business). |
403 | De header Authorization ontbreekt, het account is gedeactiveerd, of deze actie is alleen voor de beheerder. |
404 | Gesprek of configuratie niet gevonden. |
409 | Kan nu niet, bijvoorbeeld omdat een voorwaarde nog niet is ingericht. Zie detail. |
422 | Het verzoek klopt niet (verkeerd veldtype of ontbrekend veld). |
429 | Te veel verzoeken. Wacht het aantal seconden uit de header Retry-After. |
Een fout komt altijd terug als {"detail": "uitleg"}.
Instellingen en prompt
/api/bot/configinlogtoken, beheerdercurl -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"
}
/api/bot/configinlogtoken, beheerderStuur 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?"}'
| Veld | Type | Uitleg |
|---|---|---|
bot_name | tekst | Naam waarmee de telefonist zich voorstelt. |
voice | tekst | Stem: marin, cedar, alloy, ash, ballad, coral, echo, sage, shimmer of verse. |
language | tekst | Taalcode van twee letters (nl, en, de, ...) of auto om de taal van de beller te volgen. |
company_info | tekst | Achtergrondinformatie over uw bedrijf: diensten, werkgebied, prijzen, veelgestelde vragen. |
system_prompt | tekst | De 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. |
greeting | tekst | Eerste zin bij opnemen. {begroeting} wordt vervangen door goedemorgen, goedemiddag of goedenavond. |
after_hours_message | tekst | Extra instructie buiten de openingstijden. |
office_hours | object | Openingstijden per dag, zie hieronder. |
notification_email | tekst | Adres dat na elk gesprek de samenvatting krijgt. |
webhook_url | tekst | Uw URL voor de webhook. |
webhook_api_key | tekst | Sleutel die Ring AI meestuurt naar uw webhook. |
webhook_enabled | true/false | Webhook 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"]
}}
"monday": {"open": ..., "close": ...}, worden niet herkend en gelden als gesloten.Klantbevestiging (WhatsApp naar de beller)
/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..."}
/api/bot/klantbevestiginginlogtoken, beheerdercurl -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)
/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}
/api/bot/klantherkenninginlogtoken, beheerderBody {"aan": true} of {"aan": false}. Geeft 402 als uw abonnement de functie niet heeft.
Gesprekslogs
/api/calls/inlogtokenLijst van gesprekken, nieuwste eerst.
| Parameter | Standaard | Uitleg |
|---|---|---|
limit | 50 | Aantal gesprekken per pagina. |
offset | 0 | Aantal over te slaan gesprekken, voor de volgende pagina. |
q | Zoekterm 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
}]
/api/calls/{id}inlogtokenEé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.
/api/calls/{id}/annotateinlogtokenVink 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"}'
/api/calls/{id}/followup/doneinlogtokenMarkeert het terugbelverzoek als afgehandeld (needs_followup wordt false). Geen body nodig.
Statistieken
/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}
/api/calls/stats/daily?days=30inlogtokenAantal gesprekken en seconden per dag, maximaal 90 dagen. Dagen zonder gesprekken staan erin met 0.
{"days": [{"date": "2026-11-19", "count": 12, "seconds": 1740}, ...]}
/api/calls/usage/monthly?months=6inlogtokenGesprekken 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.
/api/connector/meconnector-sleutelcurl -s https://ringai.nl/api/connector/me -H "X-Connector-Key: rc_..."
{"tenant": "Voorbeeld BV", "tenant_id": "a146...", "plan": "business"}
/api/connector/calls?limit=200connector-sleutelDe 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": ""
}]}
/api/connector/calls/{id}/followupconnector-sleutelBody {"done": true} zet het gesprek op opgevolgd, {"done": false} draait dat terug.
/api/connector/calls/{id}/noteconnector-sleutelBody {"note": "tekst"} zet de notitie. Een lege tekst wist hem.
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.