Embed the assistant

The embedded assistant is the WPOS agent running inside your product, in an iframe, branded as yours. Your operators drive it as a manager, and your end customers drive it as a client. The browser never holds your API key: you mint a short-lived, site-scoped session token on your server and load it in the frame. This needs the embed scope.

How it fits together

Mint a session on your server

Call POST /sites/:siteId/embed-session with your partner key. You get a one-hour token and a ready-to-frame URL. The site must belong to you.

curl -X POST https://api.wpcursor.com/api/partner/v1/sites/site_.../embed-session \
  -H "X-Partner-Key: $WPOS_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "client", "displayName": "Jordan" }'

{
  "success": true,
  "role": "client",
  "token": "...",
  "expiresIn": 3600,
  "url": "https://api.wpcursor.com/embed/chat?token=..."
}

Frame the URL

Drop the returned url into an iframe in your app.

<iframe
  src="https://api.wpcursor.com/embed/chat?token=..."
  style="width:100%;height:600px;border:0"
  title="Website Assistant">
</iframe>

The embed surface sets a frame-ancestors policy that allows your configured origins, so it loads inside your app and nowhere else.

Your customer chats

The assistant loads with your branding and runs the agent on the token’s site. Each message is a build job under the hood, bounded by the same credits and caps as the Build jobs API. When the token expires after an hour, mint another.

Roles

Role	For	Framing
`manager`	Your operators	Full agent access, presented as an operator tool.
`client`	Your end customers	The same execution, presented as “request a change”.

The role is stamped into the session token and travels with every job the session runs, so your reporting can tell operator work from customer work.

Branding

The embedded assistant renders with the site’s white-label branding: agency name, logo, and accent color, falling back to your partner defaults. Set them per site through Branding, or set partner-wide defaults with WPOS. No WPOS name appears to your customer.

Security model

Mint session tokens on your server, never in the browser, and never ship your partner key to the client. The embed token is deliberately narrow: it is site-scoped, expires in an hour, and only works on the embed surface. It cannot read your other sites or your account.

The token is an embed-only credential. It cannot be used as a partner key or a site token.
Everything the frame can do is scoped to the one site the token was minted for.
Configure which origins may frame the assistant with WPOS when you set up your embed integration.

Branding

Set the name, logo, and color your customers see.

Build jobs

The API the embedded assistant runs on.

Overview

Get started

Guides

Reference

Embed the assistant

How it fits together

Roles

Branding

Security model

Next

Branding

Build jobs

​How it fits together

​Roles

​Branding

​Security model

​Next

Branding

Build jobs

How it fits together

Roles

Branding

Security model

Next