AIOOS Docs — für Betriebe und Entwickler

Alles, was du deinem AIOOS-Assistenten beibringen und an ihm einstellen kannst — Schritt für Schritt, mit den Wörtern, die auf dem Bildschirm stehen. Du brauchst dafür keine Technik und keinen Dienstleister. Wenn etwas noch nicht geht, steht es hier genauso ehrlich wie in der App. Deine Konsole findest du unter aioos.ai/app; die technische Doku für Entwickler steht weiter unten.

Anlernen — dem Assistenten etwas beibringen

Was es macht

„Anlernen“ ist der eine Ort für alles, was dein Assistent weiß. Du gibst ihm Material — eine Seite deiner Website, ein PDF, ein Foto, eine Tabelle, eine Aufnahme oder einen selbst geschriebenen Text. Er liest es, sagt dir zurück, was er verstanden hat, und stellt dir zwei Fragen: für wen das ist und wohin damit. Danach antwortet er daraus — am Telefon und im Web-Chat. Eine zweite Seite namens „Wissen“ gibt es nicht mehr; sie ist hier aufgegangen.

So geht es

Menü oben links öffnen und in der Seitenleiste „Anlernen“ antippen.
Auf der Karte „Was soll ich lernen?“ einen der sechs Wege wählen: „Website-Link“, „PDF“, „Bild/Foto“, „Tabelle“, „Video & Audio“, „Text & Notizen“. Unter jeder Kachel steht ihre Grenze — „bis 32 MB“, „bis 6 MB“, „bis 500 MB · 60 Min“.
Website-Link: die Adresse eintippen (das Feld zeigt www.deine-seite.at/leistungen) und „Anlernen“ antippen.
Datei: „Datei wählen“ antippen und die Datei aussuchen; daneben steht danach „Gewählt: …“.
Text: schreiben — die erste Zeile wird der Titel — und „Anlernen“ antippen.
Warten, bis das Wort „Gelernt“ steht. PDF, Foto, Video und Ton liest der Server; solange steht dort „Wartet auf den Leser …“ und „Der Assistent liest gerade …“.
Die Karte „Das habe ich verstanden“ lesen: „Erkannt als …“, die Stichpunkte und „Das könnten Anrufer fragen“.
„Für wen ist das?“ beantworten: „Für Anrufer / Kunden“ oder „Für unsere Mitarbeiter“.
„Wohin damit?“ beantworten: „Zum Assistenten hinzufügen“ oder „Eigenen Assistenten dafür anlegen“.
„Hinzufügen“ antippen. Beim eigenen Assistenten heißt der Knopf „Assistenten anlegen“, und du gibst vorher unter „Name des neuen Assistenten“ einen Namen ein.

Gut zu wissen

Der Website-Link liest genau diese eine Seite, nicht die ganze Website. Für mehrere Seiten mehrmals anlernen.

Die Zahlen unter den Kacheln fragt die Seite beim Server nach, sie stehen nicht fest im Programm. Heute gilt:

Weg	Grenze
PDF	bis 32 MB
Bild/Foto (jpg, png, webp)	bis 6 MB
Video	bis 500 MB und höchstens 60 Minuten
Ton	bis 100 MB und höchstens 60 Minuten
Tabelle (.csv, .xlsx)	bis 6 MB, bis 5.000 Zeilen
Textdatei	bis 4 MB
Website-Link, Text & Notizen	keine Dateigrenze

