API

Vocaris in Ihrer Software.

Eine kleine, klare API mit Schlüssel je Firma. Lesen, was am Telefon passiert ist, Wissen ergänzen, Anrufe auslösen, planen und beenden, Zugänge verwalten. Dazu signierte Webhooks für Make, n8n und Zapier.

JSON, ISO 8601, Bearer-Schlüssel
120 Anfragen je Minute und Schlüssel
Jeder Schlüssel sieht nur die eigene Firma

Erste Schritte

Schlüssel holen, Anfrage senden.

Im Kundenbereich unter Schnittstellen → API-Schlüssel einen Schlüssel erstellen. Er beginnt mit vk_live_ und wird nur einmal angezeigt. Jede Anfrage trägt ihn im Authorization-Header. Basis-Adresse: https://ki-anruf.onrender.com. Antworten sind JSON, Zeiten in ISO 8601 (UTC), Fehler immer als {"error": "…"}. Höchstens 120 Anfragen je Minute und Schlüssel.

Beispiele als

curl https://ki-anruf.onrender.com/api/v1/me \
  -H "Authorization: Bearer vk_live_IHR_SCHLUESSEL"

Endpunkte

Lesen und schreiben.

Alle Endpunkte unter /api/v1/, jeweils mit dem vk_live_-Schlüssel. Beispiele lassen sich mit einem Klick kopieren und zwischen curl und JavaScript umschalten.

GET/api/v1/me

Ihre Firma und die zugeordneten Rufnummern.

curl https://ki-anruf.onrender.com/api/v1/me \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "tenant": { "id": "…", "name": "Praxis Dr. Sommer" }, "numbers": [ { "number": "+4989…", "department": "general" } ] }

GET/api/v1/calls

Anrufe, neueste zuerst. Parameter: limit (bis 200), since (ISO-Zeit), status (active | ended).

curl "https://ki-anruf.onrender.com/api/v1/calls?since=2026-09-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "calls": [ { "id": "…", "caller_number": "+49…", "status": "ended", "started_at": "…", "ended_at": "…", "summary": "…", "topic": "Termin", "sentiment": "positiv" } ] }

GET/api/v1/calls/:id

Ein Anruf mit vollständigem Transkript.

curl https://ki-anruf.onrender.com/api/v1/calls/ANRUF_ID \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "call": { … }, "transcript": [ { "role": "caller", "content": "…", "created_at": "…" }, { "role": "assistant", "content": "…", "created_at": "…" } ] }

GET/api/v1/messages

Aufgenommene Nachrichten und Rückrufwünsche. Parameter: limit, since.

curl "https://ki-anruf.onrender.com/api/v1/messages?limit=20" \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "messages": [ { "id": "…", "caller_name": "…", "callback_number": "+49…", "summary": "…", "category": "…", "urgency": "hoch", "created_at": "…" } ] }

GET/api/v1/gaps

Offene Fragen, die Vocaris nicht beantworten konnte. Parameter: status (open | answered), limit.

curl "https://ki-anruf.onrender.com/api/v1/gaps?status=open" \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "gaps": [ { "id": "…", "question": "…", "status": "open", "created_at": "…" } ] }

POST/api/v1/gaps/:id/answer

Offene Frage beantworten. Die Antwort wird zugleich als Wissenseintrag gespeichert, der Assistent kennt sie beim nächsten Anruf.

curl -X POST https://ki-anruf.onrender.com/api/v1/gaps/FRAGE_ID/answer \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"answer": "Samstags von 9 bis 13 Uhr geöffnet."}'

Antwort

{ "ok": true, "gap_id": "…", "knowledge_entry_created": true }

GET/api/v1/appointments

Termine ab jetzt, aufsteigend. Parameter: from, to (ISO-Zeit), limit (bis 500).

curl "https://ki-anruf.onrender.com/api/v1/appointments?to=2026-12-31T23:59:59Z" \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "appointments": [ { "id": "…", "starts_at": "…", "ends_at": "…", "customer_name": "…", "customer_phone": "+49…", "status": "booked", "source": "assistant" } ] }

GET/api/v1/tickets

Vorgänge des eingebauten Ticketsystems. Parameter: status (open | in_progress | done), assignee, overdue=1, since, limit.

