Connect Customer Accounts - Social media studio

Each customer in your application maps to an isolated Social media studio end user. Social connections and posts are scoped to that end user, while your partner key is scoped to the entire developer project.

Upsert an end user

Use an immutable identifier from your own database as externalId. Calling upsert again with the same value updates the customer and re-enables it if it was previously disabled.

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

Store endUser.id with your customer record. SDK methods use this Social media studio ID, not externalId.

const customers = await soMe.endUsers.list();
const customer = await soMe.endUsers.get(endUser.id);

To stop a customer from using the embedded platform:

await soMe.endUsers.disable(endUser.id);

Disabling deactivates the customer’s isolated workspace. A later upsert with the same externalId reactivates it.

Create a connect session

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

Connect sessions expire after 10 minutes and can be used only for the specified end user. Redirect the customer to the returned connectUrl:

return Response.redirect(session.connectUrl!);

The returnUrl origin must exactly match an origin registered on your partner project, including scheme, hostname, and port. Paths and query parameters may vary. Credentials embedded in a return URL are rejected.

Handle completion

After the hosted flow reaches a terminal state, the customer sees a return button. The destination receives these query parameters:

Parameter	Value
`social_connect`	`success` or `failed`
`end_user_id`	The Social media studio end-user ID
`connection_id`	The new connection ID when successful

Treat browser parameters as a notification, not proof of success. Confirm the result from your backend using the connect-session ID you created:

const result = await soMe.connectSessions.get(session.id);

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

The hosted page also sends a postMessage to its opener when used in a popup:

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.
});

List and disconnect accounts

const connections = await soMe.connections.list(endUser.id);

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

Always pass the end-user ID that owns the connection. Social media studio rejects attempts to read or disconnect a connection belonging to a different customer.

Session states

Status	Meaning
`created`	Ready for the customer to open
`started`	The hosted OAuth flow has begun
`completed`	Account connected; `connectionId` is available
`failed`	Authorization was denied or could not be completed
`expired`	The 10-minute session window elapsed

Create a new session after failed or expired; terminal sessions cannot be restarted.

​Upsert an end user

​Create a connect session

​Handle completion

​List and disconnect accounts

​Session states

Upsert an end user

Create a connect session

Handle completion

List and disconnect accounts

Session states