Solange „Für wen ist das?“ offen ist, hört kein Anrufer das Thema. In der Liste steht dann „Für wen? — noch offen“, die Kopfzeile zählt mit („2 warten auf ‚Für wen?'“), und ein Klick auf „Für Anrufer freigeben“ erledigt es.
„Für unsere Mitarbeiter“ heißt: der Assistent bekommt das Thema am Telefon und im Web-Chat gar nicht erst — er kann es nicht ausplaudern, weil er es nicht hat. Wer es hören soll, nennt die Mitarbeiter-PIN. In der Konsole siehst du es immer.
„Eigenen Assistenten dafür anlegen“ baut einen zweiten Assistenten, der nur dieses Thema kennt. Er belegt einen eigenen Betriebs-Platz und hat eigene Minuten, und er entsteht erst nach deiner Bestätigung — nie still.
Ändern und Löschen stehen in derselben Liste: „Das kann dein Assistent schon“ → „Ändern“ → Felder „Titel“ und „Das weiß er darüber“ → „Speichern“. „Löschen“ fragt einmal nach: „Wirklich löschen? Der Assistent weiß es dann nicht mehr.“
Jedes gelernte Thema trägt seine Herkunft im Text: „Quelle: … · gelernt am …“.
Alte Excel-Dateien im .xls-Format liest er nicht. Der Satz dazu lautet: „Bitte als .xlsx oder .csv speichern.“
Ein YouTube-Link wird hier nicht angenommen — warum, steht bei Video & Audio.

Wenn etwas nicht klappt

Die Karte sagt ihren Zustand als Wort, nie als Farbpunkt:

„Noch nichts“: Auf diesem Weg ist noch nichts passiert.
„Wird gelesen …“: Läuft gerade. Bei großen Dateien liest der Server mit und zählt den Fortschritt mit.
„Gelernt“: Steht in der Liste „Das kann dein Assistent schon“.
„Fehlgeschlagen“: Der Grund steht darunter, im Klartext.
„Noch nicht“: Diesen Weg gibt es, er ist auf diesem Server aber nicht eingerichtet oder noch nicht gebaut. Kein Fehler.
Unter einer geschlossenen Kachel: „prüfe …“ · „nicht erreichbar“ · „noch nicht“: Drei verschiedene Dinge: die Seite fragt gerade beim Server nach · sie konnte ihn nicht fragen · er kann es nicht.

Die Sätze, die dabei am häufigsten auftauchen:

„Die Seite war nicht lesbar (HTTP 404).“: Die Adresse stimmt nicht oder die Seite ist gesperrt. Adresse im Browser öffnen und vergleichen.
„Auf der Seite stand kein lesbarer Text — vielleicht ist sie nur ein Bild oder braucht einen Login.“: Eine Unterseite mit echtem Fließtext nehmen, oder den Text als Notiz selbst schreiben.
„Auf der Seite stand zu wenig Verwertbares …“: Meist ein Cookie-Hinweis oder eine reine Navigationsseite. Das Thema ist trotzdem gespeichert; besser ist eine Unterseite mit Inhalt.
„Aus dieser Datei war kein Text zu lesen.“: Ein gescanntes PDF ohne Texterkennung oder eine leere Datei. Als Foto anlernen ist oft der bessere Weg.
„Dieser Betrieb ist noch nicht gespeichert — schließ zuerst die Einrichtung ab.“: Der Betrieb hat noch keine gespeicherte Fassung. Einrichtung zu Ende gehen, dann noch einmal.
„Die Grenzen konnten gerade nicht beim Server erfragt werden — die angezeigten Werte sind die üblichen, nicht die geprüften.“: Die Zahlen unter den Kacheln sind in diesem Moment ungeprüft. Hochladen geht trotzdem; im Zweifel meldet der Upload die echte Grenze.
„Neues Wissen ist inzwischen dazugekommen — zusammengeführt“: Während du die Konsole offen hattest, ist von außen ein Thema dazugekommen — etwa per E-Mail an den Assistenten. Deine Änderungen wurden behalten und das neue Thema übernommen. Es ist nichts verloren, du musst nichts tun.

Mitarbeiter-PIN

Was es macht

Themen, die du auf „Für unsere Mitarbeiter“ gestellt hast, stehen am Telefon und im öffentlichen Web-Chat gar nicht im Kopf des Assistenten. Er kann sie nicht ausplaudern, weil er sie nicht hat. Nennt jemand im Gespräch die vierstellige Mitarbeiter-PIN, bekommt er sie für dieses eine Gespräch. In der Konsole siehst du dieses Wissen immer, auch ohne PIN.

So geht es

In der Seitenleiste „Anlernen“ öffnen.
Rechts die Karte „Mitarbeiter-PIN“ suchen („Vier Ziffern, mit denen deine Leute am Telefon auch das interne Wissen hören“).
In das Feld vier Ziffern tippen — der Platzhalter zeigt „4 Ziffern, z. B. 4711“.
„PIN setzen“ antippen. Danach steht als Zustand „Gesetzt“ und darunter: „PIN gesetzt. Ab dem nächsten Anruf gilt sie.“
Ein Thema auf „Für unsere Mitarbeiter“ stellen — beim Anlernen bei „Für wen ist das?“, oder später über „Ändern“.
Zum Ändern: „Neue PIN“ → vier Ziffern → „PIN ersetzen“. Zum Abschalten: „Entfernen“ — zehn Sekunden lang steht dann „Rückgängig“ daneben.

Gut zu wissen

Genau vier Ziffern. Am Telefon ist es egal, wie sie gesprochen werden — „1234“, „1 2 3 4“ und „12-34“ sind dieselbe PIN.
Drei Versuche je Gespräch. Danach fragt der Assistent im selben Gespräch nicht mehr danach und bietet das Freischalten nicht mehr an. Beim falschen Versuch sagt er nur, dass es nicht stimmt — nie, welche Ziffer falsch war.
Ohne gesetzte PIN kommt niemand an internes Wissen — auch deine eigenen Leute nicht. Der Assistent weiß dann nicht einmal, dass es eine PIN geben könnte. Hast du internes Wissen ohne PIN hinterlegt, sagt die Karte das ausdrücklich.
Die PIN wird nirgends im Klartext gespeichert und steht in keinem Gesprächsprotokoll und keinem Transkript. Vergessen ist kein Problem: einfach eine neue setzen.
Die PIN gilt für Telefon und öffentlichen Web-Chat. Ein Testanruf aus deiner eingeloggten Konsole hat das interne Wissen sofort — dort bist du schon angemeldet.
Produkte sind ausgenommen: eine Preisliste ist per Definition öffentlich und bleibt es.
Ehrlich gesagt: vier Ziffern halten Neugierige auf, keinen Angreifer. Und wer sich in diese Konsole einloggen kann, sieht das interne Wissen ohnehin — die PIN schützt den Telefon- und Chat-Weg, nicht dein Konto.

Wenn etwas nicht klappt

„Nicht gesetzt“: Es gibt keine PIN. Internes Wissen ist am Telefon und im Web-Chat unerreichbar.
„Gesetzt“: Die PIN liegt am Betrieb. Daneben steht das Datum.
„PIN entfernt. Internes Wissen ist am Telefon jetzt gar nicht mehr erreichbar.“: Genau so gemeint. Solange kein Ersatz gesetzt ist, hört niemand dieses Wissen mehr.
Der Anrufer hört „Das kann ich am Telefon nicht sagen“: So klingt das geschlossene Tor. Der Assistent bietet dann an, es freizuschalten, wenn die vierstellige Mitarbeiter-PIN genannt wird. Die Ziffern liest er nie vor und wiederholt er nie.
Nach drei falschen Versuchen sagt er gar nichts mehr dazu: Für dieses Gespräch ist das Tor zu. Auflegen und neu anrufen.

Live-Tabelle — Preise, die sich ändern

Was es macht

Eine Tabelle kannst du einmal einlesen oder live halten. Live heißt: die Datei bleibt die Quelle und wird bei jedem Anruf frisch gelesen. Änderst du morgen einen Preis in der Datei, sagt der Assistent ihn beim nächsten Anruf — ohne dass du etwas neu anlernst. Die Zeilen stehen nicht in seinem Gedächtnis; er schlägt sie während des Gesprächs nach.

So geht es

In der Seitenleiste „Anlernen“ öffnen.
Die Kachel „Tabelle“ wählen (darunter steht „CSV/Excel“).
„Datei wählen“ antippen und die .csv- oder .xlsx-Datei aussuchen.
Die Seite fragt jetzt. Zwei gleichwertige Knöpfe:
- „Einmal einlesen“ — „Der Inhalt wird jetzt zu Wissen. Änderst du die Datei später, merkt er davon nichts.“
- „Als Tabelle live halten“ — „Wir lesen die Datei bei jedem Anruf neu. Änderst du einen Preis in der Datei, sagt der Assistent ihn beim nächsten Anruf — ohne dass du etwas anlernen musst.“
In der Liste „Das kann dein Assistent schon“ steht das Thema danach mit dem Wort „live“ und dem Dateinamen.
Neue Fassung einspielen: beim Thema „Ändern“ → „Datei ersetzen“ → neue Datei wählen. Das Thema bleibt dasselbe, der Assistent antwortet weiter darauf.

Gut zu wissen

Nur .csv und .xlsx. Altes .xls wird abgelehnt: „Bitte als .xlsx oder .csv speichern.“
Deutsche Tabellen sind eingeplant: Semikolon als Trenner, Umlaute und Beträge wie „24,90“ bleiben so, wie sie in der Datei stehen.
Formeln werden nie gerechnet — gelesen wird der Wert, den Excel zuletzt gespeichert hat. Eine Zelle ohne gespeicherten Wert bleibt leer; geraten wird nichts.
Gelesen wird einmal pro Anruf, nicht bei jeder Frage. Das Nachschlagen selbst dauert Millisekunden — auf einer Tabelle mit 2.000 Zeilen gemessen 12 bis 29 ms. Im Gespräch merkt niemand eine Pause.
Höchstens 5.000 Zeilen und 6 MB. Ist die Datei länger, sagt der Assistent im Gespräch offen dazu, dass er nur den vorderen Teil der Liste sehen konnte.
Er nennt bis zu fünf passende Zeilen je Frage. Rechnen über die Tabelle hinweg kann er nicht — „Was ist euer billigstes Brot?“ beantwortet er nicht aus der Tabelle.
Der Text beim Thema ist nur die Beschreibung („Aktuelle Werte aus ‚Preisliste' (Spalten: Artikel, Preis, Verfügbar).“) — die Zeilen stehen in der Datei. Du darfst diese Beschreibung frei umschreiben.
Er schreibt nie in deine Tabelle zurück. Er liest nur.
Klare Spaltenköpfe helfen: „Artikel“, „Preis“, „Verfügbar“ trifft besser als „Sp1“, „Sp2“.
Steht eine Live-Tabelle auf „Für unsere Mitarbeiter“, ist sie für Anrufer vollständig unsichtbar — auch ihr Titel.

Wenn etwas nicht klappt

„Wird gelesen …“ / „Gelernt“: Wie bei jedem anderen Weg. Danach steht am Thema „live“ und der Dateiname.
Der Anrufer hört: „dazu habe ich keine Angabe“: Kein Treffer in der Tabelle — oder die Datei war in diesem Moment nicht lesbar. Beides klingt gleich, und zwar mit Absicht: der Assistent erfindet in keinem Fall einen Wert. Wenn ein Wert wiederholt fehlt, obwohl er in der Datei steht: die Datei über „Datei ersetzen“ neu hochladen.
„Bitte als .xlsx oder .csv speichern.“: Die Datei ist im alten .xls-Format. In Excel unter „Speichern unter“ als .xlsx ablegen.
„Das ist keine Tabelle — bitte eine .csv- oder .xlsx-Datei.“: Beim Ersetzen wurde eine andere Dateiart gewählt.
Der Assistent nennt einen alten Preis: Dann ist das Thema wahrscheinlich „Einmal einlesen“ und nicht live. Am Thema fehlt in dem Fall das Wort „live“. Datei noch einmal hochladen und diesmal „Als Tabelle live halten“ wählen.

Das wird gefragt — und er weiß es nicht

Was es macht

Der Assistent merkt sich, was Anrufer wissen wollten und er nicht beantworten konnte. Auf der Anlernen-Seite steht das als Liste: der Wortlaut der Frage, wie oft sie kam und wann zuletzt. Ein Klick macht daraus ein neues Thema. So schließt sich die Lücke dort, wo sie aufgefallen ist.

So geht es

In der Seitenleiste „Anlernen“ öffnen. Steht dort eine Zahl neben dem Wort, sind so viele Fragen offen.
Rechts die Karte „Das wird gefragt — und er weiß es nicht“ lesen. Darunter steht, woher die Fragen kommen: „Aus den Telefonaten der letzten sieben Tage.“
Jede Zeile zeigt die Frage in Anführungszeichen, dazu „3× gefragt“ oder „einmal gefragt“ und das Datum.
Bei einer Frage „Antwort eintragen“ antippen.
Die Seite springt in das Schreibfeld von „Text & Notizen“. Die Frage steht dort schon als erste Zeile — sie wird der Titel. Darunter die Antwort schreiben.
„Anlernen“ antippen, dann wie gewohnt „Für wen ist das?“ und „Wohin damit?“ beantworten und „Hinzufügen“ drücken.

Gut zu wissen

Die Liste ist eine Auswertung der letzten sieben Tage, kein Live-Ticker. Geholt wird sie beim Öffnen der Konsole, und nach jedem angelernten Thema noch einmal.
Gespeist wird sie aus Gesprächen, die eine Zusammenfassung hinterlassen. Ein sehr kurzes Gespräch mit weniger als zwei Wortwechseln erzeugt keine — das ist Absicht, sonst stünden Fehlanrufe in der Liste.
Die Zahl neben „Anlernen“ in der Seitenleiste zeigt dieselben offenen Fragen. Konnte der Server nicht gefragt werden, erscheint gar keine Zahl — nie eine falsche Null.
Ist nichts offen, bleibt die Karte stehen und sagt: „Bisher ist keine Frage offen geblieben.“ Auch das ist eine Auskunft.
Dieselbe Frage in anderen Worten kann noch einmal auftauchen. Dann steht sie ehrlich wieder da, statt still verschluckt zu werden.

Wenn etwas nicht klappt

Die Karte ist gar nicht da: Wahrscheinlich wird sie noch geladen — oder der Server konnte nicht gefragt werden. In dem Fall erfindet die Karte keine leere Liste, sondern bleibt weg. Seite neu laden.
Die Liste bleibt leer, obwohl im Web-Chat viel gefragt wurde: Heute speisen Telefonate diese Liste. Fragen aus dem Website-Chatbot landen noch nicht darin. Die Überschrift sagt das ausdrücklich, damit du nicht auf eine Vollständigkeit baust, die es noch nicht gibt.
Die Zahl an der Seitenleiste verschwindet nicht sofort: Die Zahl wird nach dem Anlernen neu geholt. Wechsel einmal die Seite oder lade neu.

E-Mail an den Assistenten

Was es macht

Dein Assistent kann eine eigene E-Mail-Adresse bekommen. Alles, was du dorthin weiterleitest, wird zu Wissen: der Betreff wird der Titel, der Text wird das Thema, und jeder Anhang wird ein eigenes Thema. Damit dir niemand Fremdes etwas unterschiebt, gilt eine Liste erlaubter Absender — und nur wer darauf steht, kommt durch.

So geht es

In der Seitenleiste „Anlernen“ öffnen und rechts zur Karte „Quellen“ gehen.
„Adresse einrichten“ antippen. Danach steht dort unter „Deine Wissens-Adresse“ eine Adresse der Form dein-betrieb-k7m2q9@wissen.aioos.ai. Diese Adresse ändert sich nie wieder — ruhig in die Kontakte eintragen.
Unter „Wer hierher schicken darf“ steht deine eigene Anmelde-Adresse schon drin. Weitere eintragen: Adresse in das Feld („name@firma.at“) und „Erlauben“ antippen.
Eine Mail mit Notiz oder Anhang an die Wissens-Adresse weiterleiten.
Unter „Zuletzt angekommen“ nachsehen, was daraus wurde: „Gelernt“, „Empfangen“, „Abgelehnt“, „Doppelt“.
Pause machen: „Eingang pausieren“. Wieder an: „Eingang wieder aktivieren“.

Gut zu wissen

Solange die Liste leer ist, wird jede Mail abgelehnt. Das ist kein Fehler, sondern der Schutz. Höchstens 20 Adressen.
Groß- und Kleinschreibung ist egal, ein Zusatz wie +preise hinter dem Namen auch — beides landet im selben Eingang.

Was aus einer Mail wird:

Teil der Mail	Ergebnis
Betreff	der Titel des Themas
Mail-Text	ein Thema — erst ab 40 Zeichen. „Hier die Liste“ allein wird übergangen.
PDF, Bild (jpg, png, webp, gif)	je ein eigenes Thema — PDF bis 32 MB, Bild bis 6 MB
.csv, .txt, .md, .json, .xml, .yaml, .tsv	je ein eigenes Thema, bis 256 KB
alles andere (z. B. .zip, .docx)	übersprungen, mit Grund in der Liste

Eine ganze Mail darf höchstens 25 MB haben. Größeres lädst du direkt in der App hoch.
Formatierung wird verworfen, gelesen wird der reine Text. Links in der Mail werden nicht geöffnet und Anhänge nie ausgeführt.
Der Absender wird zweifach geprüft: der technische Absender und der im Text sichtbare müssen beide auf deiner Liste stehen. Das fängt Mails ab, die sich als jemand anderes ausgeben.
Du bekommst keine Bestätigungsmail zurück. Was aus einer Mail wurde, steht in der Konsole.
Es werden die letzten zehn Mails angezeigt.
Höchstens 30 Mails pro Minute je Assistent.

Wenn etwas nicht klappt

Die Karte zeigt keinen Knopf „Adresse einrichten“, sondern nur einen Ladehinweis: Der Mail-Weg ist auf diesem Server noch nicht freigeschaltet. Für den Eingang braucht AIOOS erst einen Mail-Anbieter samt DNS-Eintrag für wissen.aioos.ai; bis dahin kann keine Mail ankommen. Bei Fragen: hello@aioos.ai.
„Gelernt“: Angenommen, und mindestens ein Thema ist daraus entstanden. Daneben steht, wie viele.
„Empfangen“: Angenommen — aber es war nichts Lernbares drin. Meist ein zu kurzer Text ohne brauchbaren Anhang.
„Abgelehnt“ · „Diese Absenderadresse steht nicht auf deiner Liste.“: Der einzige Fall, den du selbst heilen kannst: daneben steht ein Knopf „… erlauben“. Ein Klick, und die Adresse ist auf der Liste.
„Abgelehnt“ · „Die Mail kam von einer erlaubten Adresse, war im Text aber als jemand anderes ausgegeben — ein Fälschungsversuch.“: Hier bieten wir bewusst nichts zum Freischalten an. Genau davor schützt die Prüfung.
„Abgelehnt“ · „Der Absender-Server konnte nicht bestätigt werden (SPF).“: Die Mail kam über einen Weg, der sich nicht ausweisen konnte. Häufig bei Weiterleitungen über alte Postfächer. Am besten direkt aus dem eigenen Mailprogramm schicken.
„Abgelehnt“ · „Die Signatur der Mail stimmte nicht (DKIM).“ / „Der Anbieter hat die Mail als Werbung eingestuft.“: Der Mail-Anbieter hat die Mail beanstandet. Noch einmal schicken, ohne Weiterleitungskette.
„Abgelehnt“ · „Der Mail-Eingang war zu diesem Zeitpunkt pausiert.“: Eingang wieder aktivieren, dann erneut schicken.
„Doppelt“: Dieselbe Mail ist schon einmal angekommen. Nichts wird doppelt gelernt.
„2 Anhänge nicht gelesen: preise.zip (dieses Dateiformat kann er nicht lesen)“: Steht auch bei angenommenen Mails. So merkst du, dass er auf eine Datei wartet, die nie angekommen ist. Die Gründe lauten „zu groß“, „dieses Dateiformat kann er nicht lesen“, „unlesbare Zeichenkodierung“ oder „beim Einlesen abgelehnt“.
„Noch nichts angekommen. Falls du schon etwas geschickt hast: die Zustellung wird gerade eingerichtet, das kann etwas dauern.“: Der Eingang steht, aber es ist noch nichts durchgekommen.

API-Schlüssel — wenn eure eigene Software schicken soll

Was es macht

Mit einem Schlüssel kann eure eigene Software Wissen an den Assistenten schicken — eine Warenwirtschaft, ein nächtlicher Export, ein Skript, ein Webhook. Der Schlüssel gilt für den ganzen Betrieb und kann nur eines: Wissen schreiben. Er kann keine Rechnungen sehen, keine Telefonnummern ändern, keine anderen Schlüssel lesen und keine Gespräche abrufen.

So geht es

In der Seitenleiste „Anlernen“ öffnen, rechts zur Karte „Quellen“.
Ganz unten „Für Entwickler“ antippen — der Block klappt auf.
In das Feld hineinschreiben, wofür der Schlüssel ist („z.B. Warenwirtschaft“), dann „Schlüssel anlegen“.
Der Schlüssel erscheint einmal: „Dieser Schlüssel wird nur jetzt angezeigt.“ Kopieren und sicher ablegen.
Den Schlüssel an die Software oder den IT-Dienstleister übergeben. Die technische Anleitung steht in der Entwickler-Doku.
Verloren oder aus der Hand gegeben? „Neu ausstellen“ → die Rückfrage bestätigen mit „Ja, neu ausstellen“. Nicht mehr gebraucht? „Ungültig machen“.

Gut zu wissen

Ein Schlüssel sieht so aus: aioos_ und danach 64 Zeichen, zusammen 70. In der Liste steht nur der Anfang, dazu „angelegt am …“ und „zuletzt benutzt …“ oder „noch nie benutzt“.
Der Schlüssel wird nur einmal gezeigt. Wir speichern ihn nicht im Klartext und können ihn nicht noch einmal anzeigen — verloren heißt: neuen ausstellen.
„Neu ausstellen“ tauscht in einem Zug: der alte gilt im selben Moment nicht mehr, es gibt keine Übergangszeit. Erst den neuen holen, dann die Software umstellen.
„Ungültig machen“ wirkt sofort und lässt sich nicht rückgängig machen. Der Eintrag bleibt danach als „Ungültig“ in der Liste stehen.
Höchstens 10 aktive Schlüssel je Betrieb. Danach: „Höchstens 10 aktive Schlüssel — bitte zuerst einen widerrufen“.
Tempo: bis zu 60 Texte je Minute und bis zu 20 Dateien je Minute (PDF oder Bild) pro Schlüssel. Wer schneller schickt, bekommt eine Absage und soll kurz warten.
Ein Schlüssel deines Betriebs kann nur in Assistenten deines Betriebs schreiben. Für einen fremden gibt es kein Ergebnis und keinen Eintrag.

Wenn etwas nicht klappt

„Ungültig“ in der Liste: Der Schlüssel wurde ungültig gemacht oder ersetzt. Software auf einen neuen umstellen.
Die Software meldet 401: Der Schlüssel stimmt nicht: falsch kopiert, abgeschnitten, oder er wurde ersetzt bzw. ungültig gemacht. Neu ausstellen und sauber übertragen.
Die Software meldet 404: Der angesprochene Assistent gehört nicht zu diesem Betrieb. Es wird dann auch nichts gespeichert.
Die Software meldet 429: Zu viele Aufrufe in einer Minute. Die Software soll warten und es noch einmal versuchen.
Die Software meldet 403: Mit einem Schlüssel wurde etwas versucht, das er nicht darf — etwa Schlüssel verwalten oder den Mail-Eingang ändern. Das geht nur eingeloggt in der Konsole.

OneDrive-Ordner

Was es macht

Ein Ordner in deinem OneDrive — was du hineinlegst, lernt der Assistent. Wir legen den Ordner „AIOOS Wissen“ selbst an; du musst nichts auswählen und nichts einstellen. Danach genügt es, eine Preisliste oder ein Angebot dort abzuspeichern.

So geht es

In der Seitenleiste „Anlernen“ öffnen und die Karte „Quellen“ mit dem Untertitel „Ein Ordner in deinem OneDrive“ suchen.
„Mit OneDrive verbinden“ antippen.
Im Microsoft-Fenster anmelden und den Zugriff bestätigen.
Zurück in der App steht als Zustand „Verbunden“, dazu der Ordnername und das Konto.
OneDrive öffnen, den Ordner „AIOOS Wissen“ suchen und Dateien direkt hineinlegen.
Warten — er sieht spätestens nach fünf Minuten nach — oder „Jetzt prüfen“ antippen.

Gut zu wissen

Geprüft wird alle 5 Minuten, fest. „Jetzt prüfen“ geht dazwischen, höchstens ein paar Mal pro Minute.
Unterordner werden nicht gelesen — die Dateien direkt in „AIOOS Wissen“ legen.
Jede Datei steht danach mit ihrem Zustand in der Karte: „Wartet“, „Wird gelesen“, „Gelernt“, „Fehlgeschlagen“, „Nicht lesbar“, „Datei entfernt“.
Löschen löscht nichts. Nimmst du eine Datei aus dem Ordner, bleibt das Gelernte bestehen und wird nur markiert: „Der Assistent weiß es weiterhin — gelöscht wird nichts von selbst.“ Soll er es wirklich vergessen, lösch das Thema in der Liste „Das kann dein Assistent schon“.
Ehrlich zur Berechtigung: Microsoft fragt beim Anmelden nach dem Recht, Dateien zu lesen und zu schreiben. Das klingt nach mehr, als wir tun. Es gibt bei Microsoft keine Berechtigung, die sich auf einen einzelnen benannten Ordner beschränken lässt und trotzdem Änderungen mitbekommt. Wir rühren nur „AIOOS Wissen“ an — das ist unsere Zusage, nicht Microsofts Zwang.
„Verbindung trennen“ fragt einmal nach: „Trennen? Der Ordner bleibt, und was der Assistent gelernt hat, bleibt auch.“

Wenn etwas nicht klappt

„Noch nicht verfügbar“ · „Diese Verbindung ist auf diesem Server noch nicht freigeschaltet.“: Das ist heute der Normalfall. Der Zugang zu Microsoft muss von AIOOS erst hinterlegt werden; erst dann erscheint der Knopf. Bis dahin lädst du die Dateien direkt auf der Anlernen-Seite hoch — das Ergebnis ist dasselbe.
„OneDrive ist auf diesem Server noch nicht eingerichtet.“: Derselbe Grund, gemeldet beim Klick auf den Knopf.
„Wird geprüft …“: Der Rückweg von Microsoft läuft noch. Kurz warten.
„Die Verbindung mit Microsoft hat nicht geklappt. Bitte noch einmal versuchen.“: Die Anmeldung wurde abgebrochen oder abgelehnt. „Mit OneDrive verbinden“ noch einmal.
„Die Anmeldung hat zu lange gedauert. Bitte noch einmal verbinden.“: Das Anmeldefenster stand zu lange offen. Einfach neu starten.
„Fehlgeschlagen“ mit einem Satz darunter: Meist ist die Zustimmung abgelaufen oder wurde im Microsoft-Konto zurückgezogen. „Neu verbinden“ antippen.
„Es wird schon geprüft. Bitte eine Minute warten.“: „Jetzt prüfen“ wurde zu oft hintereinander gedrückt.
Eine Datei steht auf „Nicht lesbar“: Dieses Dateiformat kann er nicht lesen. Als PDF, Bild, Text oder Tabelle ablegen.

Video & Audio

Was es macht

Der Assistent kann eine Aufnahme abhören und mitschreiben: eine gesprochene Notiz, ein Schulungsvideo, eine Einweisung. Aus dem Gesprochenen wird Text mit Zeitmarken, und daraus wird ein Thema wie jedes andere. Du musst nichts abtippen.

So geht es

In der Seitenleiste „Anlernen“ öffnen.
Die Kachel „Video & Audio“ wählen. Darunter steht die Grenze: „bis 500 MB · 60 Min“.
„Datei wählen“ antippen und die Aufnahme aussuchen.
Zusehen, wie er arbeitet: „… wird hochgeladen …“, dann „Der Assistent liest gerade …“ mit dem Fortschritt in Prozent.
Unter „Das habe ich verstanden“ nachlesen, was er herausgehört hat.
„Für wen ist das?“ und „Wohin damit?“ beantworten, dann „Hinzufügen“.

Gut zu wissen

Grenzen: Video bis 500 MB, Ton bis 100 MB, beides höchstens 60 Minuten. Ein längeres Video wird abgelehnt, nicht heimlich abgeschnitten — lieber vorher den wichtigen Teil herausschneiden.
Der Dateidialog nimmt .mp4 .mov .m4v .webm .mkv sowie .mp3 .m4a .wav .ogg .opus .aac.
Lange Aufnahmen zerlegt er im Hintergrund in Zehn-Minuten-Stücke. Ein Video von zwölf Minuten war im Test in gut zwanzig Sekunden fertig.
Der Text bekommt Zeitmarken wie [04:12]. Ist die Aufnahme sehr lang, verdichtet er den Text und behält die Zeitmarken — das vollständige Transkript bleibt gespeichert.
Er übersetzt nicht: die Sprache der Aufnahme bleibt die Sprache des Themas.
Das Abhören ist im Preis enthalten; es wird dir nicht extra verrechnet.
Über den E-Mail-Eingang lassen sich Video und Ton nicht schicken — dafür ist die Konsole der Weg.

Wenn etwas nicht klappt

Die Kachel „Video & Audio“ ist zu und trägt das Wort „noch nicht“: In der Karte steht dann: „Video, Ton und YouTube sind auf diesem Server nicht eingerichtet. Sobald der Mitschreiber da ist, hört der Assistent Video- und Tondateien ab und schreibt mit.“ Das ist heute der Normalfall — bis der Mitschreiber eingerichtet ist, ist der Weg sichtbar, aber zu.
„prüfe …“: Die Seite fragt gerade beim Server nach, ob er Video und Ton lesen kann.
„nicht erreichbar“ · „Ich konnte den Server gerade nicht fragen …“: Später noch einmal versuchen — hochladen würde jetzt nur eine Absage geben.
„Fehlgeschlagen“: Der Grund steht darunter: zu groß, zu lang, keine verständliche Tonspur, oder gar keine Mediendatei.
YouTube-Link: „Noch nicht“: Unten auf der Seite steht die Karte „Kommt als Nächstes“ mit der Zeile „YouTube-Link“ und dem Wort „Noch nicht“. Der Grund daneben: „Derselbe fehlende Mitschreiber wie bei Video- und Tondateien — und zusätzlich muss er das Video erst von YouTube holen dürfen.“ YouTube behandelt unseren Server als Maschine und lässt ihn die Tonspur nicht holen. Fügst du trotzdem einen YouTube-Link in das Website-Feld ein, sagt die Seite es sofort und schickt nichts: „YouTube-Links kann er noch nicht — er müsste das Video erst anhören und mitschreiben. Eine Seite mit Text liest er sofort.“ Der Weg heute: das Video als Datei hochladen, oder den Inhalt als Notiz schreiben.

AI to go — dein Assistent zum Mitnehmen

Was es macht

Eine Karte mit QR-Code und ein Link. Wer den Code scannt, spricht sofort mit deinem Assistenten — keine App, keine Installation. Gut für die Visitenkarte, den Aufsteller am Tresen, das Schaufenster oder die Signatur. Standardmäßig antwortet er mit dem Wissen deines Betriebs; für eine einzelne Person kannst du auch einen eigenen Bereich mit eigenem Wissen anlegen.

So geht es

In der Seitenleiste „AI to go“ öffnen.
Unter „Deine Karte“ ausfüllen: „Name der Person“ („z. B. Maria Huber“), „Hashtag“ („z. B. #bäckereisonne“) und „Telefon (optional)“.
„Karte speichern“ antippen. Danach steht dort „Gespeichert ✓“.
Die Karte rechts anklicken — sie dreht sich um und zeigt den großen QR-Code.
Unter „AI to go — als Link & QR teilen“: „Link kopieren“, „QR als PNG“ oder „QR als SVG“ für die Druckerei.
Eigenes Wissen für eine Person: „Eigenen Bereich anlegen →“. Der neue Bereich erscheint in der Liste darunter, mit „Anlernen & bearbeiten →“, „Testen“ und „Link kopieren“.

Gut zu wissen

Der Link hat die Form aioos.ai/k/… und steht auch klein auf der Rückseite der Karte.
„Geteiltes Wissen“ heißt: dieselbe Karte, dasselbe Gehirn wie dein Hauptassistent. Was du unter „Anlernen“ beibringst, weiß auch die Karte — nichts wird kopiert, nichts läuft auseinander.
„Eigenen Bereich anlegen“ baut dagegen einen eigenen Assistenten für diese Person: eigenes Wissen, eigener QR-Code. Er belegt einen Betriebs-Platz.
Ein Name, ein Bereich. Ein zweiter Klick mit demselben Namen legt nichts Neues an, sondern zeigt auf den vorhandenen: „… hat schon einen eigenen Bereich — unten zum Bearbeiten öffnen.“
Das SVG ist die Datei für die Druckerei — sie bleibt in jeder Größe scharf. PNG genügt für Bildschirm und Social Media.
Die Karte bewegt sich mit der Maus und dreht sich beim Klick. Wer Bewegung ausgeschaltet hat oder ein Tablet benutzt, sieht sie ruhig — der QR-Code ist derselbe.

Wenn etwas nicht klappt

„Der QR-Code erscheint, sobald dein Assistent gespeichert ist.“: Der Betrieb ist noch nicht gespeichert. Einrichtung zu Ende gehen, dann ist der Code da.
„Der Teilen-Link wird geholt …“: Läuft. Einen Moment warten.
„Teilen ist gerade nicht möglich — …“: Der Grund steht im selben Satz. Dein Assistent und alles, was du eingerichtet hast, sind davon nicht betroffen.
„QR folgt nach dem Speichern“: Steht auf der Rückseite der Karte, solange es noch keinen Link gibt.
„… ist angelegt, aber der Teilen-Link fehlt noch“: Der eigene Bereich existiert, nur der Code fehlt. Seite später neu laden, dann holt er ihn nach. Der Hinweis bleibt bewusst stehen, bis das erledigt ist.
„Workspace-Limit erreicht — bitte Paket prüfen.“: Dein Tarif erlaubt keinen weiteren Assistenten. Unter „Nutzung“ nachsehen oder hello@aioos.ai fragen.
„Erst etwas ändern — dann lässt sich die Karte speichern.“: An der Karte hat sich nichts geändert, deshalb ist Speichern aus.

Open a real-time voice and text session with your AIOOS agent from your own website, app, or backend. The same agent you configured at aioos.ai/app — answering on your phone number and your website chatbot — becomes a session your software can start anywhere. Two doors in: drop the ready-made chatbot onto your site with two lines of HTML, or build your own experience on the Session API.

How it works

Exchange your agent key for a session token — one HTTPS call to POST /v1/session.
Connect using the returned token and server URL — one import, every modern browser (quickstart below). Your agent joins automatically; in voice sessions it greets first, in text-only sessions the greeting arrives with its first reply.
Talk or type. Voice flows as a normal audio track; text and live transcripts flow as small JSON messages on the same connection.

Your agent key

Every agent has one key of the form wk_…. You'll find it at aioos.ai/app → your workspace → Chatbot, inside the embed code (agent-id="wk_…").

The key is publishable — it is designed to appear in public web pages, like a Stripe publishable key. Abuse is bounded by rate limits, an optional origin allowlist, and your plan's minute pool. To restrict your key to specific website origins, or to rotate a key, contact hello@aioos.ai.

Add the chatbot to your website

The fastest integration — two lines of HTML, no build step. Paste this right before </body>:

<script src="https://aioos.ai/embed.js" async></script>
<aioos-widget agent-id="wk_YOUR_KEY"></aioos-widget>

Your console shows this snippet ready to copy — pre-filled with your key, brand color and position. The chatbot lives in an isolated frame: it can never collide with your site's styles or scripts, and the microphone permission is requested by the chatbot itself, separate from your page. Voice and text conversations here draw from the same minute pool as everything else.

Everything can be configured visually in your console; for hand-tuning, <aioos-widget> also accepts:

Attribute	Default	Meaning
`agent-id`	— required	Your agent key (`wk_…`).
`accent`	`#0084FF`	Brand color for launcher and chat.
`position`	`right`	Screen corner: `right` or `left`.
`theme`	`light`	`light` or `dark`.
`launcher`	`pill`	Closed state: `pill`, `icon` or `orb`.
`label`	"Fragen? Sprechen Sie mit uns"	Text on the launcher pill.
`name`	`AIOOS`	Assistant name in the chat header.
`greeting`	"Hallo! Wie kann ich Ihnen helfen?"	First message visitors see.
`radius`	`24`	Corner rounding, 10–30.
`offset-x` / `offset-y`	`18`	Distance from the corner, in px.

See it live: demo · dark demo.

Quickstart — voice in the browser

For your own UI instead of the ready-made chatbot. Sessions speak an open realtime standard — the livekit-client package in the first line is the only dependency; there is nothing AIOOS-specific to install.

Run this from a click handler (browsers require a user gesture for microphone and audio playback):

import { Room, RoomEvent } from "https://esm.sh/livekit-client@2"; // or: npm i livekit-client

// 1 — exchange your key for a session token
const s = 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 }),
}).then(r => r.json());

