Bauen Sie auf derselben API, auf der wir bauen
Alles, was die Plattform tut — Gespräche, Kontakte, KI-Agenten, Wissen, Analysen — läuft über diese REST-API. Es gibt keine bessere private API dahinter: Dies ist die einzige. Basis-URL: `https://api.inteligenciaviva.com/v1`.
Quickstart: Ihre erste Anfrage in 60 Sekunden
Erstellen Sie einen API-Schlüssel in Ihrem Workspace, exportieren Sie ihn und listen Sie Ihre Gespräche auf. Schlüssel gelten pro Workspace und können nur-lesend oder lesend-schreibend sein.
curl https://api.inteligenciaviva.com/v1/workspaces/WORKSPACE_ID/conversations \
-H "Authorization: Bearer sk_live_..."Jede Antwort ist JSON. Sammlungs-Endpunkte liefern `data`-Arrays; Fehler liefern ein `error`-Objekt mit `code` und `message` und dem passenden HTTP-Status.
Die kostenlose API — ohne Konto, ohne Schlüssel
Auch die kostenlose Ebene spricht API. `POST /v1/free/widget-snippet` nimmt exakt dieselbe Konfiguration entgegen, die der visuelle Generator auf der Seite Kostenlos baut, und liefert das fertige HTML-Snippet zum Einfügen — ohne Authentifizierung, ohne Registrierung. Nutzen Sie sie, um Widgets für Kundenseiten im Stapel zu erzeugen, Embeds aus der CI neu zu generieren, wenn sich Zeitpläne ändern, oder einfach, um die API anzufassen, bevor Sie einen Cent zahlen.
curl -X POST https://api.inteligenciaviva.com/v1/free/widget-snippet \
-H "Content-Type: application/json" \
-d @widget-config.json
# → { "snippet": "<link rel=\"stylesheet\" ..." }Authentifizierung
Jede Anfrage trägt einen API-Schlüssel in der `Authorization`-Kopfzeile als Bearer-Token. Schlüssel werden über die API selbst oder im Dashboard erstellt und widerrufen, pro Workspace — ein widerrufener Schlüssel verliert seinen Zugriff sofort.
Die Sitzungs-Endpunkte auf Kontoebene (Registrierung, Login, Google-Anmeldung, Ticket-Tausch, Profil und Kontolöschung unter `/v1/auth`) treiben unsere eigenen Apps an; für Server-zu-Server-Integrationen bevorzugen Sie immer Workspace-API-Schlüssel gegenüber Benutzersitzungen.
Authorization: Bearer sk_live_...Ressourcen-Referenz
Alle Routen unten hängen an `https://api.inteligenciaviva.com/v1/workspaces/{workspaceId}`, sofern nicht anders vermerkt. Dies ist die real gemountete Oberfläche des aktuellen Backends — nichts Aspirationales.
Bereichsübergreifender Posteingang /inbox
| GET | /conversations | Alle Unterhaltungen ALLER Bereiche, die diese Anmeldedaten betreuen, in einer nach Aktivität sortierten Liste. |
| GET | /conversations/{id} | Eine Unterhaltung, über alle Bereiche hinweg gesucht. Gibt ihre workspace_id zurück. |
| GET | /workspaces | Die Bereiche, die diese Anmeldedaten betreuen können, mit ihrer Rolle in jedem. |
Gespräche /conversations
| GET | / | Gespräche auflisten, filterbar nach Zustand. |
| GET | /{id} | Ein Gespräch mit Zustand, Kanal, Kontakt und Zuweisung. |
| GET | /{id}/messages | Nachrichtenverlauf (Besucher, menschlicher Agent, KI, System). |
| POST | /{id}/messages | Als Agent eine Nachricht in das Gespräch senden. |
| POST | /{id}/assign | Das Gespräch einem menschlichen Agenten oder einer Abteilung zuweisen. |
| POST | /{id}/resolve | Das Gespräch schließen. Hat die KI es allein geschlossen, zählt es als abrechenbare Lösung. |
| POST | / | Eine Unterhaltung außerhalb des Widgets öffnen (z. B. um einen bestehenden Verlauf zu migrieren). |
| GET | /{id}/ai-turns | «Woher hat sie das?» — das Protokoll jedes KI-Zugs: worauf sie sich stützte, welches Modell, wie lange und warum übergeben wurde. |
| GET | /{id}/portal-case | Status des Falls, den diese Unterhaltung im Support-Board des Portals eröffnet hat, samt Antworten. Wird live abgefragt: der Status ändert sich im anderen Board. |
| POST | /{id}/read | Unterhaltung als vom Team gelesen markieren (Zähler für Ungelesene). |
| POST | /{id}/reopen | Eine geschlossene Unterhaltung wieder öffnen, mit erhaltenem Verlauf. Ohne dies war ein versehentliches Schließen endgültig. |
| POST | /{id}/archive | Archivieren oder zurückholen. Sie verlässt den Posteingang, ohne geschlossen zu werden oder etwas zu verlieren; Body: {valor:true|false}. |
| POST | /{id}/pin | Oben anheften oder lösen. Angeheftete stehen auf der ersten Seite des Posteingangs ganz oben. Body: {valor:true|false}. |
| POST | /{id}/mute | Hinweise für N Stunden stummschalten, oder {horas:null}, um sie wieder zu hören. |
| POST | /{id}/unread | Als ungelesen lassen: die Lesemarke rückt hinter die letzte Nachricht der Kundin oder des Kunden zurück. |
Kontakte /contacts
| GET | / | Kontakte auflisten. |
| GET | /{id} | Ein Kontakt mit seinen Identitäten und seinem Gesprächsverlauf. |
KI-Agenten /ai-agents
| GET | / | Die KI-Agenten des Workspace auflisten. |
| POST | / | Einen KI-Agenten erstellen: Anweisungen, Abteilung, Konfidenzschwelle. |
| PATCH | /{id} | Anweisungen, Schwelle oder Abteilung aktualisieren. |
| GET | /{id}/knowledge-sources | Wissensquellen, die mit diesem Agenten verknüpft sind. |
| POST | /{id}/knowledge-sources | Eine Wissensquelle mit diesem Agenten verknüpfen. |
| GET | /{aiAgentId} | Ein KI-Agent: Anweisungen, Konfidenzschwelle, Werkzeuge und Abteilung. |
Wissen (RAG) /knowledge-sources
| POST | /document | Ein Dokument als fundiertes Wissen indexieren. |
| POST | /url | Eine URL indexieren. |
| GET | /{id} | Status und Metadaten der Quelle. |
| DELETE | /{id} | Eine Quelle und ihre Vektoren entfernen. |
| POST | /{id}/reindex | Eine URL-Quelle neu einlesen, ohne sie zu löschen: Schlägt der Abruf fehl, bleibt alles unverändert. |
| GET | / | Wissensquellen mit ihrem Indexierungsstatus auflisten. |
Kanäle /channels
| GET | / | Kanäle auflisten. Heute live: Web-Chat und API; weitere kommen hinzu, sobald sie erscheinen. |
| PUT | /{id}/credentials | Die Zugangsdaten eines Kanals setzen. |
| PUT | /{id}/status | Einen Kanal aktivieren oder deaktivieren. |
| POST | / | Einen Kanal anlegen. |
| GET | /{channelId} | Ein Kanal mit Typ, Status und Einstellungen. |
| GET | /{channelId}/snippet | Die eine Zeile, die der Kunde in seine Website einfügt. Alles andere wird hier konfiguriert. |
| GET | /{channelId}/config | Die Chat-Konfiguration: das Veröffentlichte (`config`) und das, was dieser Kanal überschreibt (`settings`). Nicht verwechseln. |
| PUT | /{channelId}/config | Konfiguration speichern. Speichern und Veröffentlichen sind ein Schritt: schlägt das CDN fehl, schlägt das PUT fehl. |
| POST | /{channelId}/config/publish | Die Konfiguration erneut ins CDN veröffentlichen, ohne sie zu ändern. |
| POST | /{channelId}/avatar | Das Gesicht des Assistenten hochladen (≤512 KB). Liegt in R2, ausgeliefert vom CDN. |
| POST | /republicar-todos | Alle Kanäle des Workspace neu veröffentlichen. Der Cron tut das bei Änderung des Textpakets; dies spart das Warten. |
Menschliche Agenten & Abteilungen /agents · /departments
| GET | /agents | Menschliche Agenten im Workspace auflisten. |
| POST | /agents/{userId}/departments | Einen Agenten in eine Abteilung aufnehmen. |
| GET | /departments | Abteilungen auflisten. |
| PUT | /departments/{id}/routing-rules | Routing-Regeln für eingehende Gespräche festlegen. |
| POST | /agents | Eine Person in den Workspace einladen, mit Rolle und Abteilungen. |
| GET | /agents/{userId} | Ein Teammitglied. |
| POST | /departments | Eine Abteilung mit ihren Routing-Regeln anlegen. |
| GET | /departments/{id} | Eine Abteilung. |
Webhooks, Schlüssel, Abrechnung, Analysen /webhooks · /api-keys · /billing · /analytics
| POST | /webhooks | Einen Endpunkt registrieren; sein Signatur-Secret erhalten Sie genau einmal. |
| DELETE | /webhooks/{id} | Einen Endpunkt entfernen. |
| POST | /api-keys | Einen Schlüssel erstellen (nur-lesend oder lesend-schreibend). |
| DELETE | /api-keys/{id} | Einen Schlüssel sofort widerrufen. |
| GET | /billing/subscription | Plan, enthaltene KI-Lösungen und Nutzung im laufenden Zeitraum. |
| GET | /analytics | Aggregierte Metriken des Workspace. |
| GET | /webhooks | Webhook-Endpunkte auflisten. |
| GET | /webhooks/{id}/deliveries | Zustellverlauf eines Webhooks, mit Wiederholungen. Das zeigt, ob der Fehler bei Ihnen oder bei uns liegt. |
| GET | /api-keys | Schlüssel auflisten. Das Geheimnis wird nie zurückgegeben, nur sein Präfix. |
Agenten-Werkzeuge /conversations/{id} · /canned-responses · /tags · /presence
| GET | /conversations/{id}/notes | Interne Notizen zur Unterhaltung. Der Besucher sieht sie nie. |
| POST | /conversations/{id}/notes | Interne Notiz hinzufügen. |
| DELETE | /conversations/{id}/notes/{noteId} | Interne Notiz löschen. |
| GET | /canned-responses | Gespeicherte Antworten des Workspace, mit ihrem Kürzel. |
| POST | /canned-responses | Gespeicherte Antwort anlegen. |
| PATCH | /canned-responses/{cannedId} | Gespeicherte Antwort bearbeiten. |
| DELETE | /canned-responses/{cannedId} | Gespeicherte Antwort löschen. |
| POST | /presence | Präsenz-Heartbeat: meldet, dass eine Person verfügbar ist. Nur mit Sitzung — ein API-Schlüssel, der schlägt, ist niemand vor dem Bildschirm und wird mit 400 abgelehnt. |
| GET | /presence | Ist gerade jemand online? Das entscheidet, ob eine Übergabe wartet oder umgeleitet wird. |
| GET | /ai-usage | Inferenz-Verbrauch des Workspace pro Tag und die teuersten Unterhaltungen. |
| GET | /tags | Tags des Workspace. |
| GET | /conversations/{id}/tags | Tags einer Unterhaltung. |
| POST | /conversations/{id}/tags | Unterhaltung taggen. Legt den Tag an, falls er nicht existierte. |
| DELETE | /conversations/{id}/tags/{tagId} | Tag von der Unterhaltung entfernen. |
| POST | /conversations/{id}/transfer | Unterhaltung an eine Abteilung übergeben. Hat Vorrang vor den Routing-Regeln: eine manuelle Übergabe wird nicht automatisch rückgängig gemacht. |
| POST | /contacts/{contactId}/block | Kontakt sperren. Er erhält ein 403 ohne Details: einem Missbraucher erklärt man nicht, wie er erkannt wurde. |
Anhänge, Geräte und Workspaces /conversations/{id}/attachments · /devices · /workspaces
| POST | /conversations/{id}/attachments | Einen Anhang als Agent hochladen. Strikte Allowlist und 10 MB: nichts, was ein Browser ausführen kann. |
| GET | /conversations/{id}/attachments | Anhänge einer Unterhaltung. |
| GET | /attachments/{attachmentId} | Einen Anhang herunterladen. Mit strengen Headern und `nosniff`; nur Bilder und Audio werden inline dargestellt. |
| POST | /devices/register | Push-Token eines Geräts registrieren, um eine Person bei einer KI-Übergabe zu benachrichtigen. Außerhalb des Workspace-Präfixes: `/v1/devices/register`. |
| POST | /workspaces | Einen Workspace anlegen. Außerhalb des Präfixes: `/v1/workspaces`. |
Echte Beispiele
Eine Agenten-Nachricht senden (curl)
curl -X POST \
https://api.inteligenciaviva.com/v1/workspaces/$WS/conversations/$CONV/messages \
-H "Authorization: Bearer $IV_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "Hi! I checked your order — it ships tomorrow."}'Gespräche auflisten (JavaScript)
const res = await fetch(
`https://api.inteligenciaviva.com/v1/workspaces/${WS}/conversations`,
{ headers: { Authorization: `Bearer ${process.env.IV_KEY}` } }
);
const { data } = await res.json();Eine Webhook-Signatur verifizieren (Node)
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, rawBody, header, toleranceSec = 300) {
const { t, v1 } = Object.fromEntries(
header.split(",").map((p) => p.split("="))
);
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
const expected = createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}Webhooks
Registrieren Sie einen HTTPS-Endpunkt, und wir senden jedes Ereignis per POST dorthin, signiert. Die Kopfzeile ist `iv-signature: t=<unix>,v1=<hex>`, wobei `v1` der HMAC-SHA256 von `<timestamp>.<roher Body>` mit dem Secret Ihres Endpunkts ist — weisen Sie alles ab, was älter als 5 Minuten ist (Replay-Schutz). Fehlgeschlagene Zustellungen werden automatisch mit frischer Signatur wiederholt, bis zu 5 Versuche.
| conversation.created | Ein neues Gespräch hat auf irgendeinem Kanal begonnen. |
| message.created | Eine Nachricht ist eingetroffen (Besucher, Mensch, KI oder System). |
| handoff.requested | Die KI hat entschieden, dass sie einen Menschen braucht — der exakte Moment, mit der Zusammenfassung. |
| conversation.resolved | Ein Gespräch wurde geschlossen; sagt Ihnen, ob die KI es allein geschlossen hat. |
Jede Zustellung und ihr Status werden aufgezeichnet — ein Webhook, dem Sie nicht vertrauen können, ist schlimmer als keiner.
Echtzeit-Streaming
Für Live-Oberflächen öffnen Sie einen WebSocket gegen den Workspace-Stream und erhalten Gesprächsereignisse, während sie geschehen — derselbe Kanal, den unsere eigenen Agenten-Apps nutzen.
wss://api.inteligenciaviva.com/v1/workspaces/{workspaceId}/streamFehler und Limits
Fehler sind konventionelles HTTP: `400` fehlerhafte Anfrage, `401` fehlender oder ungültiger Schlüssel, `403` Schlüssel ohne Berechtigung, `404` Ressource nicht in diesem Workspace, `429` Ratenlimit erreicht (warten und mit Jitter erneut versuchen), `5xx` unsere Schuld — wiederholen Sie idempotente Anfragen. Der Body trägt immer einen `error.code` und eine menschenlesbare `error.message`. Ratenlimits gelten pro Schlüssel und sind großzügig für echte Integrationen.
Häufig gestellte Fragen
Ist diese Dokumentation aspirational oder die reale Oberfläche?
Real. Sie ist gegen die gemounteten Routen des aktuellen Backends geschrieben. Wenn hier etwas „kommt bald“ sagt, existiert es noch nicht — wir dokumentieren keinen Dunst.
Brauche ich einen kostenpflichtigen Plan, um die API zu nutzen?
Ja — die API ist Teil der kostenpflichtigen Plattform (Pro enthält sie). Das kostenlose Widget und das WordPress-Plugin sind client-seitig und brauchen gar keine API.
Was ist der Unterschied zwischen nur-lesenden und lesend-schreibenden Schlüsseln?
Nur-lesende Schlüssel können auflisten und abfragen, aber nie verändern — ideal für Dashboards und BI. Lesend-schreibende Schlüssel können Nachrichten, Kontakte, KI-Agenten und Konfiguration erstellen.
Wie erfahre ich von neuen Nachrichten — Polling oder Webhooks?
Webhooks (`message.created`) für Server, der WebSocket-Stream für Live-Oberflächen. Polling funktioniert, aber Sie stoßen an die Ratenlimits, bevor Sie Echtzeit erreichen.
Wie verifiziere ich genau, dass ein Webhook von Ihnen kam?
Berechnen Sie den HMAC-SHA256 von `<t>.<roher Body>` mit Ihrem Endpunkt-Secret neu und vergleichen Sie ihn in konstanter Zeit mit dem `v1`-Wert der `iv-signature`-Kopfzeile; weisen Sie ab, wenn `t` älter als 300 Sekunden ist. Funktionierender Code steht auf dieser Seite.
Was passiert, wenn mein Webhook-Endpunkt ausgefallen ist?
Wir zeichnen die fehlgeschlagene Zustellung auf und wiederholen automatisch mit frischem Timestamp und frischer Signatur, bis zu 5 Versuche. Wurde der Endpunkt inzwischen gelöscht oder deaktiviert, stoppen die Wiederholungen sauber.
Kann die KI an mein eigenes Eskalationssystem übergeben?
Ja — genau dafür gibt es `handoff.requested`. Es feuert in dem Moment, in dem die Konfidenz der KI unter die Schwelle des Workspace fällt, mit der Gesprächszusammenfassung — damit Sie eine Person alarmieren oder anderswo ein Ticket öffnen können.
Welche Kanäle kann ich heute über die API steuern?
Der Web-Chat ist von Ende zu Ende live, und alles in dieser Referenz funktioniert heute. Telegram und weitere Messaging-Kanäle verbinden sich mit demselben Gesprächsmodell, sobald sie erscheinen — Ihre Integration ändert sich nicht.
Gibt es ein SDK?
Ein Flutter-SDK treibt unsere eigene Agenten-App an und ist die Basis des White-Label-SDK für Enterprise. Für Server ist die REST-Oberfläche bewusst schlicht — jeder HTTP-Client funktioniert ohne Wrapper.
Wo melde ich einen API-Bug oder eine Lücke in dieser Dokumentation?
Schreiben Sie an l@inteligenciaviva.com. Dokumentation, die lügt, ist auch ein Bug — wir behandeln sie mit derselben Schwere.