Embeddable Support Widget

Support Station provides two ways to embed support functionality on your website: a floating Chat Widget and a Full-Page Form via iframe. Both options automatically create tickets in your dashboard when customers submit requests.

The chat widget appears as a floating button in the corner of your website. When clicked, it opens a modal where visitors can submit support requests.

Quick Start

Add this code before your closing </body> tag:

Chat widget embed code

<script>
  window.SupportStation = {
    orgSlug: 'your-org-slug'
  };
</script>
<script async src="https://assets.supportstation.io/widget.js"></script>

Replace your-org-slug with your organization's slug from Settings > Organization in your dashboard.

Configuration Options

Full configuration

<script>
  window.SupportStation = {
    orgSlug: 'your-org-slug',

    // Pre-filled customer data (optional)
    email: '[email protected]',
    name: 'John Doe',
    externalUserId: 'user_123',
    externalOrganizationId: 'org_456',
    externalOrganizationName: 'Acme Corp',

    // HMAC signature for secure prefill (optional)
    signature: 'hmac_signature_here',

    // User context for AI personalization (optional)
    userContext: `Account: Acme Corp (Pro Plan)
User Role: Admin
Member Since: January 2024
Features: API Access, SSO enabled`,

    // Callbacks (optional)
    onSubmit: function(data) {
      console.log('Ticket created:', data.ticketNumber);
    }
  };
</script>
<script async src="https://assets.supportstation.io/widget.js"></script>

Name
orgSlug
Type
string
Description
Your organization's unique slug. Find this in Settings > Organization in your dashboard.
Name
email
Type
string
Description
Customer's email address. When provided, the email field is pre-filled and hidden.
Name
name
Type
string
Description
Customer's display name. Attached to the ticket for easy identification.
Name
externalUserId
Type
string
Description
Your system's user ID. Links the customer to your internal records.
Name
externalOrganizationId
Type
string
Description
Your system's organization/company ID. Links the customer to their company in your system.
Name
externalOrganizationName
Type
string
Description
Your system's organization/company name. Displayed in the customer details.
Name
signature
Type
string
Description
HMAC-SHA256 signature for secure identity verification. Required if identity verification is enabled.
Name
userContext
Type
string
Description
Contextual information about the user (max 5000 characters). Passed to the AI agent to personalize responses. Include account info, plan details, user role, or other relevant context.
Name
onSubmit
Type
function
Description
Callback function called when a ticket is successfully created. Receives { ticketNumber: string }.

JavaScript API

Control the widget programmatically:

Widget API

// Open the widget
window.SupportStationWidget.open();

// Close the widget
window.SupportStationWidget.close();

// Toggle open/closed
window.SupportStationWidget.toggle();

// Remove the widget
window.SupportStationWidget.destroy();

Updating User Data (SPAs)

For single-page applications where user state changes after the widget loads, use setUser to update the customer identity and context:

setUser API

window.SupportStation.setUser({
  email: '[email protected]',
  name: 'John Doe',
  externalUserId: 'user_123',
  externalOrganizationId: 'org_456',
  externalOrganizationName: 'Acme Corp',
  signature: 'hmac_signature',
  userContext: `Account: Acme Corp (Pro Plan)
User Role: Admin
Member Since: January 2024`
});

Name
email
Type
string
Description
Customer's email address.
Name
name
Type
string
Description
Customer's display name.
Name
externalUserId
Type
string
Description
Your system's user ID for linking.
Name
externalOrganizationId
Type
string
Description
Your system's organization/company ID.
Name
externalOrganizationName
Type
string
Description
Your system's organization/company name.
Name
signature
Type
string
Description
HMAC-SHA256 signature for identity verification. Generate a new signature server-side when user data changes.
Name
userContext
Type
string
Description
Contextual information about the user (max 5000 characters). Passed to the AI agent to personalize responses.

When updating user data with setUser, you must provide a new HMAC signature if identity verification is enabled. The signature should be generated on your server using the same method as the initial embed.