curl "https://ki-anruf.onrender.com/api/v1/tickets?status=open&overdue=1" \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "tickets": [ { "id": "…", "number": 27, "title": "Rückruf: Erika Beispiel · Angebot", "status": "open", "priority": "high", "category": "Angebot", "assignee": "Anna", "due_at": "…", "tags": [], "caller_phone": "+49…", "created_at": "…" } ] }

GET/api/v1/tickets/:id

Ein Vorgang mit allen Notizen.

curl https://ki-anruf.onrender.com/api/v1/tickets/VORGANG_ID \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "ticket": { … }, "notes": [ { "body": "…", "author": "Team", "created_at": "…" } ] }

POST/api/v1/tickets

Vorgang anlegen, etwa aus einem Formular oder Ihrem eigenen System. Felder: title, optional body, priority, caller_name, caller_phone.

curl -X POST https://ki-anruf.onrender.com/api/v1/tickets \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"title": "Rückruf Herr Muster", "priority": "high", "caller_phone": "+491701234567"}'

Antwort

{ "ok": true, "id": "…", "number": 28 }

PATCH/api/v1/tickets/:id

Status, Priorität, Betreff, Zuständigkeit, Kategorie, Schlagwörter oder Frist ändern. status: open | in_progress | done. Jede Änderung erscheint im Verlauf des Vorgangs.

curl -X PATCH https://ki-anruf.onrender.com/api/v1/tickets/VORGANG_ID \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"status": "in_progress", "assignee": "Anna", "due_at": "2026-09-10T16:00:00Z"}'

Antwort

{ "ok": true, "ticket": { "id": "…", "status": "done", "closed_at": "…" } }

POST/api/v1/tickets/:id/notes

Notiz an einen Vorgang hängen.

curl -X POST https://ki-anruf.onrender.com/api/v1/tickets/VORGANG_ID/notes \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"body": "Kunde zurückgerufen, Termin am Freitag."}'

Antwort

{ "ok": true, "id": "…" }

GET/api/v1/blocked-numbers

Sperrliste: Anrufe dieser Nummern werden abgewiesen, bevor der Assistent abnimmt. Mit Trefferzähler.

curl https://ki-anruf.onrender.com/api/v1/blocked-numbers \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "blocked": [ { "id": "…", "phone": "+4930*", "reason": "Werbeanrufe", "hits": 3, "last_hit": "…" } ] }

POST/api/v1/blocked-numbers

Nummer sperren. phone: E.164, Bereich mit Stern am Ende (+4930*) oder anonym für unterdrückte Rufnummern. Optional reason.

curl -X POST https://ki-anruf.onrender.com/api/v1/blocked-numbers \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"phone": "+491701234567", "reason": "Dauerstörer"}'

Antwort

{ "ok": true, "id": "…", "phone": "+491701234567" }

DELETE/api/v1/blocked-numbers/:id

Sperre aufheben.

curl -X DELETE https://ki-anruf.onrender.com/api/v1/blocked-numbers/EINTRAG_ID \
  -H "Authorization: Bearer vk_live_…"

Antwort

{ "ok": true }

POST/api/v1/knowledge

Wissenseintrag anlegen, zum Beispiel aus Ihrem eigenen System heraus. Felder: title, content, optional category, department.

curl -X POST https://ki-anruf.onrender.com/api/v1/knowledge \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"title": "Parkplätze", "content": "Zwei Kundenparkplätze hinter dem Haus, Einfahrt Gartenstraße."}'

Antwort

{ "ok": true, "id": "…" }

POST/api/v1/calls

Ausgehenden Anruf durch den Assistenten auslösen, von Ihrer Rufnummer aus. Felder: to (+49…), optional auftrag (was der Assistent klären soll, ein bis drei Sätze) und name des Angerufenen. Mit Auftrag stellt sich der Assistent vor, nennt den Grund und erledigt den Auftrag; die Zusammenfassung holen Sie danach über GET /api/v1/calls.

curl -X POST https://ki-anruf.onrender.com/api/v1/calls \
  -H "Authorization: Bearer vk_live_…" -H "Content-Type: application/json" \
  -d '{"to": "+491701234567", "name": "Frau Beispiel", "auftrag": "Termin am Freitag um 10 Uhr bestätigen und fragen, ob die Versichertenkarte mitgebracht wird."}'