// 2 — connect; the agent joins automatically and speaks first
const room = new Room();
room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === "audio") document.body.appendChild(track.attach());
});
room.on(RoomEvent.DataReceived, (payload) => {
  const msg = JSON.parse(new TextDecoder().decode(payload));
  if (msg.type === "transcript") console.log(msg.role + ": " + msg.text);
});
await room.connect(s.server_url, s.token,
  s.ice_servers?.length ? { rtcConfig: { iceServers: s.ice_servers } } : undefined);

// 3 — open the microphone and talk
await room.localParticipant.setMicrophoneEnabled(true);

End the session with room.disconnect(). Each session needs a fresh token — call /v1/session again to reconnect; never cache tokens.

Text without voice

Connect exactly as above, skip the microphone, and send text turns as data messages. The agent's replies arrive as transcript messages (the greeting is prefixed to the first reply):

function sendText(text) {
  room.localParticipant.publishData(
    new TextEncoder().encode(JSON.stringify({ type: "user_text", text })),
    { reliable: true }
  );
}
sendText("What are your opening hours?");

Reference — POST /v1/session

POST https://aioos.ai/v1/session · Content-Type: application/json · no authentication header — the key travels in the body. CORS is open; the endpoint is callable from browsers and servers alike.

Request

Field	Type	Description
`key`	string, required	Your agent key (`wk_…`).
`page_origin`	string, optional	Send `location.origin` from browsers. Required to pass when your key carries an origin allowlist; server-side callers may omit it (works while the key has no allowlist).

