Entwicklerdokumentation

Voximo API

Vier getrennte API-Oberflächen, eine Plattform. Die öffentliche API bleibt auf Agenten, Anrufe und Nutzung beschränkt. Kalender, Generic Submit und Webhook-Management nutzen eigene Auth-Modelle und dürfen nicht mit Public-API-Keys vermischt werden.

Oberfläche	Zielgruppe	Authentifizierung	Zweck
Öffentliche API v1	Kunden und Automatisierungs-Tools	Bearer API-Key	Agenten, Anrufe und Nutzung. Bleibt in Automation Connector v1 unverändert.
Kalender-Integrations-API	Voice-Agent und Dashboard	X-Agent-Secret oder Session-Cookie	Verfügbarkeit, Buchung, Suche, Storno und Umbuchung.
Generic-Submit-API	Voice-Agent und Dashboard	X-Agent-Secret oder Session-Cookie	Strukturierte Voice-Action-Daten an aktive Partner-Integrationen senden.
Webhook-Management und Zustellung	Dashboard-Admins und externe Webhook-Ziele	Session-Cookie (Management), HMAC-Signatur (Zustellung)	Outbound Events an Custom Webhooks, n8n, Make und Zapier Catch Hook.

Interaktive Referenz öffnen OpenAPI-Spec herunterladen

Authentifizierung

Öffentliche API

