Für EntwicklerFor developers
Sie tauschen einen Agent-Key gegen eine kurzlebige Realtime-Session und verbinden sich damit. Das ist die ganze Schnittstelle. Alles Weitere — Wissen, Stimme, Verhalten des Agenten — konfigurieren Sie in der Konsole, nicht im Code.
You exchange an agent key for a short-lived realtime session and connect to it. That is the whole interface. Everything else — the agent's knowledge, voice and behaviour — you configure in the console, not in code.
Die Reihenfolge ist bindend: ohne Key keine Session, ohne Session keine Verbindung.
The order is binding: no key, no session — no session, no connection.
Den Key finden Sie in der Konsole unter Ihrem Agenten. Er beginnt mit
wk_ und ist veröffentlichbar — er ist dafür
gebaut, im Browser-Code zu stehen. Beschränken Sie ihn dort auf Ihre Domains,
dann ist er auch nur von dort nutzbar.
You find the key in the console, under your agent. It starts with
wk_ and is publishable — it is built to sit
in browser code. Restrict it to your own domains there, and it only works from
those.
Ein POST gegen /v1/session. Kein Auth-Header —
der Key reist im Body. Die Antwort gilt für genau eine Sitzung.
A POST to /v1/session. No auth header — the key
travels in the body. The response is good for exactly one session.
# -> token, server_url, ice_servers
curl -X POST https://aioos.ai/v1/session \
-H "Content-Type: application/json" \
-d '{"key":"wk_YOUR_KEY","page_origin":"https://your-domain.com"}'const res = await fetch("https://aioos.ai/v1/session", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
key: "wk_YOUR_KEY",
page_origin: location.origin
})
});
const { token, server_url, ice_servers } = await res.json();
Verbinden Sie sich mit dem zurückgegebenen server_url — immer
mit dem Wert aus der Antwort, nie mit einer fest eingetragenen Adresse. Ist
ice_servers gefüllt, reichen Sie es durch; steht dort
null, verbinden Sie ohne.
Connect using the returned server_url — always the value from
the response, never a hardcoded address. If ice_servers is filled,
pass it through; if it is null, connect without it.
import { Room } from "livekit-client";
const room = new Room(ice_servers ? { rtcConfig: { iceServers: ice_servers } } : {});
await room.connect(server_url, token);
await room.localParticipant.setMicrophoneEnabled(true);Wenn Sie nichts selbst bauen wollen: eine Zeile im HTML, und der Chatbot sitzt auf der Seite. Der Loader übernimmt Session-Aufbau und Mikrofon selbst.
If you would rather not build anything: one line of HTML and the chatbot sits on the page. The loader handles the session and the microphone by itself.
<script src="https://aioos.ai/embed.js" async></script>
<aioos-widget agent-id="wk_YOUR_KEY"
launcher="orb"
position="right"></aioos-widget>Das ist genau das Snippet, das dir das Widget-Studio in der Konsole erzeugt — kopiere es am besten von dort, dann sind Farbe, Begrüßung und Name schon eingetragen.This is exactly the snippet the Widget Studio in the console generates for you — copy it from there and your colour, greeting and name are already filled in.
| AttributAttribute | StandardDefault | BedeutungMeaning |
|---|---|---|
| agent-idPflichtrequired | — | Ihr Agent-Key (wk_…).Your agent key (wk_…). |
| launcheroptional | pill | pill, icon oderor orb. |
| positionoptional | right | right oderor left. |
| accent, theme, greeting, nameoptional | — | Aussehen und Begrüßung — am einfachsten aus dem Widget-Studio übernehmen.Appearance and greeting — easiest taken from the Widget Studio. |
Die einzige öffentliche Schnittstelle. Sie ist bewusst klein gehalten.
The only public endpoint. It is deliberately small.
| FeldField | TypType | BeschreibungDescription |
|---|---|---|
| keyPflichtrequired | string | Ihr Agent-Key (wk_…).Your agent key (wk_…). |
| page_originoptional | string | Aus dem Browser location.origin senden. Pflicht, sobald der Key eine Domain-Liste trägt; serverseitige Aufrufe dürfen es weglassen, solange keine Liste hinterlegt ist.Send location.origin from browsers. Required once the key carries an origin allowlist; server-side callers may omit it while the key has no allowlist. |
| FeldField | TypType | BeschreibungDescription |
|---|---|---|
| token | string | Einmal-Credential für genau eine Sitzung. Nicht zwischenspeichern, nicht weitergeben.Single-use credential for exactly one session. Do not cache or share it. |
| server_url | string | WebSocket-Adresse. Immer den zurückgegebenen Wert verwenden.WebSocket address. Always use the returned value. |
| ice_servers | array | null | Kurzlebige TURN-Zugangsdaten für restriktive Firmennetze. Bei null ohne verbinden.Short-lived TURN credentials for restrictive corporate networks. On null, connect without them. |
Fehler kommen als {"error": "…"} zurück.Errors come back as {"error": "…"}.
| Status | error | BedeutungMeaning |
|---|---|---|
| 400 | bad_body / bad_key |
Ungültiges JSON, oder der Key ist kein gültiger wk_…-String.Malformed JSON, or the key is not a valid wk_… string. |
| 402 | no_minutes |
Das Minutenkontingent Ihres Tarifs ist leer.Your plan's minute pool is empty. |
| 403 | unknown_key |
Der Key existiert nicht oder wurde widerrufen.The key does not exist or was revoked. |
| 403 | origin_not_allowed |
Der Key beschränkt Domains und page_origin steht nicht auf der Liste.The key restricts origins and page_origin is not on the list. |
| 429 | rate_limited |
10 Anfragen/min pro IP, 30 pro Key. Zurücknehmen und erneut versuchen.10 requests/min per IP, 30 per key. Back off and retry. |
| 5xx | internal |
Vorübergehendes Serverproblem. Mit Backoff wiederholen.Transient server problem. Retry with backoff. |
Dieselbe Schnittstelle, derselbe Ablauf — nur die Client-Bibliothek ist eine andere.
Legen Sie die Session serverseitig an, wenn Sie den Key nicht in die App ausliefern
wollen: Ihr Backend ruft /v1/session auf und reicht token
und server_url an die App weiter. Auf dem Gerät verbinden Sie damit
über die Realtime-Bibliothek Ihrer Plattform (iOS, Android oder React Native).
Der schnellste Weg zu einem funktionierenden Prototyp bleibt ein WebView auf eine
Seite mit dem Chatbot-Snippet — die
Schritt-für-Schritt-WebView-Anleitung (Mikrofon-Freigabe
fuer iOS und Android) steht in der Dokumentation.
Ehrlich gesagt: ein eigenes, installierbares AIOOS-SDK für iOS oder Android gibt es heute nicht. Was es gibt, ist diese REST-Schnittstelle plus die Realtime-Bibliotheken, die ohnehin für jede Plattform existieren. Wenn Sie ein natives Paket brauchen, sagen Sie uns, für welche Plattform — das entscheidet die Reihenfolge.
Same interface, same flow — only the client library differs.
Create the session server-side if you would rather not ship the key inside the app:
your backend calls /v1/session and hands token and
server_url to the app. On the device you connect with the realtime
library for your platform (iOS, Android or React Native). The fastest route to
a working prototype is still a WebView pointed at a page carrying the chatbot snippet —
the step-by-step WebView guide (microphone permission for iOS
and Android) is in the documentation.
To be straight with you: there is no installable AIOOS SDK for iOS or Android today. What exists is this REST endpoint plus the realtime libraries that ship for every platform anyway. If you need a native package, tell us which platform — that is what decides the order of work.
Die ausführliche Dokumentation liegt zweisprachig vor, Deutsch und Englisch.
The full documentation is available in both German and English.
Vollständige Anleitung: Quickstart, Echtzeit-Protokoll, Fehlersuche, Abrechnung und Limits.The full guide: quickstart, realtime protocol, troubleshooting, metering and limits.
Dokumentation öffnen →Open the docs →Maschinenlesbare Beschreibung der Schnittstelle — für Postman, Swagger oder Client-Generatoren.Machine-readable description of the interface — for Postman, Swagger or client generators.
openapi.json →Fehlt ein Endpunkt, ein Paket oder ein Beispiel für Ihre Plattform? Schreiben Sie uns.Missing an endpoint, a package or an example for your platform? Write to us.
hello@aioos.ai →