Response · 200

Field	Type	Description
`token`	string	Single-use, single-session credential. Do not cache or share.
`server_url`	string	WebSocket URL to connect to. Always use the returned value — never hardcode it.
`ice_servers`	array \| null	Short-lived TURN relay credentials for restrictive corporate networks. Pass to the SDK as shown; when `null`, connect without them.

Errors

Errors return JSON {"error": "…"}:

Status	`error`	Meaning
400	`bad_body` / `bad_key`	Malformed JSON, or the key is not a valid `wk_…` string.
402	`no_minutes`	Your plan's minute pool is empty. Upgrade or top up at aioos.ai/app.
403	`unknown_key`	The key does not exist or was revoked.
403	`origin_not_allowed`	Your key restricts origins and `page_origin` is not on the list.
429	`rate_limited`	Limits: 10 requests/min per IP, 30 requests/min per key. Back off and retry.
5xx	`internal` …	Transient server problem. Retry with backoff.

Realtime protocol

Inside a connected session:

Channel	Direction	What
Audio track (yours)	you → agent	Publish your microphone (`setMicrophoneEnabled(true)`). Optional — text-only sessions skip it.
Audio track (agent)	agent → you	The agent's voice. Auto-subscribed; attach it to play. In voice sessions the agent greets first on join.
Data messages	both	UTF-8 JSON, reliable delivery. Shapes below.

