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. |
| GET | /visitantes | Wer GERADE in allen Ihren Workspaces surft, mit der gelesenen Seite und ob bereits ein Gespräch läuft. Eine Momentaufnahme, kein Verlauf: nicht paginiert. Ein Workspace, der nicht antwortet, bricht die Liste nicht: Er steht in `casas_sin_responder`. |
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. |
| POST | /{id}/typing | „Schreibt…“ an den Kunden: Bei WhatsApp empfängt es Meta, im Web-Chat das Widget des Besuchers. Ohne Body; immer 204 (auf Kanälen, die es nicht unterstützen, wirkungslos) und 404, wenn das Gespräch nicht existiert. |
| POST | /{id}/messages/{messageId}/forward | Eine Nachricht an ein anderes Gespräch im selben Workspace weiterleiten, mit ihrem Anhang (kopiert, nicht geteilt). Body: `{to_conversation_id}`. Sie geht als Agentennachricht hinaus. |
| PUT | /{id}/messages/{messageId}/reaction | Mit einem Emoji auf eine WhatsApp-Nachricht reagieren; ersetzt die vorherige Reaktion des Unternehmens, `{emoji:null}` entfernt sie. Nur WhatsApp (Meta-API) und nur auf eine Nachricht, die Meta bereits bestätigt hat: sonst 400. |
| POST | /{id}/location | Einen Standort per WhatsApp senden: `{lat, lon, name?, address?, reply_to_message_id?}`. Er geht zuerst an Meta: Lehnt Meta ab, bleibt nichts im Verlauf. Nur WhatsApp. |
| POST | /{id}/contact-card | Eine Kontaktkarte per WhatsApp senden: `{name:{formatted_name}, phones?, emails?, reply_to_message_id?}`. Wie beim Standort: zuerst Meta, dann der Verlauf. Nur WhatsApp. |
| GET | /{id}/copiloto | Der Copilot des Agenten: was die KI für dieses Gespräch vorgeschlagen hat und was mit ihr besprochen wurde. Nur für das Team: Der Kunde sieht es nie. |
| POST | /{id}/copiloto | Der KI privat eine Frage zu diesem Gespräch stellen (`{content}`, bis 4.000 Zeichen). Sie antwortet DEM AGENTEN, nicht dem Kunden: Nichts geht über den Kanal hinaus. 503 `copilot_unavailable`, wenn sie nicht antworten kann. |
| POST | /{id}/copiloto/{sugerenciaId}/enviar | Einen Copilot-Vorschlag an den Kunden senden, unverändert oder bearbeitet (`{content}` optional). Er geht als Agentennachricht mit ihrem menschlichen Autor hinaus. Ein Vorschlag wird nur einmal gesendet: der zweite Versuch ergibt 409 `ya_enviada`. |
| POST | /{id}/resumen | Die Zusammenfassung des Gesprächs (offen oder geschlossen) anfordern und damit das Kontaktprofil aktualisieren. Kostet eine KIT-Aufgabe; erneut ohne neue Nachrichten angefordert, wird nicht erneut berechnet. Gibt es keine Zusammenfassung, steht der Grund in `motivo` und `codigo`. |
Kontakte /contacts
| GET | / | Kontakte auflisten. |
| GET | /{id} | Ein Kontakt mit seinen Identitäten und seinem Gesprächsverlauf. |
| GET | /{id}/historial | Worum es in den letzten Anfragen ging: die letzten Gespräche mit ihrer Zusammenfassung (`?limit=`, bis 25), die Summen und das Kontaktprofil. Das Öffnen erzeugt kein fehlendes Profil, weil das Geld kostet: Es wird gezielt mit `?generar=1` angefordert. |
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. |
Unternehmensdatenblatt /ficha
| GET | / | Einheiten auflisten (Filter ?estado= und ?tipo=) mit den Schwellen der Bänder. |
| POST | / | Einheit anlegen: Frage, Varianten, freigegebene Antwort, URL und Sprache. Ein Admin oder ein API-Schlüssel veröffentlicht sie; ein Agent schlägt sie vor. Die KI veröffentlicht nie. |
| GET | /{id} | Eine Einheit abrufen. |
| PATCH | /{id} | Eine Einheit bearbeiten; eine geänderte Frage oder Varianten berechnen das Embedding neu. |
| DELETE | /{id} | Eine Einheit löschen (Admin). |
| POST | /{id}/aprobar | Einen Vorschlag freigeben: er wird aktiv und speichert, wer ihn freigab (Admin). |
| POST | /{id}/rechazar | Einen Vorschlag ablehnen (Admin). |
| POST | /probar | Vorschau: was das Datenblatt auf eine Frage antworten würde, mit Bewertung und Band (optional mit Vorschlägen). |
| POST | /recalcular | Fehlende oder nicht mehr passende Embeddings neu berechnen (Admin). |
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. |
| PUT | /{channelId}/modo | Der Betreuungsmodus des Kanals: `{modo:"humano"|"hibrido"|"ia"}`. Er entscheidet, ob die KI mit dem Kunden spricht. Gilt für jeden Kanaltyp (WhatsApp, Telegram, E-Mail, Widget). Nur für Administratoren. |
| PUT | /{channelId}/auto | Die automatischen Nachrichten des Kanals: `{bienvenida, fueraDeHorario}` (je bis 1.000 Zeichen; `null` löscht). Die Nachricht außerhalb der Öffnungszeiten nutzt die Zeiten des Kanals. Nur für Administratoren. |
| PUT | /{channelId}/tarjeta | Die Kontaktkarte, die der Agent aus diesem Kanal senden kann: `{tarjetaContacto:{name:{formatted_name}, phones?, emails?}}`, mit mindestens einer Telefonnummer oder E-Mail; `null` entfernt sie. Nur WhatsApp. Nur für Administratoren. |
| PUT | /{channelId}/horario | Die Öffnungszeiten: `{officeHours:{tz, dias:{lun:[["09:00","17:00"]], …}, festivos:["MM-DD" oder "YYYY-MM-DD"]}}`; `null` entfernt sie (24/7). Unlesbares wird mit 400 und der Angabe des Fehlers abgelehnt. Liefert `abiertoAhora`, vom Server berechnet. Nur für Administratoren. |
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. |
| GET | /canned-responses/categories | Die bereits verwendeten Kategorien der Textbausteine (Freitext), für die Autovervollständigung. |
| POST | /canned-responses/{cannedId}/use | Vermerken, dass ein Textbaustein verwendet wurde (Zähler und letzte Verwendung). Immer 204, ob er existiert oder nicht: Nutzungstelemetrie, keine Aktion. |
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`. |
| GET | /workspaces/{workspaceId}/retencion/ensayo | Der Probelauf der Löschung: wie viele Gespräche und Anhänge (und Bytes) die Aufbewahrung entfernen würde, ohne etwas zu löschen. `?days=` fragt nach einer noch nicht gespeicherten Frist. Administrator und `analytics:read` erforderlich. Vollständige Route: `/v1/workspaces/{workspaceId}/retencion/ensayo`. |
Live-Besucher und Echtzeit /visitantes · /stream-ticket
| GET | /visitantes | Wer gerade auf den Websites dieses Workspace surft: Seite, Sprache, seit wann und ob der Chat schon offen ist oder ein Gespräch läuft. |
| POST | /visitantes/{visitorId}/invitar | Einen Besucher einladen, den Chat zu öffnen, mit optionaler `{mensaje}` (ohne sie die Begrüßung des Widgets in seiner Sprache). Erzeugt kein Gespräch und verbraucht keine KI: Das Gespräch entsteht, wenn der Besucher antwortet. 404 `no_esta`, wenn er weg ist; 409 `ya_conversa`, wenn er schon chattet. |
| POST | /stream-ticket | Ein Ticket, um den Stream-WebSocket mit `?ticket=` zu öffnen, ohne das Token in die URL zu setzen. Gilt 60 s und nur einmal. Funktioniert mit Sitzung oder API-Schlüssel. |
KIT-Fähigkeiten /conversations/{id}/kit
| GET | / | Die in diesem Gespräch gestarteten KIT-Aufgaben mit ihrem Status. Beim Auflisten werden die ausstehenden geprüft. |
| GET | /catalogo | Welche KIT-Fähigkeiten sich auf einen Anhang (`?attachment_id=`) oder den Verlauf anwenden lassen, mit Suche (`?q=`, `?lang=`). Nur Lesen: kostet nichts. |
| POST | / | Eine KIT-Fähigkeit (`{action, attachment_id?, params?}`) auf einen Anhang oder den Verlauf anwenden. Das Ergebnis kommt als INTERNE NOTIZ zurück, nie zum Kunden. Es kostet Geld aus dem KIT-Guthaben, dieselbe Anfrage wird nie doppelt berechnet. 202 mit der Aufgabe in der Warteschlange. |
Telefon (VOICE) /voice
| GET | /llamadas | Das Anrufprotokoll der Telefonanlage des Workspace (`?limite=` bis 200, `?antes_de=` zum Blättern). Scope `voice:read`; 404, wenn der Workspace keine Telefonanlage hat. |
| GET | /llamadas-en-curso | Die Anrufe, die gerade laufen. |
| GET | /aparcadas | Geparkte Anrufe, die darauf warten, übernommen zu werden. |
| GET | /grabaciones/{id}/audio | Der Ton einer Aufzeichnung, über die API ausgeliefert (kein öffentlicher Link) und nie zwischengespeichert. Die Telefonanlage protokolliert, wer sie angehört hat. |
| GET | /extensiones | Die Nebenstellen, die das Panel als Telefon nutzen kann (reservierte erscheinen nicht). |
| POST | /webphone-sesion | Den Browser als Telefon einer Nebenstelle registrieren (`{extension_id}`): liefert einen kurzlebigen SIP-Zugang, den die Telefonanlage bei jedem Abruf erneuert. Scope `voice:write`. Der Schlüssel der Telefonanlage verlässt nie den Server. |
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 — dafür gibt es `handoff.requested`. Es wird in dem Moment ausgelöst, in dem das Gespräch an einen Menschen geht (der Besucher hat danach gefragt, es gab Anzeichen einer Krise oder von Frust, oder die Antwort beruhte nicht auf dem Wissen), mit der Gesprächszusammenfassung, damit Sie jemanden benachrichtigen oder ein Ticket in einem anderen System erö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.