Drive the chat from your code.

Signature

embeddedChat.setUser({"name": "John", "profile_image": "https://..."})

Parameters

• name — display name shown in chat. required
• profile_image — avatar URL. optional
• email — visitor's email; used for engagement analytics. optional

Call this before embeddedChat.init().

<script>
  window.embeddedChatAsyncInit = function() {
    embeddedChat.setUser({
      name: "Jane Doe",
      profile_image: "https://example.com/avatars/jane.png"
    });
    embeddedChat.init("YOUR_PROJECT_ID");
  };
</script>

Signature

embeddedChat.setRoom("room-id", "Optional pretty name")

Parameters

• room_id — unique identifier. Determines which message stream the user joins.
• name — display label for the room. optional

After init, use embeddedChat.changeRoom("other-id", "Optional pretty name") to switch.

<script>
  window.embeddedChatAsyncInit = function() {
    embeddedChat.setRoom("product-42", "Sneakers Talk");
    embeddedChat.init("YOUR_PROJECT_ID");
  };
</script>

Signature

embeddedChat.openChat()
embeddedChat.closeChat()

Safe to call right after init(): if the chat is still loading it opens as soon as it is ready.

<button onclick="embeddedChat.openChat()">Talk to us</button>

The contract

Call setUser before init(). These three keys are the entire payload — any other field is ignored.

• name — display name shown in chat. required
• email — the identity key: same email means the same person across visits, devices and pages. strongly recommended
• profile_image — avatar URL. optional

Send email if you want identity to stick. Without it, every page load mints a brand-new visitor — a returning reader loses their history and their own messages stop being recognised as theirs.

What you get

• Visitors never type a name or pick a sign-in method.
• @mentions resolve to a stable person rather than a free-typed nickname.
• Names and avatars match the ones on your own site.

<script>
  // currentUser is whatever your server printed into the page.
  window.embeddedChatAsyncInit = function() {
    if (currentUser) {
      embeddedChat.setUser({
        name: currentUser.name,
        email: currentUser.email,
        profile_image: currentUser.avatarUrl
      });
    }
    embeddedChat.init("YOUR_PROJECT_ID");
  };
</script>

<script>
  window.embeddedChatAsyncInit = function() {
    fetch("/members/api/member/")
      .then(function(r) { return r.json(); })
      .catch(function() { return null; })
      .then(function(member) {
        if (member && member.email) {
          embeddedChat.setUser({
            name: member.name || member.email.split("@")[0],
            email: member.email,
            profile_image: member.avatar_image || ""
          });
        }
        embeddedChat.init("YOUR_PROJECT_ID");
      });
  };
</script>

Get your signing key

Admin → Install → Pre-authenticated visitors → Generate key. It is per project, and it never leaves your server — anyone holding it can sign in as any of your users. Rotate it from the same place; every token already issued stops working the moment you do.

Payload

{
  "user_id": "your-internal-user-42",   // required — your id, your namespace
  "username": "Jane Doe",
  "email": "jane@example.com",
  "image_url": "https://example.com/avatars/jane.png",
  "exp": 1730000000                     // required — unix seconds, max 24h out
}

What we enforce

• HS256 only. No alg negotiation, so none is not an option.
• exp is mandatory and capped 24h ahead. A token that never expires is a password, and we won't accept one.
• user_id is scoped to your project. Another customer signing the same id is a different person, always.
• is_admin is ignored. Moderator standing comes from your admin account and nothing you sign can grant it.
• A token that fails any of the above is treated as anonymous — never as an unsigned setUser.

# Sign once per page load, for the user your session already identified.
import jwt, time

token = jwt.encode({
    "user_id": str(request.user.id),
    "username": request.user.full_name,
    "email": request.user.email,
    "image_url": request.user.avatar_url,
    "exp": int(time.time()) + 3600,
}, EMBEDDED_CHAT_SIGNING_KEY, algorithm="HS256")

<script>
  window.embeddedChatAsyncInit = function() {
    embeddedChat.setUser({ token: "<the token your server just signed>" });
    embeddedChat.init("YOUR_PROJECT_ID");
  };
</script>

Configure

Panel → Integrations → Webhooks (Pro plan). Add a URL, pick events, optionally provide your own secret (or we'll generate one once and show it to you a single time). Pause, edit or delete a webhook there too, and see how its last delivery went.

Events

• message_posted — every new chat message.
• mention_received — fires alongside message_posted when the message contains @usernames.
• message_pinned — admin pins a message to the top of a room.

Headers

• Content-Type: application/json
• X-EC-Event — the event name (matches the body's event field).
• X-EC-Signature — sha256=<hex>. HMAC-SHA256 over the raw body bytes, keyed with your shared secret.

Behavior

• Best-effort delivery from a background queue, one attempt per event: a failed delivery isn't retried, so design your receiver to be idempotent and tolerant of gaps.
• 3-second timeout per delivery. Slow receivers get marked last_status=null and the chat moves on.
• No redirect-following. A 3xx response is treated as an error so a hostile receiver can't 302 us into SSRF.
• Public hosts only. URLs pointing at private/loopback IP literals are rejected at save time.

{
  "event": "message_posted",
  "data": {
    "comment_id": 12345,
    "room_id": 42,
    "channel": "general",
    "username": "alice",
    "message": "hi @bob, see this →",
    "is_admin": false,
    "mentions": ["bob"]
  }
}

import hmac, hashlib

def verify(raw_body, header_sig, secret):
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_sig)

Connect

• Server: https://www.embedded-chat.com/mcp/ (Streamable HTTP).
• Sign in with OAuth. The first time, your client opens an Embedded Chat page where you sign in and click Allow. Nothing to copy.
• Or use a token if your client only takes a header: Panel → Integrations → AI agents (MCP) → Create token, sent as Authorization: Bearer <token>. It is shown once.
• Every connected app and token is listed in Integrations, where you can revoke it. Changing or resetting your password revokes them all.

claude mcp add --transport http embedded-chat https://www.embedded-chat.com/mcp/
# then run /mcp in Claude Code to sign in

{
  "mcpServers": {
    "embedded-chat": {
      "url": "https://www.embedded-chat.com/mcp/",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Tools

Reads run without asking. Changes are marked destructive, so your AI client asks you first; those marked preview also answer with a preview and act only when the agent repeats the call with confirm.

Prompts: daily_check, catch_up_on_chats, set_up_chat.

Behavior

• Same rules as the dashboard. Every change goes through the panel's own checks, so a value the panel would refuse, or a feature your plan doesn't include, comes back as an error that says why.
• Owner only. A connection acts as the account owner on its chat; teammates can't connect apps or create tokens.
• It asks before acting. Anything your visitors would see and anything destructive answers with a preview first, and only happens with an explicit confirm. Cancelling also needs the monthly price repeated back.
• No agent moves money. No tool charges a card, refunds or pays out: a plan change comes back as a link the owner opens and approves, and card details and the tips payout account stay in the panel.
• 120 calls a minute per account, and up to 60 image uploads an hour.