Data messages

Direction	Shape	Meaning
you → agent	`{"type":"user_text","text":"…"}`	One text turn, exactly like speaking a sentence.
agent → you	`{"type":"transcript","role":"user"\|"agent","text":"…"}`	Live transcript of both sides, for voice and text turns alike.
agent → you	`{"type":"media","items":[…]}`	Optional rich content (e.g. image cards). Safe to ignore.

Forward compatibility: ignore data messages with unknown type values, and unknown fields in known messages — new ones may be added without notice. The shapes documented here are stable.

Troubleshooting

The microphone prompt never appears — start the session from a click handler (browsers require a user gesture) and serve your page over HTTPS (localhost also works).
You hear nothing — attach the agent's audio track after that same user gesture; browsers block autoplay without one.
400 bad_key / 403 unknown_key — re-copy the key from your console; it starts with wk_ and travels in the JSON body, not in a header.
403 origin_not_allowed — your key carries an origin allowlist: send page_origin: location.origin and make sure that origin (including your dev origin) is on the list.
402 no_minutes — the minute pool is empty; top up at aioos.ai/app.
Connections fail on a corporate network — pass ice_servers exactly as returned; the session then falls back to a relay that traverses strict firewalls.
The session ends when the phone locks or the tab sleeps — expected: tokens are single-session. Mint a fresh token and reconnect when the user returns.
Reconnect loops — never reuse a token; every room.connect needs its own /v1/session call (limits: see the reference).