Antwort

{ "ok": true, "sid": "…" }

Kundenbereich

Anrufe steuern, Rückrufe planen, Zugänge verwalten.

Diese Endpunkte gehören zum Kundenbereich und werden mit dem Login-Token Ihrer Sitzung aufgerufen (Authorization: Bearer LOGIN_TOKEN), nicht mit dem vk_live_-Schlüssel. Sie sind gedacht für eigene Oberflächen, die den Kundenbereich ergänzen, etwa eine Anzeige am Empfang. Gleiche Basis-Adresse, gleiche Fehlerform; 401 heißt hier: nicht angemeldet, 403: keine Firma zugeordnet oder kein Recht.

POST/api/call/hangup

Ein laufendes Gespräch des Assistenten beenden. Feld: call_id (die Anruf-ID aus dem Kundenbereich oder aus GET /api/v1/calls). Aufgelegt wird in der Leitung, nicht nur in der Anzeige. Ist der Anruf nicht mehr aktiv, wird der Eintrag geschlossen und die Antwort trägt schon: true. Fehler: 400 ohne call_id, 401 ohne Token, 403 ohne zugeordnete Firma, 404 wenn der Anruf nicht zu Ihrer Firma gehört, 409 solange noch keine Leitung bekannt ist, 502 wenn der Netzbetreiber nicht auflegen konnte.

curl -X POST https://ki-anruf.onrender.com/api/call/hangup \
  -H "Authorization: Bearer LOGIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"call_id": "ANRUF_ID"}'

Antwort

{ "ok": true }

WS/media-mithoeren

WebSocket zum Mithören eines laufenden Gesprächs. Parameter in der Adresse: token (Login-Token) und call_id. Nach { "event": "start" } kommen beide Gesprächsspuren als Nachrichten { "event": "media", "spur": "…", "payload": "…" }, der Ton als μ-law 8 kHz, Base64-kodiert. Es geht nichts zurück in die Leitung, der Anrufer kann nicht gestört werden. Ohne Zugriff oder bei beendetem Gespräch antwortet der Server mit { "event": "fehler" } und schließt die Verbindung.

wss://ki-anruf.onrender.com/media-mithoeren?token=LOGIN_TOKEN&call_id=ANRUF_ID

GET/api/rueckrufe

Geplante Anrufe des Assistenten Ihrer Firma, mit Status (geplant, gestartet, abgesagt, fehlgeschlagen) und Fehlertext, falls ein Anruf nicht zustande kam. Fehler: 401 ohne Token, 403 ohne zugeordnete Firma.

curl https://ki-anruf.onrender.com/api/rueckrufe \
  -H "Authorization: Bearer LOGIN_TOKEN"

Antwort

{ "rueckrufe": [ { "id": "…", "phone": "+49…", "name": "Frau Berger", "auftrag": "Angebot nachfassen", "scheduled_at": "2026-09-19T12:00:00.000Z", "status": "geplant", "error": null, "created_at": "…", "started_at": null } ] }

POST/api/rueckrufe

Anruf durch den Assistenten zu einer festen Uhrzeit planen. Felder: phone (+49…), at (ISO-Zeit, nicht in der Vergangenheit), optional name des Angerufenen und auftrag (was zu klären ist, ein bis drei Sätze). Ein Prüflauf je Minute startet fällige Einträge über denselben Weg wie einen sofortigen Assistenten-Anruf. Fehler: 400 wenn Nummer oder Uhrzeit fehlen, die Nummer nicht dem Format +49… entspricht oder die Uhrzeit nicht lesbar ist oder in der Vergangenheit liegt; 401 ohne Token; 403 ohne zugeordnete Firma.

curl -X POST https://ki-anruf.onrender.com/api/rueckrufe \
  -H "Authorization: Bearer LOGIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"phone": "+491701234567", "name": "Frau Berger", "auftrag": "Fragen, ob das Angebot vom Montag passt.", "at": "2026-09-19T12:00:00Z"}'

Antwort

{ "ok": true, "message": "Anruf geplant.", "id": "…" }

DELETE/api/rueckrufe/:id

Geplanten Anruf absagen. Geht nur, solange er noch nicht gestartet ist. Fehler: 404 wenn der Eintrag nicht zu Ihrer Firma gehört oder schon gestartet wurde.

