Bots teilen

Für Entwickler, die einen Client mit OpenBot verbinden oder den Server erweitern. Die Beispiele brauchen die auf dieser Seite genannten Rechte. Beginne mit dem Entwicklerhandbuch.

Du kannst einen Bot mit Personen außerhalb deiner Organisation teilen. Das ist so, wie du ein Member zu einer Organisation hinzufügst. Du lädst eine Person per E-Mail ein, oder du erstellst einen Einladungslink. Dein Client kann den Link als QR-Code zeigen. Die Person nimmt die Einladung an. Danach nutzt sie den Bot in ihrer eigenen Organisation.

Wort	Bedeutung
Geteilter Bot	Dein Bot, den andere Personen nutzen.
Einladungslink	Eine Einladung ohne E-Mail. Jeder, der ihr Geheimnis hat, kann sie annehmen, bis du sie zurückziehst.
Bot-Mitglied	Eine Person, die eine Einladung angenommen hat und den Bot nutzt.
Verknüpfter Bot	Der Bot, den ein Bot-Mitglied in seiner eigenen Organisation bekommt. Er nutzt deinen Bot.

Personen einladen

Du brauchst share für den Bot. Members können ihre eigenen Bots teilen. Administratoren können auch die gemeinsamen Bots der Organisation teilen. Du kannst nur einen obersten Bot teilen: einen, der einem Member oder der Organisation gehört und der nicht archiviert ist.

Um eine Person einzuladen, sende ihre E-Mail. Die Einladung gilt 7 Tage, wie eine Einladung in die Organisation:

curl -X POST -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@example.com"}' \
  https://api.example.com/v1/bots/$BOT/invitations

Um einen Einladungslink zu erstellen, lass email weg. Viele Personen können denselben Link nutzen.

curl -X POST -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/join"}' \
  https://api.example.com/v1/bots/$BOT/invitations

Feld	Bedeutung
`email`	Die E-Mail der Person. Lass sie weg, um einen Link zu erstellen.
`expiresAt`	Wann ein Link endet (Millisekunden seit 1970). Ohne diesen Wert endet ein Link nie.
`path`	Ein Pfad auf dem öffentlichen Origin, wo dein Client Einladungslinks öffnet.

{
  "invitation": {
    "id": "inv_51c2…",
    "bot": "bot_7d2c",
    "email": null,
    "prefix": "obai_Xk2pQ9aB",
    "path": "/join",
    "status": "pending",
    "invitedBy": "u_123",
    "createdAt": "2026-10-23T08:00:00.000Z",
    "expiresAt": null
  },
  "secret": "obai_Xk2pQ9aB…",
  "url": "https://api.example.com/join#obai_Xk2pQ9aB…"
}

url ist der öffentliche Origin, dann path, dann # und das Geheimnis. Ein Browser sendet den Teil nach # nie an einen Server. So kommt das Geheimnis nie in ein Server-Log. url ist null, wenn es keinen path gibt. Zeige url als QR-Code, oder baue deine eigene Adresse aus secret.

GET /v1/bots/:botId/invitations/:invitationId/secret gibt dir das Geheimnis und die url eines Links noch einmal, zum Beispiel um den QR-Code noch einmal zu drucken. OpenBot speichert das Geheimnis verschlüsselt. Es speichert auch einen Hash, um den Link zu finden.

GET /v1/bots/:botId/invitations listet die Einladungen auf. DELETE /v1/bots/:botId/invitations/:invitationId zieht eine Einladung zurück. Danach kann niemand sie annehmen. Die Personen, die sie vorher angenommen haben, bleiben Bot-Mitglieder.

Eine Einladung annehmen

Die eingeladene Person meldet sich an. Sie nutzt das Session-Cookie oder ihr eigenes User-Token.

Eine Einladung per E-Mail erscheint in GET /v1/invitations, mit bot. Nimm sie mit ihrer ID an.
Für einen Link sende sein Geheimnis.

curl -X POST -H "Authorization: Bearer $THEIR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret":"obai_Xk2pQ9aB…","organization":"org_9a1f"}' \
  https://api.example.com/v1/bot-invitations/accept