Sessions, metering & limits

Sessions are metered per minute, from connect to disconnect, against your plan's single minute pool — shared with your phone number and website chatbot.
When the pool is empty, /v1/session answers 402 no_minutes and no session opens; a running session is capped at your remaining balance.
Idle sessions are closed by the server. Reconnect with a fresh token when the user returns.
Plans and remaining minutes: aioos.ai/app.

Mobile apps & backends

The session token is platform-neutral. Native apps for iOS (Swift), Android (Kotlin), Flutter and React Native connect with the LiveKit-compatible client for their platform (SDK reference) — call POST /v1/session, connect, and the same voice + data protocol applies. That's the whole integration.

Backends automate the same way: Node and Python clients open text-only sessions — send user_text, read transcript — with no browser involved. If your key carries an origin allowlist, tell us about planned native or server-side callers so we configure it to match.

Inside a mobile app (WebView)

The fastest way to put the assistant in your own iOS or Android app is a WebView pointed at a page that carries the chatbot snippet above — the same one the Widget Studio generates. Everything is the normal web embed; the one thing a WebView needs beyond a browser is the microphone. The widget iframe is created with allow="microphone; autoplay", so the host app must (1) hold the OS microphone permission and (2) grant the WebView's capture request.

What is verified vs. not: the snippet, the iframe's allow="microphone; autoplay" and the POST /v1/session token flow are verified in our test browser. The native host settings below are taken from Apple's and Google's platform docs and were not run in our environment (ungetestet) — use them as a starting point and test on a real device.