curl -X DELETE https://ki-anruf.onrender.com/api/rueckrufe/EINTRAG_ID \
  -H "Authorization: Bearer LOGIN_TOKEN"

Antwort

{ "ok": true }

POST/api/calendar/apple

Apple-Kalender per öffentlichem Kalender-Link verbinden (nur lesend: der Assistent sieht belegte Zeiten und bucht nur, was frei ist). Feld: url, der Link aus der Kalender-Freigabe (webcal:// oder https://). Der Kalender wird einmal geladen und geprüft; die Antwort nennt die Zahl der Termine der nächsten Wochen. Fehler: 400 wenn der Link fehlt, kein webcal- oder https-Link ist oder sich nicht laden lässt; 401 ohne Token; 403 ohne zugeordnete Firma.

curl -X POST https://ki-anruf.onrender.com/api/calendar/apple \
  -H "Authorization: Bearer LOGIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "webcal://p12-caldav.icloud.com/published/2/…"}'

Antwort

{ "ok": true, "message": "Kalender verbunden.", "termine": 14 }

GET/api/mitglieder

Zugänge Ihrer Firma und Ihre eigene Stufe (owner, admin oder member). Sehen darf jedes Mitglied; ändern dürfen nur Inhaber und Admins. Wer zu mehreren Firmen gehört, nennt die Firma mit ?tenant_id=…. Fehler: 401 ohne Token, 403 wenn Sie nicht zu dieser Firma gehören.

curl https://ki-anruf.onrender.com/api/mitglieder \
  -H "Authorization: Bearer LOGIN_TOKEN"

Antwort

{ "stufe": "owner", "mitglieder": [ { "userId": "…", "email": "empfang@praxis.de", "stufe": "member", "seit": "…" } ] }

POST/api/mitglieder

Zugang anlegen. Felder: email, optional password und stufe (admin oder member, Vorgabe member). Fehler: 400 wenn die E-Mail fehlt oder ungültig ist, 403 wenn Sie kein Inhaber oder Admin sind.

curl -X POST https://ki-anruf.onrender.com/api/mitglieder \
  -H "Authorization: Bearer LOGIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email": "empfang@praxis.de", "stufe": "member"}'

Antwort

{ "ok": true, "message": "…", "user_id": "…" }

PATCH/api/mitglieder/:userId

Stufe eines Zugangs ändern. Feld: stufe (admin oder member). Die eigene Stufe ändert ein anderer Admin, damit sich niemand selbst aussperrt. Fehler: 400 bei ungültiger Stufe oder eigenem Zugang, 403 ohne Verwaltungsrecht, 404 wenn der Zugang nicht zu Ihrer Firma gehört.

curl -X PATCH https://ki-anruf.onrender.com/api/mitglieder/USER_ID \
  -H "Authorization: Bearer LOGIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"stufe": "admin"}'

Antwort

{ "ok": true }

DELETE/api/mitglieder/:userId

Zugang aus der Firma entfernen. Den eigenen Zugang entfernt ein anderer Admin. Fehler: 400 beim eigenen Zugang, 403 ohne Verwaltungsrecht, 500 wenn das Entfernen fehlschlägt.

curl -X DELETE https://ki-anruf.onrender.com/api/mitglieder/USER_ID \
  -H "Authorization: Bearer LOGIN_TOKEN"

Antwort

{ "ok": true }

Webhooks

Ereignisse, die zu Ihnen kommen.

Unter Schnittstellen → Automatisierung tragen Sie eine Adresse und ein Geheimnis ein. Vocaris sendet dann pro Ereignis eine POST-Anfrage mit JSON. Fünf Ereignisse: message.captured, appointment.booked, gap.created, call.ended, ticket.created (neuer Vorgang mit Nummer, Priorität und Frist). call.ended bringt Name des Anrufers, Dauer, Thema, Zusammenfassung, Stimmung, Richtung und den Gesprächsverlauf gleich mit; ein Nachladen über GET /api/v1/calls/:id ist nicht mehr nötig. Derselbe Inhalt geht auf Wunsch als E-Mail, in Slack, Teams oder Telegram; dringende Nachrichten zusätzlich als SMS an eine Nummer Ihrer Wahl.