Jede /api/v1/*-Route erwartet einen Bearer-API-Key im Authorization-Header. Keys werden unter Dashboard → Einstellungen → API Keys erstellt und scopen jede Antwort auf die Firma hinter diesem Key.

API-Zugriff ist aktuell nur nach Freischaltung verfügbar. Sprechen Sie uns an, wenn Sie die öffentliche API nutzen möchten. Public REST Hooks und eine Zapier Public App sind nicht Teil von Automation Connector v1.

Interne Integrationsrouten

Kalender- und Generic-Submit-Routen akzeptieren entweder einen X-Agent-Secret-Header (für Voice Agents) oder ein Session-Cookie (für das Dashboard). Diese Routen sind nicht über öffentliche API-Keys erreichbar.

curl -X GET https://voximo.io/api/v1/agents?limit=10 \
  -H "Authorization: Bearer vox_live_sk_..." \
  -H "Accept: application/json"

Endpunkte der öffentlichen API

Basis-URL: https://voximo.io/api/v1. Alle Antworten nutzen das Standardformat mit data, meta.request_id und bei Listen zusätzlich meta.pagination.

GET

/api/v1/agents

Listet alle Agenten des Workspaces.

GET

/api/v1/agents/:id

Lädt einen einzelnen Agenten per ID.

PATCH

/api/v1/agents/:id

Aktualisiert Begrüßung oder Aktivstatus.

GET

/api/v1/calls

Listet Anrufe mit Filtern wie agent_id, status, since und until.

GET

/api/v1/calls/:id

Lädt Anrufdetails inklusive Transkript.

GET

/api/v1/usage

Zeigt die aktuelle Nutzung im Abrechnungszeitraum.

Erfolgsformat

{
  "data": [{ "id": "...", "name": "Hauptzentrale", ... }],
  "meta": {
    "request_id": "550e8400-...",
    "pagination": { "total": 1, "limit": 10, "offset": 0, "has_more": false }
  }
}

Fehlerformat

{
  "error": { "code": "authentication_failed", "message": "Ungültiger oder widerrufener API-Key." },
  "meta": { "request_id": "550e8400-..." }
}

Kalender-Integrationen

Voximo behandelt Kalender-Provider als Cluster mit einem gemeinsamen Capability-Modell. Jeder Provider wird über einen dedizierten Adapter auf dieselben internen Primitive gemappt. Die Tabelle unten zeigt den aktuellen Voximo-Implementierungsstatus — nicht das, was der Provider theoretisch könnte.

Funktion	Cal.com	Google Calendar
validateCredentials	supported	supported
oauth	unsupported	supported
webhook	unsupported	supported
listEventTypes	supported	supported
checkAvailability	supported	supported
createBooking	supported	supported
getBooking	supported	unsupported
searchBookings	supported	unsupported
cancelBooking	supported	unsupported
rescheduleBooking	supported	unsupported

unterstützt teilweise nicht unterstützt

Kalender-Endpunkte

Alle Kalender-Routen liegen unter /api/integrations/calendar und nutzen X-Agent-Secretoder Session-Authentifizierung. Nicht unterstützte Funktionen liefern 409 unsupported_capability inklusive Provider- und Capability-Namen im Body zurück.

POST

/api/integrations/calendar/availability

Prüft freie Zeitslots für einen bestimmten Tag.

POST

/api/integrations/calendar/next-availability

Sucht über 14 Tage nach bis zu drei freien Optionen.

POST

/api/integrations/calendar/book

Erstellt eine Buchung über den aufgelösten Provider.

POST

/api/integrations/calendar/bookings/find

Findet Buchungen per lokalem Lookup mit Provider-Fallback.

POST

/api/integrations/calendar/bookings/cancel

Storniert per Provider-Booking-UID.

POST

/api/integrations/calendar/bookings/reschedule

Verschiebt eine Buchung, wenn der aktive Provider rescheduleBooking unterstützt.

Cal.com

Bearer-API-Key-Authentifizierung. Unterstützt vollständige Buchungsverwaltung (create, find, cancel, reschedule). Kein OAuth und keine Webhooks in Voximo. API-Version gepinnt auf 2024-08-13 (Event Types: 2024-06-14).

Google Calendar

OAuth mit Refresh Tokens. Unterstützt Availability, Event-Erstellung sowie Watch/Webhook-Renewal. Kein Booking-Management (get, search, cancel, reschedule) über Cluster-Flows.

Automatisierung und Webhooks

Automation Connector v1 nutzt bestehende Generic-Submit- und Webhook-Surfaces. n8n, Make und Zapier werden in v1 als Webhook-Ziele angebunden, nicht als native Provider und nicht als neue Public-API-Subscription-Schicht.

Quickstarts herunterladen (DE)Quickstarts herunterladen (EN)

Integrations-Submit (Generic)

POST /api/integrations/:slug/submit nimmt strukturierte Daten aus dem Voice Agent entgegen. Für Agent-Auth ist company_id erforderlich; Dashboard-Requests lösen die Firma aus der Session. Voice-Action-Erweiterungen bleiben in v1 auf diese interne Oberfläche begrenzt.

Outbound-Webhooks

Webhook-Management bleibt dashboard-authentifiziert. Zustellungen werden mit X-Voximo-Signaturesigniert und wiederholen keine Auth-Modelle aus der Public API. Aktiv sind call.started, call.completedund voice_action.submitted; Voice-Action-Zustellungen nutzen den bestehenden Webhook-Layer.

Retry und Idempotency

Generic-Submit-Fehler werden als integration_submissions persistiert, um sie später manuell erneut auszulösen. Webhook-Zustellungen werden protokolliert; fehlgeschlagene Zustellungen blockieren den Anruf-Lebenszyklus nicht. Empfänger sollen event, created_at und stabile IDs wie call_id oder Action-ID idempotent behandeln.

Konventionen

Benennung

Ressourcen: plural, kleingeschriebenes Englisch (/agents, /calls)
Felder: snake_case (created_at, company_id)
Fehlercodes: snake_case-Strings (authentication_failed)
Zeitstempel: ISO 8601 UTC
Identifier: UUID v4

Paginierung

Offset-basiert: ?limit=25&offset=0. Standard-Limit 25, maximal 100. Das Boolean-Feld has_more zeigt an, ob eine weitere Seite existiert.

HTTP-Methoden

GET — lesen
POST — erstellen
PATCH — teilweise aktualisieren
DELETE — entfernen

CORS

Access-Control-Allow-Origin: * für alle /api/v1/*-Routen. Authentifizierung läuft über den Bearer-Header, nicht über Cookies, daher ist kein Credentials-Modus nötig.

Ratenlimits

Öffentliche API: 60 Requests pro Minute pro API-Key. Kalender-Integrationsrouten verwenden eine IP-basierte Ratenbegrenzung. Bei Drosselung enthält die Antwort:

Header	Beschreibung
X-RateLimit-Limit	Maximale Requests im aktuellen Fenster.
X-RateLimit-Remaining	Verbleibende Requests bis zur Drosselung.
X-RateLimit-Reset	Unix-Epoch-Sekunden bis zum Reset des Fensters.
Retry-After	Sekunden bis zum nächsten Wiederholungsversuch (nur bei 429).

Fehlerreferenz

Jede Fehlerantwort nutzt dasselbe Format: error.code, error.message und meta.request_id. Kalender-Routen ergänzen bei 409 zusätzlich capability und provider.

HTTP	Code	Wann
400	validation_error	Die Zod-Validierung für Query oder Body ist fehlgeschlagen.
401	authentication_failed	API-Key fehlt, ist ungültig formatiert oder widerrufen.
403	insufficient_permissions	Der API-Key ist gültig, aber der Plan enthält keinen API-Zugang.
404	not_found	Die Ressource existiert nicht im authentifizierten Workspace.
409	unsupported_capability	Der Kalender-Provider unterstützt diese Operation in Voximo nicht.
429	rate_limit_exceeded	Erneut versuchen, sobald der Retry-After-Wert abgelaufen ist.
500	internal_error	Unerwarteter Serverfehler. Bei idempotenten Requests sicher wiederholbar.
502	provider_error	Der Upstream-Provider-Request ist fehlgeschlagen.