Embedding the chat

For the developer at a company that puts its product’s chat inside its own app with Zest. The Embed page (Live › Embed) has your exact snippet, the embed secret and a live preview.

The chat is the same one people get in ChatGPT and Claude: the same intents for their role, the same views, read-back before every change, undo. Every call shows on Activity. People see your product’s name, logo and colors, never Zest.

Install

One line, before </body>, on any page:

<script src="https://zestmcp.app/embed/v1.js" data-zest="<product>" data-key="<public key>" async></script>

data-zest is the product’s short name and data-key its public key, both on the Embed page. The public key is safe in a page: it says which chat to load, nothing more. That line draws a round button in the corner; the chat opens in a panel above it. Everything else (launcher, position, greeting, the suggested intents) comes from the Embed page until you set it in code.

data-site overrides where the chat loads from; it defaults to the address the script came from.

Identity

Your app already knows who is signed in. It tells Zest with an embed token: a short-lived JWT your backend mints and the page hands over. Never put the embed secret, an API key or a password in the page.

Sign it with HS256 and the embed secret from the Embed page (Identity › Rotate). The secret is shown once; keep it on your server, as ZEST_EMBED_SECRET. Rotating it makes every token signed with the old one stop working.

Then load the script without async and pass the token:

<script src="https://zestmcp.app/embed/v1.js" data-zest="<product>" data-key="<public key>"></script>
<script>
  Zest.init({
    identity: '<embed token>',          // minted by your backend, see below
    onLink: (url) => router.push(url),  // open links inside your app
  });
</script>

When the token is about to expire, or someone else signs in, mint a new one and call Zest.setIdentity(token). Each person keeps their own conversation.

Minting the token

import jwt from 'jsonwebtoken';
const token = jwt.sign(
  { sub: user.email, name: user.name, role: 'Front desk' },
  process.env.ZEST_EMBED_SECRET, { algorithm: 'HS256', expiresIn: '1h' },
);

import jwt, os, time
token = jwt.encode(
    {"sub": user.email, "name": user.name, "role": "Front desk", "exp": int(time.time()) + 3600},
    os.environ["ZEST_EMBED_SECRET"], algorithm="HS256",
)

use Firebase\JWT\JWT;
$token = JWT::encode(
    ['sub' => $user->email, 'name' => $user->name, 'role' => 'Front desk', 'exp' => time() + 3600],
    getenv('ZEST_EMBED_SECRET'), 'HS256'
);

require 'jwt'
token = JWT.encode(
  { sub: user.email, name: user.name, role: 'Front desk', exp: Time.now.to_i + 3600 },
  ENV['ZEST_EMBED_SECRET'], 'HS256'
)

token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
	"sub": user.Email, "name": user.Name, "role": "Front desk",
	"exp": time.Now().Add(time.Hour).Unix(),
}).SignedString([]byte(os.Getenv("ZEST_EMBED_SECRET")))
if err != nil { return err }

Config

Every key of Zest.init is optional. What you leave out comes from the script tag, then from the Embed page.

On a phone the panel fills the screen and closes with its ✕.

Methods and events

Zest.on('link', (url) => analytics.track('chat_link', { url }));
document.querySelector('#help').addEventListener('click', () => Zest.say('Who is on my schedule today?'));

Theming

The chat takes your product’s name, logo and three colors from Branding, and the look of the views inside it (Paper, Product or Dark, plus your adjustments) from Views. Change them there and every chat, embedded or in an AI app, follows. theme and accent in init change the chat around the views for one page, for instance a dark panel on a dark app.

Allowed origins

On the Embed page, list the sites that may show the chat, one per line, like https://app.yourproduct.com. A chat on any other site answers that it is not allowed there. Empty allows any site: fine for a demo, set it before going live.

If your pages send a Content Security Policy, allow the Zest site in script-src (the script) and frame-src (the chat).

When the person is not signed in

• No token, sample data. On a demo, email and name are enough: the first time, the person is added to the company in the first role.
• No token, real data. With an anonymous role on the Embed page, the person uses the chat as that role, reads only. Without one, the chat answers “Sign in to {product} to use this here.” Mint a token and call Zest.setIdentity.
• A bad or expired token. The chat says what is wrong under the input, and nothing is sent. Mint a new token and call Zest.setIdentity.
• Offline, or Zest cannot be reached. The chat says it did not go through and keeps what they typed.

Versioning

v1 is stable: what this page describes keeps working. Breaking changes go to v2 at a new address, never in place. New config keys and events may be added to v1; unknown ones are ignored.