iOS — WKWebView (ungetestet): add NSMicrophoneUsageDescription to Info.plist; set configuration.allowsInlineMediaPlayback = true and configuration.mediaTypesRequiringUserActionForPlayback = [] on the WKWebViewConfiguration. iOS prompts for the microphone on first capture.

Android — WebView (ungetestet): declare <uses-permission android:name="android.permission.RECORD_AUDIO"/> in the manifest; in a WebChromeClient override onPermissionRequest(request) and call request.grant(request.getResources()) for RESOURCE_AUDIO_CAPTURE; and set webView.settings.mediaPlaybackRequiresUserGesture = false so the assistant can speak without a tap.

Keep the key server-side if you prefer. An agent key (wk_…) is publishable and safe in app code, but if you would rather not ship it, mint the session on your backend with POST /v1/session and hand token and server_url to the app — then load a WebView page that connects with those instead of the embed snippet.

Versioning

This page is the v1 contract. Additive changes (new response fields, new data-message types) may land without notice — ignore what you don't know. Breaking changes get a new version and an announcement.

Starten Sie eine Sprach- und Text-Session mit Ihrem AIOOS-Agenten in Echtzeit — aus Ihrer eigenen Website, App oder Ihrem Backend. Derselbe Agent, den Sie unter aioos.ai/app konfiguriert haben — erreichbar über Ihre Telefonnummer und Ihren Website-Chatbot — wird zu einer Session, die Ihre Software überall öffnen kann. Zwei Wege: den fertigen Chatbot mit zwei Zeilen HTML einbauen, oder ein eigenes Erlebnis auf der Session API bauen.

So funktioniert es

Tauschen Sie Ihren Agent-Key gegen ein Session-Token — ein HTTPS-Aufruf an POST /v1/session.
Verbinden Sie sich mit dem erhaltenen Token und der Server-URL — ein Import, jeder moderne Browser (Quickstart unten). Ihr Agent tritt automatisch bei; in Sprach-Sessions begrüßt er zuerst, in reinen Text-Sessions kommt die Begrüßung mit seiner ersten Antwort.
Sprechen oder tippen. Sprache läuft als normale Audiospur; Text und Live-Transkripte laufen als kleine JSON-Nachrichten über dieselbe Verbindung.

Ihr Agent-Key

Jeder Agent hat genau einen Key der Form wk_…. Sie finden ihn unter aioos.ai/app → Ihr Workspace → Chatbot, im Embed-Code (agent-id="wk_…").

Der Key ist veröffentlichbar — er ist dafür gemacht, in öffentlichen Webseiten zu stehen, wie ein Stripe Publishable Key. Missbrauch wird durch Rate-Limits, eine optionale Origin-Allowlist und das Minutenkontingent Ihres Tarifs begrenzt. Um Ihren Key auf bestimmte Website-Origins einzuschränken oder zu rotieren, schreiben Sie an hello@aioos.ai.

Den Chatbot in Ihre Website einbauen

Die schnellste Integration — zwei Zeilen HTML, kein Build-Schritt. Direkt vor </body> einfügen:

<script src="https://aioos.ai/embed.js" async></script>
<aioos-widget agent-id="wk_IHR_KEY"></aioos-widget>

Ihre Konsole zeigt dieses Snippet fertig zum Kopieren — vorausgefüllt mit Ihrem Key, Ihrer Markenfarbe und Position. Der Chatbot lebt in einem isolierten Frame: Er kann nie mit den Styles oder Skripten Ihrer Seite kollidieren, und die Mikrofon-Berechtigung fragt der Chatbot selbst an — getrennt von Ihrer Seite. Sprach- und Text-Gespräche laufen hier über dasselbe Minutenkontingent wie alles andere.

Alles lässt sich visuell in der Konsole einstellen; zum Feinjustieren akzeptiert <aioos-widget> außerdem:

Attribut	Standard	Bedeutung
`agent-id`	— erforderlich	Ihr Agent-Key (`wk_…`).
`accent`	`#0084FF`	Markenfarbe für Launcher und Chat.
`position`	`right`	Bildschirmecke: `right` oder `left`.
`theme`	`light`	`light` oder `dark`.
`launcher`	`pill`	Geschlossener Zustand: `pill`, `icon` oder `orb`.
`label`	„Fragen? Sprechen Sie mit uns"	Text auf dem Launcher.
`name`	`AIOOS`	Name des Assistenten im Chat-Kopf.
`greeting`	„Hallo! Wie kann ich Ihnen helfen?"	Erste Nachricht für Besucher.
`radius`	`24`	Eckenrundung, 10–30.
`offset-x` / `offset-y`	`18`	Abstand zur Ecke, in px.

Live ansehen: Demo · dunkle Demo.

Quickstart — Sprache im Browser

Für Ihre eigene Oberfläche statt des fertigen Chatbots. Sessions sprechen einen offenen Echtzeit-Standard — das Paket livekit-client aus der ersten Zeile ist die einzige Abhängigkeit; es gibt nichts AIOOS-Spezifisches zu installieren.

Aus einem Click-Handler aufrufen (Browser verlangen eine Nutzergeste für Mikrofon und Audiowiedergabe):

import { Room, RoomEvent } from "https://esm.sh/livekit-client@2"; // oder: npm i livekit-client

// 1 — Key gegen Session-Token tauschen
const s = await fetch("https://aioos.ai/v1/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ key: "wk_IHR_KEY", page_origin: location.origin }),
}).then(r => r.json());

// 2 — verbinden; der Agent tritt automatisch bei und spricht zuerst
const room = new Room();
room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === "audio") document.body.appendChild(track.attach());
});
room.on(RoomEvent.DataReceived, (payload) => {
  const msg = JSON.parse(new TextDecoder().decode(payload));
  if (msg.type === "transcript") console.log(msg.role + ": " + msg.text);
});
await room.connect(s.server_url, s.token,
  s.ice_servers?.length ? { rtcConfig: { iceServers: s.ice_servers } } : undefined);

// 3 — Mikrofon öffnen und sprechen
await room.localParticipant.setMicrophoneEnabled(true);

Beenden Sie die Session mit room.disconnect(). Jede Session braucht ein frisches Token — rufen Sie /v1/session erneut auf; Tokens niemals zwischenspeichern.

Text ohne Sprache

Verbinden Sie sich genau wie oben, lassen Sie das Mikrofon weg und senden Sie Text-Turns als Datennachrichten. Die Antworten des Agenten kommen als transcript-Nachrichten (die Begrüßung wird der ersten Antwort vorangestellt):

function sendText(text) {
  room.localParticipant.publishData(
    new TextEncoder().encode(JSON.stringify({ type: "user_text", text })),
    { reliable: true }
  );
}
sendText("Wie sind Ihre Öffnungszeiten?");

Referenz — POST /v1/session

POST https://aioos.ai/v1/session · Content-Type: application/json · kein Authentifizierungs-Header — der Key steht im Body. CORS ist offen; der Endpunkt ist aus Browsern und von Servern aufrufbar.

Request

Feld	Typ	Beschreibung
`key`	string, erforderlich	Ihr Agent-Key (`wk_…`).
`page_origin`	string, optional	Aus Browsern `location.origin` senden. Erforderlich, sobald Ihr Key eine Origin-Allowlist trägt; serverseitige Aufrufer können es weglassen (funktioniert, solange der Key keine Allowlist hat).

