Platform API

Platform API

GlassChat Platform API is the paid integration surface for customer apps, automations, and embedded chat. Your backend gets scoped API keys; your frontend loads only the hosted GlassChat embed bundle.

Base URL


https://glasschat.app/platform/v1

Legacy Agentry-compatible routes still exist during migration, but new integrations should use /platform/v1.

If you still call /partner/v1, migrate those requests now. The legacy alias returns deprecation headers and can be disabled after customer migration.

Authentication

Server-to-server calls use a generated Platform API key:


Authorization: Bearer gcp_...

Keys are shown once, stored hashed, and scoped. Use the smallest scope that matches the job.

Common scopes:

  • platform:provision — create teams and issue embed sessions.
  • platform:messages:send — send through scoped data-plane routes.
  • platform:webhooks:write — manage webhook endpoints.
  • platform:usage:read — read usage and delivery history.

Embed GlassChat

Load the hosted bundle. Do not copy the app source into your product.


<script src="https://glasschat.app/embed/glasschat.embed.js"></script>
<div id="glasschat"></div>
<script>
  GlassChat.mount("#glasschat", {
    appId: "app_xxx",
    token: "short_lived_embed_token",
    baseUrl: "https://glasschat.app",
    layout: "embedded",
    themeSource: "host",
    themeName: "glasschat"
  })
</script>

Allowed origins are configured per app, so browser embeds only run where you expect them to run.

Auth modes

The embed supports two identity models via authMode:

authMode: "partner" (backend-provisioned, default when a token is passed). Your backend provisions the user + group and mints a short-lived embed token (/teams/:teamId/members/:externalId/embed-session); you pass it as token. The embed logs in as that managed account and drops the user straight into the provisioned group — no login screen. Use this when you own identity.


GlassChat.mount("#glasschat", { appId, baseUrl, token, authMode: "partner" })

authMode: "user" (self-service, default when no token). Your users sign in or sign up with their own GlassChat accounts. No embed token, and nothing is auto-created — if the user isn't signed in, the embed shows GlassChat's own login/signup; once signed in they land in their own chat list and control their own conversations.


GlassChat.mount("#glasschat", { appId, baseUrl, authMode: "user" })
// no token, no backend embed-session call

If you omit both token and authMode, the embed defaults to "user" (self-service). Passing a token implies "partner".

Layout & theming

layout controls how the app is presented inside your page:

  • "embedded" (default) — a compact, single-pane widget that fills its

    • container. Best for a side panel or a card in your app.

  • "fullscreen" — the full mobile-style app, taking over its container.
  • "desktop" — the multi-pane desktop shell (left rail + conversation pane).

    • Requires a wide container (≥ 1024px); below that it falls back to the single-pane layout automatically.


GlassChat.mount("#glasschat", { appId, baseUrl, authMode: "user", layout: "desktop" })

Theming:

  • End users can switch light/dark from Settings → Appearance inside the

    • embed (self-service mode); the choice is saved to their account.

  • themeSource: "host" makes an embedded widget follow your page's

    • data-theme/CSS tokens instead. Use theme: { … } to pass explicit color tokens, or themeName to select a named palette.

Provision a workspace

Create a customer team:


POST /platform/v1/teams
Authorization: Bearer gcp_...
Content-Type: application/json

{
  "externalTeamId": "acme-support",
  "tenantId": "acme",
  "name": "Acme Support"
}

Then issue a short-lived embed session for one of that team's members:


POST /platform/v1/teams/:teamId/members/:externalId/embed-session

The response includes a scoped token and the groupId the embed can access.

Webhooks

Webhook destinations must be HTTPS public URLs. Localhost and private-network targets are rejected.

Every webhook delivery is signed:


x-glasschat-event-id: evt_...
x-glasschat-event-type: chat.created
x-glasschat-delivery-id: whd_...
x-glasschat-timestamp: <unix seconds>
x-glasschat-signature: t=<unix seconds>,v1=<hmac_sha256(timestamp.body)>

Supported events:

  • message.created
  • message.updated
  • reaction.created
  • chat.created
  • member.joined
  • member.left
  • call.completed

Deliveries retry on timeout, 408, 429, and 5xx. Delivery history exposes status codes and sanitized errors, not message content or webhook response bodies.

Billing and limits

Each app has a plan, billing status, and optional monthly limits.

  • active and trialing allow API usage.
  • past_due and suspended block generated Platform API keys.
  • null monthly limit means unlimited.
  • 0 monthly limit means zero usage.

When a quota is exhausted the API returns platform_quota_exceeded with the metric, limit, and current usage.

Each app also has an optional per-minute request cap (rateLimitPerMinute). null means unlimited and 0 blocks all traffic. When the cap is exceeded the API returns 429 platform_rate_limited with the limit. Rate limiting is checked before the monthly quota, so bursts are rejected quickly.

E2EE boundary

GlassChat preserves its encryption boundary. In end-to-end encrypted chats, the server can route metadata and ciphertext but cannot expose decrypted message content through Platform API responses or webhooks.

For automation that requires plaintext, use a clearly marked business automation chat where users understand the server-side automation boundary.