API-Einführung
Die dalvon REST API gibt Ihnen programmatischen Zugriff auf Agenten, Anrufe, Kontakte, Kampagnen und alle weiteren Plattform-Ressourcen.
Was Sie erreichen werden
- API-Schlüssel erstellen und sicher verwahren
- Erste Anfragen gegen die API senden
- Paginierung und Fehlerbehandlung verstehen
- Wissen, wann Sie weiter zu API-Fehler beheben springen sollten
Voraussetzungen
- Ein Nutzerkonto unter app.dalvon.ai mit der Rolle Administrator oder Manager
Schritt 1: API-Schlüssel erstellen
- Öffnen Sie app.dalvon.ai und melden Sie sich an
- Klicken Sie oben rechts auf Ihren Namen und wählen Sie Einstellungen
- Wählen Sie den Tab API-Schlüssel
- Klicken Sie auf Neuer API-Schlüssel
- Geben Sie dem Schlüssel einen eindeutigen Namen (z.B.
CRM-Integration Produktion) - Klicken Sie auf Erstellen und kopieren Sie den Schlüssel sofort
Hinweis: Der Schlüssel wird nur einmalig angezeigt. Bewahren Sie ihn sicher auf — z.B. in einem Secret Manager. Kompromittierte Schlüssel können Sie jederzeit über dasselbe Menü löschen und durch neue ersetzen.
Organisationsscope des Schlüssels
Jeder API-Schlüssel ist an genau eine Organisation gebunden. Alle Lese- und Schreiboperationen über diesen Schlüssel beziehen sich ausschließlich auf Ressourcen dieser Organisation. Möchten Sie auf Ressourcen einer anderen Organisation zugreifen, benötigen Sie einen Schlüssel, der dort erstellt wurde. Dieser Punkt ist die häufigste Ursache für unerwartete 404-Antworten — mehr dazu unter API-Fehler beheben.
Schritt 2: Basis-URL und Authentifizierung
Alle API-Anfragen gehen an:
https://api.dalvon.ai
Senden Sie Ihren Schlüssel als Authorization-Header:
curl -X GET "https://api.dalvon.ai/agents/" \
-H "Authorization: Bearer IHR_API_KEY" \
-H "Content-Type: application/json"
Schritt 3: Erste Anfragen
Agenten auflisten
curl -X GET "https://api.dalvon.ai/agents/" \
-H "Authorization: Bearer IHR_API_KEY"
Beispielantwort:
{
"total": 2,
"skip": 0,
"limit": 30,
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Bot",
"language": "de",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
Outbound-Anruf starten
curl -X POST "https://api.dalvon.ai/calls/" \
-H "Authorization: Bearer IHR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"phone_number": "+491234567890"
}'
Paginierung
Listen-Endpunkte unterstützen Paginierung über zwei Query-Parameter:
| Parameter | Beschreibung | Default |
|---|---|---|
skip | Anzahl zu überspringender Einträge | 0 |
limit | Maximale Einträge pro Seite | 30 |
Beispiel — zweite Seite mit je 30 Einträgen:
curl "https://api.dalvon.ai/calls/?skip=30&limit=30" \
-H "Authorization: Bearer IHR_API_KEY"
Das Feld total in der Antwort gibt die Gesamtanzahl der Einträge an.
HTTP-Statuscodes
| Code | Bedeutung |
|---|---|
200 | Erfolg |
201 | Ressource erstellt |
400 | Ungültige Anfrage (Pflichtfeld fehlt o.ä.) |
401 | API-Schlüssel fehlt oder ungültig |
403 | Keine Berechtigung für diese Aktion |
404 | Ressource nicht gefunden — häufig ein Scope-Problem (s.u.) |
405 | HTTP-Methode nicht erlaubt |
422 | Validierungsfehler (Formatproblem in einem Feld) |
5xx | Serverseitiger Fehler — mit Backoff wiederholen |
Fehlerantworten enthalten immer ein detail-Feld:
{
"detail": "Agent nicht gefunden"
}
Bei 422 erhalten Sie zusätzlich eine Liste der betroffenen Felder:
{
"detail": [
{
"loc": ["body", "phone_number"],
"msg": "Ungültiges Nummernformat",
"type": "value_error"
}
]
}
Wenn etwas schiefgeht: Detaillierte Hilfe zu 404-, 401-, 5xx- und anderen Fehlern finden Sie unter API-Fehler beheben.
Stolpersteine, die nicht im Schema stehen
Die vollständigen Endpunkte, Felder und Typen sind in der API-Referenz dokumentiert. Die folgenden Punkte gehen über das Schema hinaus und tauchen erfahrungsgemäß erst in der Integration auf.
- PATCH = Merge-Semantik, nicht Replace. Nur explizit gesendete Felder werden geändert. Verschachtelte Objekte wie
conversationoderllmwerden ebenfalls minimal gemergt — nur die enthaltenen Unterfelder ändern sich. Für Agenten gilt zusätzlich: Sprachmodell, Spracherkennung, Sprachausgabe-Modell, Sprachmodus, Reaktionsgeschwindigkeit und Rauschunterdrückung stellen Sie ausschließlich über die Engine ein (engine_id, siehe Engines-API). Jeder Agent hat eine Engine; ohne Angabe erhält ein neuer Agent die Standard-Engine. - Kontakte:
first_nameundlast_namegetrennt. Es gibt kein kombiniertesname-Feld. Wernameschickt, erhält keine Fehlermeldung — beide Felder bleiben aber leer, was Weiterleitungen und Kontaktabgleich still bricht. - Kontakt-DELETE per Query-Parameter. Die Kontakt-ID geht als
?contact_id=in die URL, nicht als Pfad-Segment.DELETE /contacts/IDliefert HTTP 405. employee-Kontakte von Lösch-Automatisierungen ausnehmen. Kontakte vom Typemployeesind Weiterleitungsziele. Skripte, die namenlose oder veraltete Kontakte bereinigen, solltencontact_type=employeeexplizit ausschließen — sonst brechen Weiterleitungen stillschweigend weg.dynamic_variablesvs.custom_dataam Anruf.dynamic_variableswerden in den Agenten-Prompt injiziert und auf den Kontaktdatensatz zurückgeschrieben.custom_datawird nur am Anruf-Record gespeichert und taucht nicht im Prompt auf — nutzen Sie es, wenn Sie anrufspezifische Daten übergeben wollen, ohne den Kontakt dauerhaft zu verändern.PATCH /calls/categoriesersetzt die gesamte Liste. Das ist kein Merge-Update wie bei anderen PATCH-Endpunkten, sondern ein vollständiger Replace. Schicken Sie immer die komplette gewünschte Kategorienliste mit. Limits: maximal 35 Kategorien, je maximal 100 Zeichen.
Nächste Schritte
- API-Fehler beheben - 404, 5xx und Authentifizierungsprobleme systematisch lösen
- Webhooks - Anrufdaten nach Gesprächsende automatisch empfangen
- MCP mit Claude Desktop - Agenten direkt aus Claude Desktop verwalten