API-Dokumentation

Die NovaVoca API ermöglicht es dir, programmatisch mit der Plattform zu interagieren — z.B. ausgehende Anrufe starten, Assistenten konfigurieren oder Gesprächsdaten abrufen.

Authentifizierung

Alle API-Requests erfordern einen API-Key im Header:

Authorization: Bearer nv_sk_xxxxxxxxxxxxxxxxxxxxx

Deinen API-Key findest du unter Einstellungen → API in der NovaVoca-Plattform.

⚠️

Teile deinen API-Key niemals öffentlich. Behandle ihn wie ein Passwort. Bei Verdacht auf Kompromittierung, generiere einen neuen Key.

Base URL

https://api.novavoca.com/v1

Outbound Call starten

Starte einen ausgehenden Anruf über die API.

Request

POST /v1/calls/outbound
Content-Type: application/json
Authorization: Bearer nv_sk_xxxxxxxxxxxxxxxxxxxxx

Body

{
  "assistant_id": "asst_xxxxxxxxxxxx",
  "to": "+4917012345678",
  "from": "+4930123456789",
  "metadata": {
    "customer_id": "cust_123",
    "campaign": "follow-up"
  }
}

Parameter

assistant_idstringrequired

Die ID des Assistenten, der den Anruf führen soll.

tostringrequired

Die Zielnummer im E.164-Format (z.B. +4917012345678).

fromstringrequired

Die Absendernummer. Muss eine deiner NovaVoca-Nummern sein.

metadataobject

Optionale Key-Value-Paare, die dem Anruf zugeordnet werden. Werden in Webhook-Events mitgeliefert.

Response

{
  "id": "call_xxxxxxxxxxxx",
  "status": "initiated",
  "assistant_id": "asst_xxxxxxxxxxxx",
  "to": "+4917012345678",
  "from": "+4930123456789",
  "created_at": "2026-04-16T10:30:00Z"
}

Fehler

Status Code	Beschreibung
`400`	Ungültige Parameter (z.B. fehlende Pflichtfelder)
`401`	Ungültiger API-Key
`402`	Nicht genug Guthaben
`404`	Assistent oder Nummer nicht gefunden
`429`	Rate Limit erreicht (max. 10 Calls/Sekunde)

Webhook-Events

NovaVoca sendet Webhook-Events an die URL, die du unter Einstellungen → Webhooks konfiguriert hast.

call.completed

Wird gesendet, wenn ein Anruf beendet wurde.

{
  "event": "call.completed",
  "call_id": "call_xxxxxxxxxxxx",
  "assistant_id": "asst_xxxxxxxxxxxx",
  "duration_seconds": 145,
  "caller_number": "+4917012345678",
  "callee_number": "+4930123456789",
  "direction": "inbound",
  "extracted_variables": {
    "name": "Max Mustermann",
    "email": "max@example.com",
    "reason": "Terminvereinbarung"
  },
  "summary": "Der Anrufer wollte einen Termin für nächste Woche vereinbaren...",
  "transcript": [
    { "role": "assistant", "content": "Guten Tag, Praxis Dr. Müller..." },
    { "role": "user", "content": "Hallo, ich würde gerne einen Termin..." }
  ],
  "metadata": {},
  "created_at": "2026-04-16T10:30:00Z"
}

call.started

Wird gesendet, wenn ein Anruf beginnt.

{
  "event": "call.started",
  "call_id": "call_xxxxxxxxxxxx",
  "assistant_id": "asst_xxxxxxxxxxxx",
  "caller_number": "+4917012345678",
  "callee_number": "+4930123456789",
  "direction": "inbound",
  "created_at": "2026-04-16T10:30:00Z"
}

Rate Limits

Endpunkt	Limit
Outbound Calls	10 Requests/Sekunde
Alle anderen	100 Requests/Sekunde

Die API befindet sich in aktiver Entwicklung. Weitere Endpunkte (Assistenten-Verwaltung, Gesprächslogs, Analytics) werden schrittweise hinzugefügt.

Rufweiterleitung einrichten FAQ