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:

from surge import Surge

surge = Surge()

response = surge.users.create_token(user_id="{user_id}")
token = response.token

import Surge from "@surgeapi/node";

const surge = new Surge();

const response = await surge.users.createToken("{user_id}");
const token = response.token;

require "surge_api"

surge = SurgeAPI::Client.new

response = surge.users.create_token("{user_id}")
token = response.token

client = Surge.Client.new(System.get_env("SURGE_API_KEY"))

# create_token/3 requires an empty params map and returns the JWT directly
{:ok, token} = Surge.Users.create_token(client, "{user_id}", %{})

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

Each component is embedded as an iframe served from embed.surge.app, with the token passed as a query parameter:

<iframe
  src="https://embed.surge.app/conversations?token={USER_JWT}"
></iframe>

See the component-specific pages for each component’s URL, parameters, and events.

Rotating signed tokens

Because signed tokens are short-lived they may expire while users are still interacting with the embedded UI components authenticated with the expiring tokens. Connections will remain authenticated after their token has expired, but any reconnects will trigger re-authentication. We recommend rotating tokens just before they expire to ensure your components will continue to work.

Token expiring warning

When an embedded UI component is authenticated with a token that is about to expire, it will emit an event warning of the pending expiration. This event will have the the type “token_expiring”:

{
  "source": "surge_inbox",
  "type": "token_expiring",
  "data": {
    "seconds_remaining": 15
  }
}

Updating a component’s token

Re-rendering the iframe with a new token in the URL could cause the component to lose necessary state, so embedded components also support an “update_token” message back into the iframe.

{
  "type": "update_token",
  "data": {
    "token": "eyJhbGciOiJFZERTQSIsImtpZCI6InNnbl8wMWp5bWowZ3AwZjNidmJmMmpyazRoYnd0ayIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NTA4ODkyMDgsInN1YiI6InVzcl8wMWp5bWdkZnJwZWMyYXNjNW0wejNhNmZyOSJ9.zKayo3EDrUm1Hw8URrofuYwajgyTu6dH2H0FEuRExprP1IV66FHa8wC3SfdzV7sR3AjDGAwkuAXztScq6rBnBw"
  }
}

Example

Here’s an example snippet of some JavaScript in your app for rotating tokens before they expire. In this example refreshSurgeToken is a made-up function that makes a request to your server for a new token.

const surgeInbox = document.querySelector('iframe#surge-inbox');

window.addEventListener('message', async ({ data, origin }) => {
  if (origin == 'https://embed.surge.app') {
    const { type } = data;

    if (type == 'token_expiring') {
      const { token } = await refreshSurgeToken();
      const message = { type: 'update_token', data: { token }};
      surgeInbox.contentWindow.postMessage(message, origin);
    }
  }
});

Next steps

Working with Users

How Users are provisioned and attributed to messages.

Inbox component

URL parameters and events for the conversation list.

Conversation component

Mounting a single thread inside your own page.

Unread Count component

Badge integration for navigation chrome.

Get started

Register your business

Sending messages

Receiving messages & webhooks

Phone numbers

Verifications

Channels roadmap