Customization

Configure the widget appearance in your Dashboard > Integrations > Widget:

Primary Color: Main color for button and header
Welcome Message: Greeting shown when widget opens
Button Label: Optional text next to the button
Quick Links: Add links to help docs, status page, etc.

Full-Page Embed (iframe)

For a full-page support form, use the iframe embed. This works well for dedicated support pages.

iframe embed code

<iframe
  src="https://supportstation.io/embed/your-org-slug"
  style="border: none; width: 100%; height: 600px;"
  title="Support Form"
></iframe>

Pre-filled Data with iframe

Add URL parameters to pre-fill customer information:

Pre-filled iframe

<iframe
  src="https://supportstation.io/embed/[email protected]&name=John+Doe&externalUserId=user_123&externalOrganizationId=org_456&externalOrganizationName=Acme+Corp"
  style="border: none; width: 100%; height: 600px;"
  title="Support Form"
></iframe>

Name
email
Type
string
Description
Customer's email address. Pre-fills and hides the email field.
Name
name
Type
string
Description
Customer's display name.
Name
externalUserId
Type
string
Description
Your system's user ID for linking.
Name
externalOrganizationId
Type
string
Description
Your system's organization/company ID.
Name
externalOrganizationName
Type
string
Description
Your system's organization/company name.
Name
signature
Type
string
Description
HMAC-SHA256 signature (required if identity verification is enabled).

Secure Customer Prefill (HMAC)

To securely pre-fill customer data and prevent impersonation, enable identity verification in your dashboard and sign requests with HMAC.

How Identity Verification Works

When identity verification is enabled, Support Station validates the HMAC signature at ticket submission time. The signature must be present in your widget configuration when the customer submits a ticket—not just when the widget loads.

Each ticket is assigned one of these verification statuses:

Status	Meaning
Verified	Signature provided and validated successfully. The customer's identity is confirmed.
Unverified	Identity verification is enabled but no signature was provided. The customer data may have been entered manually or your integration isn't passing the signature correctly.
Failed	A signature was provided but validation failed. This could indicate tampering or a misconfigured signature.
None	Identity verification is not enabled for your organization.

Common Integration Mistake: Make sure the signature is included in your window.SupportStation configuration object. If you only pass the signature to other endpoints (like activity tracking) but not in the widget config, tickets will be marked as Unverified. The signature must be present when the customer submits a ticket.

Enable Identity Verification