organization ist die Organisation, in der die Person den Bot nutzt. Sie muss ein aktives Member davon sein. Sie kann es weglassen, wenn sie nur eine Organisation hat oder wenn sie ein User-Token nutzt. Die Antwort ist ihr neuer verknüpfter Bot.

Wenn die Person den Bot schon nutzt, bekommt sie ihren verknüpften Bot zurück. Um eine Einladung per E-Mail abzulehnen, nutze POST /v1/invitations/:invitationId/decline.

Einen geteilten Bot nutzen

Der verknüpfte Bot ist ein Bot des Bot-Mitglieds, in seiner eigenen Organisation. Er hat source. Das nennt deinen Bot:

{
  "id": "bot_e40b",
  "owner": { "_tag": "Member", "userId": "u_456" },
  "name": "Guide",
  "source": { "organizationId": "org_3c7e", "bot": "bot_7d2c" }
}

Das Bot-Mitglied arbeitet damit wie mit seinen eigenen Bots:

Es spricht mit ihm in seinem eigenen Chat, in seiner eigenen Organisation, und kann ihn zu seinem Standard-Bot machen.
Der Bot arbeitet mit den Berechtigungen des Bot-Mitglieds, mit seinen verbundenen Apps und mit seinen anderen Bots. Er kann den Bots des Bot-Mitglieds Arbeit geben.
Seine Requests gehen an das Bot-Mitglied. Dessen Entscheidungen, Grants und Rules gelten nur in seiner Organisation. Deine gelten nur in deiner.
Die Organisation des Bot-Mitglieds bezahlt die Models. Wenn dein Bot ein Model nennt, das seine Organisation nicht hat, nutzt sein Chat es nicht. Er nutzt das Standard-Model des Servers nur in einer Simulation wie der Entwicklung. Im Produktivbetrieb gibt es kein Standard-Model. Der Empfänger braucht ein verfügbares Model.
Du siehst nie seine Chats.

Name, Rolle, Anweisungen und Model kommen immer von deinem Bot. Wenn du sie änderst, ändert sich auch jeder verknüpfte Bot. Ein Bot-Mitglied kann sie nicht ändern. Ein Bot-Mitglied kann planApproval ändern.

Der Bot hat einen Memory-Pool, in deiner Organisation. Was er in der Organisation eines Bot-Mitglieds lernt, ist für dieses Bot-Mitglied, in dieser Organisation. Niemand liest das Memory über eine andere Person: du nicht, und andere Bot-Mitglieder auch nicht. Du kannst mit einem Purge entfernen, was ein Bot-Mitglied hinterlassen hat, ohne es zu lesen. Nur du verwaltest den Memory-Bot.

Bot-Mitglieder verwalten

Anfrage	Was sie tut
`GET /v1/bots/:botId/members`	Listet die Bot-Mitglieder auf: ihre User-ID und Organisation und ihren verknüpften Bot.
`DELETE /v1/bots/:botId/members/:userId`	Entfernt eine Person. Ihr verknüpfter Bot hört sofort auf zu arbeiten.

Beide brauchen share auf dem Bot. Ein verknüpfter Bot hört auch auf, wenn du deinen Bot archivierst.

Ein Bot-Mitglied geht, wenn es seinen verknüpften Bot archiviert.

Berechtigungen

Aktion auf `Bot`	Damit kannst du
`share`	Personen einladen, einen Bot zu nutzen, und seine Bot-Mitglieder verwalten.

Siehe Berechtigungen.

Fehler

Status	Fehler	Wann
`400`	`BotInvalid`	Du kannst den Bot nicht teilen, oder ein Bot-Mitglied will ändern, was der geteilte Bot ist.
`400`	`InvitationInvalid`	Die Einladung ist benutzt, zurückgezogen oder abgelaufen, oder du musst die Organisation nennen.
`404`	`InvitationNotFound`	Es gibt keine Einladung mit dieser ID oder diesem Geheimnis für dich.
`404`	`BotNotFound`	Es gibt keinen Bot mit dieser ID, den du lesen darfst, oder ein verknüpfter Bot arbeitet nicht mehr.
`503`	`BotStorageUnavailable`	OpenBot erreicht seine Datenbank nicht.