POST https://ihre-adresse.de/vocaris
Content-Type: application/json
X-Vocaris-Event: message.captured
X-Vocaris-Signature: sha256=3f1a…

{
  "event": "message.captured",
  "occurred_at": "2026-09-08T12:00:00.000Z",
  "data": {
    "caller_name": "Max Mustermann",
    "callback_number": "+49 170 1234567",
    "caller_number": "+49 170 1234567",
    "summary": "Rückruf gewünscht zu Angebot",
    "category": "Angebot",
    "urgency": "mittel"
  }
}

Beispiel call.ended

{
  "event": "call.ended",
  "occurred_at": "2026-09-18T09:41:07.000Z",
  "data": {
    "call_id": "…",
    "mode": "assistant",
    "caller_name": "Erika Beispiel",
    "caller_number": "+49 170 1234567",
    "direction": "in",
    "started_at": "2026-09-18T09:39:52.000Z",
    "duration_seconds": 75,
    "topic": "Termin",
    "summary": "Kontrolltermin am Freitag um 10 Uhr vereinbart, Bestätigung per SMS.",
    "sentiment": "positiv",
    "transcript": [
      { "role": "caller", "content": "Guten Tag, ich hätte gern einen Termin zur Kontrolle." },
      { "role": "assistant", "content": "Gern. Am Freitag habe ich um 10 Uhr oder um 16 Uhr etwas frei." },
      { "role": "caller", "content": "Zehn Uhr passt." }
    ]
  }
}

direction ist in für eingehende und out für Anrufe des Assistenten; role im Verlauf ist caller, assistant oder, bei Ihren eigenen Gesprächen, agent. Zusammenfassung und Stimmung fehlen, falls sie beim Versand noch nicht berechnet waren.

Signatur prüfen

Der Header X-Vocaris-Signature ist HMAC-SHA256 über den rohen Anfragetext mit Ihrem Geheimnis. Vergleichen Sie zeitkonstant.

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
const erwartet = "sha256=" + createHmac("sha256", GEHEIMNIS).update(rohText).digest("hex");
const gueltig = timingSafeEqual(Buffer.from(erwartet), Buffer.from(req.headers["x-vocaris-signature"] || ""));

Make, n8n, Zapier

In allen drei Werkzeugen genügt ein „Webhook“-Auslöser: Adresse kopieren, bei Vocaris eintragen, „Test senden“ klicken. Danach stehen die Felder aus data in Ihrem Szenario zur Verfügung. Für Abfragen (etwa Transkript nachladen) nutzen Sie einen HTTP-Schritt mit dem API-Schlüssel.

Fehler und Grenzen

Was Sie zurückbekommen.

401

Schlüssel fehlt, ist ungültig oder widerrufen.

400 / 404

Pflichtfeld fehlt oder falsch formatiert, beziehungsweise Objekt gehört nicht zu Ihrer Firma.

429

Mehr als 120 Anfragen je Minute mit einem Schlüssel. Kurz warten, dann erneut.

403 / 409 / 502

Nur im Kundenbereich: keine Firma zugeordnet oder kein Recht (403), Leitung noch nicht bekannt (409), Netzbetreiber konnte nicht auflegen (502).

Schlüssel lassen sich im Kundenbereich jederzeit widerrufen. Jeder Schlüssel sieht ausschließlich Daten der eigenen Firma. Fragen an unser Team.

Passt dazu: Was der Assistent am Telefon tut Sicherheit und Datenhaltung Preise und Grenzen

Kostenloser Testanruf

In wenigen Sekunden klingelt Ihr Telefon.

Rufnummer eintragen, Vocaris ruft Sie an, und Sie hören selbst, wie ein Gespräch klingt. Kostenlos, unverbindlich, ohne Anmeldung.

Demo-Termin vereinbaren 30 Minuten, wir richten Ihren Assistenten gemeinsam ein.

Schlüssel holen, Anfrage senden.

Lesen und schreiben.

Anrufe steuern, Rückrufe planen, Zugänge verwalten.

Ereignisse, die zu Ihnen kommen.

Signatur prüfen

Make, n8n, Zapier

Was Sie zurückbekommen.

401

400 / 404

429

403 / 409 / 502

In wenigen Sekunden klingelt Ihr Telefon.

Lassen Sie sich anrufen