Flash stagingAsk for an invitation
All docs pages

The owner inbox in your dashboard

Profile owners answer their visitors from your own owner dashboard. The dashboard shows the inbox in a frame served by the platform, and signs the owner in with a user token, so owners sign in once, on your site, and never register with the platform (contracts/inbox-host.md).

The inbox shows the conversations of the profiles this owner has on your site, and nothing of any other site.

Before you start

  • Your profile sync names each profile's owner by their user ID on your site (guide 2, step 1). The inbox finds an owner's profiles by that ID.
  • You have a token signing key uploaded (guide 1) and can sign tokens (guide 4).
  • Your owner dashboard has an origin of its own, such as https://pro.spaguide.example, which serves no public pages and no third-party scripts. Its inbox token route lives there and nowhere else (The inbox token says why).
  • Add that origin to the site's allowed origins, on the console's Sites page. From go-live, the platform serves the inbox only into frames on the site's allowed origins; until then any page can frame it (Security). Adding your origin now means nothing changes for you then.
  • Allow the inbox address in frame-src in your dashboard's Content Security Policy.

Framing the inbox

The frame's address names the protocol version, your site and your dashboard's origin:

{inboxUrl}?v=1&site={publishable key}&host={your dashboard's origin}

{inboxUrl} is the inbox address of the platform you integrate with, which the platform team gives you. Add &theme=dark, or &theme=system to follow the owner's system setting, when your dashboard is dark; light is the default.

The dashboard page then answers the inbox's question "who is signed in?". Signing in has the whole page script, short enough to copy. It creates the frame. Each time the inbox sends token, the script asks your inbox token route for a token and answers signin with it, or signout when nobody is signed in or the route fails. The rules the script keeps are listed under it: answer every token within the inbox's 10 seconds, tell the inbox when the user changes, and accept and post messages only at the inbox's origin.

Give the frame a fixed height, such as the window's height below your header. The inbox scrolls inside it and works from 320 pixels wide (Layout and keyboard).

The inbox token

Your owner dashboard's server signs the inbox token, on a route of its own, /messenger/inbox-token. It works as the visitor's route in guide 4 does, with three differences:

  • aud is messenger-inbox. A widget token does not open the inbox, and an inbox token does not sign anyone in to the messenger.
  • sub is the owner's user ID: exactly the owner your profile sync sends for their profiles. name is optional, the name the inbox shows for the owner.
  • The route answers only on the dashboard's own origin, and only for a user signed in to the dashboard.

An inbox token opens the owner's conversations, and the browser cannot tell two pages of one origin apart. If your public profile pages shared the dashboard's origin, any script on any of them, such as an analytics tag or an advertisement, could ask the route for the token of an owner who is browsing there (Signing in, "The dashboard's own origin"). Checking the request cannot help: Sec-Fetch-Site: same-origin, the Origin header and a SameSite cookie look the same for every page of the origin. Only an origin that serves nothing but the dashboard makes "a page of this origin" mean "the dashboard".

The other route rules are the visitor route's: POST only, no CORS headers, a session cookie with SameSite=Lax or SameSite=Strict, the token as plain text, and never in a log. token-server.ts runs the two routes as two servers, each answering only its own.

Which profiles an owner sees

An owner's session reaches the profiles on your site whose owner is the token's sub (No profile on this site):

  • The platform looks them up on every request, so when your sync gives a profile a new owner, it leaves the previous owner's inbox at once and appears in the new owner's, with its past conversations.
  • A session reaches at most 100 profiles. An owner with more sees the 100 whose ids come first in byte order.
  • When no profile on your site names the user as its owner, the inbox does not open. It tells them that your site decides who owns a profile. If an owner sees this by mistake, check that your sync sends their user ID as owner exactly as your token sends it as sub.

What owners can do there

In the inbox, an owner can:

  • read and answer their visitors, as themselves;
  • take a conversation over from the AI assistant, and hand it back;
  • say whether they are available, and set working hours, outside which the AI assistant replies;
  • switch the AI assistant off or on for their own profile;
  • give the AI assistant instructions of their own. These add to your site's playbook and can only narrow it, never widen it (guide 6).

Not in this version: an unread count for your dashboard's own badge, opening one conversation from a link, and browser notifications.

Next: the AI playbook, sync health and going live.