Response · 200

Feld	Typ	Beschreibung
`token`	string	Einmaliges Credential für genau eine Session. Nicht zwischenspeichern, nicht teilen.
`server_url`	string	WebSocket-URL für die Verbindung. Immer den zurückgegebenen Wert verwenden — niemals hartkodieren.
`ice_servers`	array \| null	Kurzlebige TURN-Relay-Credentials für restriktive Firmennetzwerke. Wie gezeigt ans SDK übergeben; bei `null` ohne sie verbinden.

Fehler

Fehler kommen als JSON {"error": "…"}:

Status	`error`	Bedeutung
400	`bad_body` / `bad_key`	Fehlerhaftes JSON, oder der Key ist kein gültiger `wk_…`-String.
402	`no_minutes`	Das Minutenkontingent Ihres Tarifs ist aufgebraucht. Upgrade unter aioos.ai/app.
403	`unknown_key`	Der Key existiert nicht oder wurde widerrufen.
403	`origin_not_allowed`	Ihr Key beschränkt Origins und `page_origin` steht nicht auf der Liste.
429	`rate_limited`	Limits: 10 Requests/Min pro IP, 30 Requests/Min pro Key. Warten und erneut versuchen.
5xx	`internal` …	Vorübergehendes Serverproblem. Mit Backoff erneut versuchen.

Echtzeit-Protokoll

Innerhalb einer verbundenen Session:

Kanal	Richtung	Was
Audiospur (Ihre)	Sie → Agent	Mikrofon veröffentlichen (`setMicrophoneEnabled(true)`). Optional — reine Text-Sessions lassen es weg.
Audiospur (Agent)	Agent → Sie	Die Stimme des Agenten. Automatisch abonniert; zum Abspielen anhängen. In Sprach-Sessions begrüßt der Agent zuerst.
Datennachrichten	beide	UTF-8-JSON, zuverlässige Zustellung. Formen siehe unten.

Datennachrichten

Richtung	Form	Bedeutung
Sie → Agent	`{"type":"user_text","text":"…"}`	Ein Text-Turn, genau wie ein gesprochener Satz.
Agent → Sie	`{"type":"transcript","role":"user"\|"agent","text":"…"}`	Live-Transkript beider Seiten, bei Sprach- wie Text-Turns.
Agent → Sie	`{"type":"media","items":[…]}`	Optionale Rich-Inhalte (z. B. Bildkarten). Kann ignoriert werden.

Vorwärtskompatibilität: Ignorieren Sie Datennachrichten mit unbekannten type-Werten sowie unbekannte Felder in bekannten Nachrichten — neue können ohne Ankündigung dazukommen. Die hier dokumentierten Formen sind stabil.

Fehlersuche

Die Mikrofon-Abfrage erscheint nie — die Session aus einem Click-Handler starten (Browser verlangen eine Nutzergeste) und die Seite über HTTPS ausliefern (localhost geht auch).
Sie hören nichts — die Audiospur des Agenten nach derselben Nutzergeste anhängen; ohne Geste blockieren Browser die Wiedergabe.
400 bad_key / 403 unknown_key — den Key neu aus der Konsole kopieren; er beginnt mit wk_ und steht im JSON-Body, nicht im Header.
403 origin_not_allowed — Ihr Key trägt eine Origin-Allowlist: page_origin: location.origin mitsenden und sicherstellen, dass diese Origin (auch die Entwicklungs-Origin) auf der Liste steht.
402 no_minutes — das Minutenkontingent ist leer; aufladen unter aioos.ai/app.
Verbindung scheitert im Firmennetzwerk — ice_servers genau wie erhalten übergeben; die Session weicht dann auf ein Relay aus, das strenge Firewalls durchquert.
Die Session endet, wenn das Handy sperrt oder der Tab schläft — erwartet: Tokens gelten für genau eine Session. Beim Zurückkehren frisches Token holen und neu verbinden.
Reconnect-Schleifen — Tokens nie wiederverwenden; jedes room.connect braucht seinen eigenen /v1/session-Aufruf (Limits: siehe Referenz).

Sessions, Abrechnung & Limits

Sessions werden pro Minute abgerechnet, von Verbindungsaufbau bis Trennung, gegen das eine Minutenkontingent Ihres Tarifs — gemeinsam mit Ihrer Telefonnummer und Ihrem Website-Chatbot.
Ist das Kontingent leer, antwortet /v1/session mit 402 no_minutes und es öffnet keine Session; eine laufende Session ist auf Ihr Restguthaben begrenzt.
Inaktive Sessions werden serverseitig beendet. Mit frischem Token neu verbinden, wenn der Nutzer zurückkehrt.
Tarife und Restminuten: aioos.ai/app.

Mobile Apps & Backends

Das Session-Token ist plattformneutral. Native Apps für iOS (Swift), Android (Kotlin), Flutter und React Native verbinden sich mit dem LiveKit-kompatiblen Client ihrer Plattform (SDK-Referenz) — POST /v1/session aufrufen, verbinden, dasselbe Sprach- und Datenprotokoll gilt. Das ist die ganze Integration.

Backends automatisieren genauso: Node- und Python-Clients öffnen reine Text-Sessions — user_text senden, transcript lesen — ganz ohne Browser. Trägt Ihr Key eine Origin-Allowlist, nennen Sie uns geplante native oder serverseitige Aufrufer, damit wir sie passend konfigurieren.

In einer mobilen App (WebView)

Der schnellste Weg, den Assistenten in Ihre eigene iOS- oder Android-App zu bringen, ist eine WebView, die auf eine Seite mit dem obigen Chatbot-Snippet zeigt — genau das, was das Widget-Studio erzeugt. Alles ist der normale Web-Einbau; das Einzige, was eine WebView über einen Browser hinaus braucht, ist das Mikrofon. Das Widget-iframe wird mit allow="microphone; autoplay" erstellt, daher muss die Host-App (1) die Mikrofon-Berechtigung des Systems besitzen und (2) die Aufnahme-Anfrage der WebView freigeben.

Was geprüft ist und was nicht: das Snippet, das allow="microphone; autoplay" des iframes und der POST /v1/session-Ablauf sind in unserem Test-Browser verifiziert. Die nativen Host-Einstellungen unten stammen aus der Plattform-Doku von Apple und Google und wurden nicht in unserer Umgebung ausgeführt (ungetestet) — nehmen Sie sie als Ausgangspunkt und testen Sie auf einem echten Gerät.

iOS — WKWebView (ungetestet): NSMicrophoneUsageDescription in die Info.plist aufnehmen; an der WKWebViewConfiguration allowsInlineMediaPlayback = true und mediaTypesRequiringUserActionForPlayback = [] setzen. iOS fragt beim ersten Zugriff nach dem Mikrofon.

Android — WebView (ungetestet): <uses-permission android:name="android.permission.RECORD_AUDIO"/> im Manifest deklarieren; in einem WebChromeClient onPermissionRequest(request) überschreiben und für RESOURCE_AUDIO_CAPTURE request.grant(request.getResources()) aufrufen; und webView.settings.mediaPlaybackRequiresUserGesture = false setzen, damit der Assistent ohne Tippen sprechen darf.

Key bei Bedarf serverseitig halten. Ein Agent-Key (wk_…) ist veröffentlichbar und im App-Code unbedenklich; wollen Sie ihn dennoch nicht ausliefern, erzeugen Sie die Session im Backend mit POST /v1/session und reichen token und server_url an die App — laden Sie dann eine WebView-Seite, die sich damit statt mit dem Snippet verbindet.

Versionierung

Diese Seite ist der v1-Vertrag. Additive Änderungen (neue Response-Felder, neue Nachrichtentypen) können ohne Ankündigung erscheinen — ignorieren Sie Unbekanntes. Breaking Changes bekommen eine neue Version und eine Ankündigung.