Go to Dashboard > Integrations
Under "Support Form", click Enable Identity Verification
Save your secret key securely (it's only shown once)

Generate Signatures

Generate the signature on your server, never in client-side code. The signature format is HMAC-SHA256(email:externalUserId, secretKey).

Generate HMAC Signature

const crypto = require('crypto');

function generateSignature(email, externalUserId, secretKey) {
  const payload = `${email}:${externalUserId || ''}`;
  return crypto
    .createHmac('sha256', secretKey)
    .update(payload)
    .digest('hex');
}

Using Signed Prefill

Chat Widget:

<script>
  window.SupportStation = {
    orgSlug: 'your-org-slug',
    email: '[email protected]',
    name: 'John Doe',
    externalUserId: 'user_123',
    externalOrganizationId: 'org_456',
    externalOrganizationName: 'Acme Corp',
    signature: 'YOUR_HMAC_SIGNATURE'
  };
</script>
<script async src="https://assets.supportstation.io/widget.js"></script>

iframe Embed:

<iframe
  src="https://supportstation.io/embed/[email protected]&name=John+Doe&externalUserId=user_123&externalOrganizationId=org_456&externalOrganizationName=Acme+Corp&signature=YOUR_HMAC_SIGNATURE"
  style="border: none; width: 100%; height: 600px;"
  title="Support Form"
></iframe>

Ticket Creation Flow

When a customer submits through either embed option:

A new ticket is created with status OPEN and channel WIDGET
If the customer email doesn't exist, a new customer record is created
If using tags, the ticket can be auto-routed to the appropriate team
You receive a notification in your dashboard (and via email/Slack if configured)
The customer sees a confirmation with their ticket number

Security

Both embed options are designed with security in mind:

Rate Limiting: Submissions are limited to 5 per IP per 15 minutes per organization
HMAC Verification: Optional signed prefill prevents customer impersonation
iframe Isolation: The widget runs in an isolated iframe/context
CSP Compatible: Works with Content Security Policies

React Integration

React component

import { useEffect } from 'react';

export function SupportWidget({
  orgSlug,
  email,
  name,
  externalUserId,
  externalOrganizationId,
  externalOrganizationName,
  signature,
  userContext
}) {
  useEffect(() => {
    // Set config
    window.SupportStation = {
      orgSlug,
      email,
      name,
      externalUserId,
      externalOrganizationId,
      externalOrganizationName,
      signature,
      userContext,
    };

    // Load the widget script
    const script = document.createElement('script');
    script.src = 'https://assets.supportstation.io/widget.js';
    script.async = true;
    document.body.appendChild(script);

    return () => {
      // Cleanup
      if (window.SupportStationWidget) {
        window.SupportStationWidget.destroy();
      }
      document.body.removeChild(script);
    };
  }, [orgSlug, email, name, externalUserId, externalOrganizationId, externalOrganizationName, signature, userContext]);

  return null;
}

// Usage
<SupportWidget
  orgSlug="your-org-slug"
  email={user?.email}
  name={user?.name}
  externalUserId={user?.id}
  externalOrganizationId={user?.organizationId}
  externalOrganizationName={user?.organizationName}
  signature={user?.supportSignature} // Generated server-side
  userContext={`Account: ${user?.organization?.name} (${user?.plan})
Role: ${user?.role}
Member Since: ${user?.createdAt}`}
/>

Troubleshooting Identity Verification

Tickets are marked "Unverified" even though I'm passing a signature

This usually means the signature is not being passed at ticket submission time. Check the following:

Verify the signature is in window.SupportStation: The signature must be set in the initial configuration object, not just sent to a separate API.

// ✅ Correct - signature included in config
window.SupportStation = {
  orgSlug: 'your-org-slug',
  email: '[email protected]',
  externalUserId: 'user_123',
  signature: 'your_hmac_signature'  // Required!
};

For SPAs using setUser: If you call setUser after the widget loads, you must include the signature there as well:

// ✅ Correct - signature included when updating user
window.SupportStation.setUser({
  email: '[email protected]',
  externalUserId: 'user_123',
  externalOrganizationId: 'org_456',
  externalOrganizationName: 'Acme Corp',
  signature: 'your_hmac_signature',  // Required!
  userContext: 'Plan: Pro, Role: Admin'
});

React/dynamic integrations: Ensure the signature prop is being passed to the component:

<SupportWidget
  orgSlug="your-org-slug"
  email={user.email}
  externalUserId={user.id}
  signature={generateSignature(user.email, user.id)}  // Don't forget this!
/>

Tickets are marked "Failed"

A "Failed" status means a signature was provided but didn't match. Check:

Payload format: The payload must be exactly email:externalUserId (or email: if no externalUserId)
Secret key: Verify you're using the correct secret key from your dashboard
No extra whitespace: Ensure there's no trailing/leading whitespace in the email or externalUserId
Encoding: The signature should be a lowercase hex string (64 characters for SHA-256)

Debugging signature generation

Use this to verify your signature matches what Support Station expects:

// Generate and log for debugging (server-side only!)
const crypto = require('crypto');

const email = '[email protected]';
const externalUserId = 'user_123';
const secretKey = 'your_secret_key';

const payload = `${email}:${externalUserId}`;
const signature = crypto.createHmac('sha256', secretKey).update(payload).digest('hex');

console.log('Payload:', payload);
console.log('Signature:', signature);
console.log('Signature length:', signature.length); // Should be 64