Skip to main content
Embedding puts Tilde inside your product. Your users see spaces, chat with agents, and connect their own accounts on your pages, signed in with your application’s login, not with Tilde. Two SDK packages do the work: The browser only talks to your server. Your key never reaches the browser, and the browser can never choose who it is.

Your users

Your server describes the signed-in user with three fields:
  • id: a stable identifier, unique in your application (1 to 256 characters).
  • groups: optional group names, for example the customer the user belongs to.
  • attributes: optional key and value strings, for example { customer: "acme", plan: "pro" }.
The same id is the user everywhere: in spaces it is the principal ext:<id>, and in agent chats it is the user’s conversation identity. A user who chats with an agent and opens a space is one person in both. In a project’s policies, groups appear as ext:<group> and attributes as tags:
Handlers read the same attributes from ctx.principal.attrs, so a read can scope its rows to the user’s customer. Many customers can share one environment: the policies keep them apart.

Set up embedding CLOUD

1

Allow your site to frame spaces

Open the project in Ontology, select the Embed tab, and add your site’s origins under Allowed origins, for example https://app.example.com. Changes apply to the next space load.
2

Create an embed key

Under Embed keys, select Create key. Name it, then choose the environments, spaces, and agents it may open. Copy the key: it is shown once. Store it as a server secret, for example TILDE_EMBED_KEY.
3

Mount the server handler

Install @trytilde/embed-server and route /api/tilde/* to it. See Embed spaces.
4

Mount components in your pages

Install @trytilde/embed and mount spaces, chat, and connection setup.
An embed key opens only what it names. Revoke a key on the Embed tab and it stops working at the next request.

Editions

Spaces and embed keys are Tilde Cloud features. With Tilde OSS, embed agent chats with @trytilde/chat-proxy and each agent’s chat key. See Embed chat.