Embedding a surface

Status: Current | Last reviewed: 2026-08-05

Once an agent has a surface configuration, you embed it in your own web page or app so customers can talk to the agent. The standard embed path uses a short-lived signed iframe session token minted by your backend with a TrueServe API token. You do not need to create an embed client for the normal server-to-server embed flow.

Mint iframe session tokens from your backend

  1. Create or choose a TrueServe API token that can manage agents.
  2. Keep that API token on your backend only.
  3. Have your backend call AI Manager's embed minting endpoint for each page load or session:
  4. agent id
  5. audience origin, such as https://your-site.example
  6. optional existing conversation id
  7. optional surface configuration id
  8. Return the short-lived embed token, or the iframe URL returned by the endpoint, to your web page.

The browser receives only the short-lived embed token. Never put the TrueServe API token in browser code.

The embed token is still required. It authenticates the iframe session, limits which parent origin can embed and message the surface, and is exchanged by surface-app for an httpOnly session cookie. What is not required for the standard flow is an embed client registration.

Add the surface to your page

The embed loads the surface in an iframe and connects it to the agent. The developer SDK guide shows the minimal iframe snippet, the postMessage protocol between your page and the surface, and the host capabilities you can wire up. Hand that section to whoever owns the host page.

Note: If the embedded surface renders with default branding instead of yours, confirm the agent has the right surface configuration assigned and that the embed token was minted for the exact parent origin hosting the iframe.

Embed the demo phone dynamically

An external app that wants the iPhone-style test-call experience can list published agents, collect caller/session options in its own UI, and ask AI Manager for a single-use emulator iframe URL. Give that backend token only the Read Agents and Run Emulator scopes. The dynamic flow supports WebRTC, outbound or simulated-inbound presentation, auto-connect, caller identity, session variables, and an STT language override. It does not let the app choose SIP destinations or send arbitrary headers.

Request a new emulator session whenever the host creates or replaces the iframe; do not save iframeUrl as reusable content. The iframe handles duplicate React development mounts itself, while reuse from another browser or page session remains blocked.

Custom web apps should load the hosted <trueserve-phone> element. It renders the phone through the transparent /embed/phone route, scales it to the host container, removes the iframe scrollbars and external phone shadow, and exposes call controls as browser methods. Your app gives the element a same-origin backend session URL; that backend calls AI Manager and keeps the tenant API token out of browser code.

The phone embedding guide contains the backend route, web component markup, events, and sizing options. The full request and response contract is in the AI Manager integration API.

The external page has one AI Manager iframe. Incoming and outgoing call screens, Messages, Safari, and trusted multimodal components all render inside that phone document. When a demo SMS arrives, tap its notification, open the message, and tap the link to launch Safari. The call stays connected in the Dynamic Island while you use the component. Safari does not add a surface-app iframe.

A stored embed configuration can also let the viewer dial any number and run the call through Live Translation, instead of always calling one fixed destination. See Dial & Translate embeds.

Where to configure embedding

Everything for embedding lives in one External Clients table under Settings → Integrations → Embedding. Each row is an external system that embeds TrueServe, of one of two types:

The New Client button opens a short wizard that asks whether the external system has a backend and creates the right type. Every row is editable, and the Active switch is a kill-switch: turning a client off blocks new sessions and withdraws its domain trust within about a minute.

Use the row-level Generate snippet action (the code icon) to produce a ready-to-paste HTML snippet tailored to that client — the App flavor calls your backend for a token; the Site flavor is a complete self-contained PKCE page.

Local development (localhost, 127.0.0.1) and your deployment's own domain are always allowed automatically, so you don't need to add them.

Which type should I pick?

Prefer App whenever a backend exists — API-token minting from a trusted server is simpler and doesn't require visitors to have AI Manager accounts. Choose Site only for backend-less pages used by people who already sign in to AI Manager, such as internal portals and demos.

Embedding in a CRM

You don't build any of this yourself for Salesforce or ServiceNow. Both have ready-made drag-and-drop components that wrap the same embed flow, mint the token server-side for you, and explain their own errors on screen. See Salesforce components.

You still register the CRM's domain as an App client here, so the browser is allowed to frame the surface.

See also