Surge home page
SupportDashboard
Surge

Embeddable UI Components

Surge provides ready-to-use UI components you can embed directly into your web application. They connect to Surge's messaging backend and give your users an inbox, conversation view, and unread count — without building any of that yourself.

Components are served from embed.surge.app.

Available components

  • Inbox — a list of all conversations for the current user, sortable and filterable
  • Conversation — a single threaded conversation with send capability
  • Unread count — a badge showing how many unread conversations the user has
  • Phone (dialpad) — a voice dialer for outbound calls (voice-enabled accounts)

Authentication

Each component mount requires a signed JWT. The JWT identifies which Surge account and user the component is showing data for.

Publishable tokens are deprecated. If you're currently using a publishable token, migrate to JWT authentication. See Deprecation Notices.

Two ways to get a JWT

Option 1 — Use the token endpoint (simpler)

Call the user token endpoint from your server, then pass the resulting token to the component:

curl -X POST https://api.surge.app/users/USER_ID/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
{
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6InNnbl8wMWouLi4ifQ..."
}

The token is short-lived. Generate a fresh one on each page load or use a refresh mechanism.

Option 2 — Create and sign your own JWT

If you need more control over JWT claims (expiration, scopes), generate a signing key in the dashboard (Settings → Signing Keys) and sign your own JWTs. The key is an Ed25519 key pair — your private key stays on your server, and Surge uses the public key to verify tokens.

import jwt  # PyJWT
from datetime import datetime, timedelta

payload = {
    "sub": surge_user_id,
    "iat": datetime.utcnow(),
    "exp": datetime.utcnow() + timedelta(hours=1),
}

token = jwt.encode(payload, private_key, algorithm="EdDSA", headers={"kid": key_id})

Mounting a component

Pass the token to the component via JavaScript. The exact mounting API depends on your framework — refer to the component-specific pages for details.

<script src="https://embed.surge.app/v1/embed.js"></script>
<div id="surge-inbox"></div>
<script>
  SurgeEmbed.mount("inbox", {
    target: document.getElementById("surge-inbox"),
    token: "eyJhbGci...",
  });
</script>

Next steps