> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Kundenkonten verbinden

> Isolierte Endnutzer anlegen und ihre Social-Media-Konten über gehostetes OAuth verbinden

Jeder Kunde in deiner Anwendung entspricht einem isolierten Endnutzer in Social media studio. Social-Verbindungen und Beiträge sind auf diesen Endnutzer beschränkt, während dein Partner-Schlüssel für das gesamte Entwicklerprojekt gilt.

## Einen Endnutzer per Upsert anlegen

Verwende als `externalId` eine unveränderliche Kennung aus deiner eigenen Datenbank. Ein erneuter Aufruf von `upsert` mit demselben Wert aktualisiert den Kunden und aktiviert ihn wieder, falls er zuvor deaktiviert war.

```ts theme={null}
const endUser = await soMe.endUsers.upsert({
  externalId: "customer_123",
  displayName: "Acme Ltd",
  metadata: {
    plan: "pro",
    region: "eu",
  },
});
```

Speichere `endUser.id` zusammen mit deinem Kundendatensatz. SDK-Methoden verwenden diese Social-media-studio-ID, nicht `externalId`.

```ts theme={null}
const customers = await soMe.endUsers.list();
const customer = await soMe.endUsers.get(endUser.id);
```

So verhinderst du, dass ein Kunde die eingebettete Plattform weiter nutzt:

```ts theme={null}
await soMe.endUsers.disable(endUser.id);
```

Beim Deaktivieren wird der isolierte Workspace des Kunden deaktiviert. Ein späterer `upsert` mit derselben `externalId` aktiviert ihn wieder.

## Eine Connect-Session erstellen

```ts theme={null}
const session = await soMe.connectSessions.create({
  endUserId: endUser.id,
  platform: "THREADS",
  returnUrl: "https://app.example.com/settings/social",
});
```

Connect-Sessions laufen nach 10 Minuten ab und können nur für den angegebenen Endnutzer verwendet werden. Leite den Kunden auf die zurückgegebene `connectUrl` weiter:

```ts theme={null}
return Response.redirect(session.connectUrl!);
```

> [!WARNING]
>
> Der Origin der `returnUrl` muss exakt mit einem Origin übereinstimmen, der in deinem Partnerprojekt registriert ist, einschließlich Schema, Hostname und Port. Pfade und Query-Parameter dürfen abweichen. Return-URLs mit eingebetteten Zugangsdaten werden abgelehnt.

## Den Abschluss behandeln

Sobald der gehostete Ablauf einen Endzustand erreicht, sieht der Kunde eine Zurück-Schaltfläche. Das Ziel erhält diese Query-Parameter:

| Parameter | Wert |
| - | - |
| `social_connect` | `success` oder `failed` |
| `end_user_id` | Die Endnutzer-ID in Social media studio |
| `connection_id` | Die neue Verbindungs-ID bei Erfolg |

Betrachte Browser-Parameter als Benachrichtigung, nicht als Beweis für den Erfolg. Bestätige das Ergebnis über dein Backend mit der ID der Connect-Session, die du erstellt hast:

```ts theme={null}
const result = await soMe.connectSessions.get(session.id);

if (result.status === "completed" && result.connectionId) {
  // Persist result.connectionId for this customer.
}
```

Die gehostete Seite sendet außerdem eine `postMessage` an ihr Opener-Fenster, wenn sie in einem Popup verwendet wird:

```ts theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://api.so-me.studio") return;
  if (event.data?.type !== "some.social_connect.completed") return;

  // Ask your backend to verify the connect session.
});
```

## Konten auflisten und trennen

```ts theme={null}
const connections = await soMe.connections.list(endUser.id);

await soMe.connections.disconnect(endUser.id, connections[0].id);
```

Übergib immer die ID des Endnutzers, dem die Verbindung gehört. Social media studio lehnt Versuche ab, eine Verbindung eines anderen Kunden zu lesen oder zu trennen.

## Session-Zustände

| Status | Bedeutung |
| - | - |
| `created` | Bereit, vom Kunden geöffnet zu werden |
| `started` | Der gehostete OAuth-Ablauf hat begonnen |
| `completed` | Konto verbunden; `connectionId` ist verfügbar |
| `failed` | Die Autorisierung wurde verweigert oder konnte nicht abgeschlossen werden |
| `expired` | Das 10-Minuten-Fenster der Session ist abgelaufen |

Erstelle nach `failed` oder `expired` eine neue Session; Sessions in einem Endzustand lassen sich nicht neu starten.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.