Sipfront Widget - Integration Documentation

Widget Types

Sipfront offers three types of embeddable widgets:

Test Widget Interactive widget that lets users start a single test on-demand. Shows real-time progress and results. Perfect for "Test Our Service" buttons on your website.
Project Widget Runs an entire test suite (multiple tests in sequence). Shows overall progress and summarized results. Ideal for comprehensive integration testing dashboards.
Monitor Widget Real-time status display showing uptime, availability percentage, voice quality scores, and operational status. Updates automatically every 60 seconds. Perfect for status pages and customer-facing dashboards. No user interaction required - displays monitoring data immediately.

Integration Instructions

Step 1: Create Your Test or Project In Sipfront, create a test or project that will run against your service.
Step 2: Publish as Widget Go to your project page, click the "..." menu on a test (or project), and select: "Publish as Test Widget", "Publish as Monitor Widget", or "Publish as Widget" (for projects). Configure allowed domains and rate limits, then generate your unique widget token.
Step 3: Add Widget to Your Page Copy the generated iframe code and paste it into your website HTML where you want the widget to appear.
Step 4: Customize Parameters For test/project widgets: Replace bot_id with your bot's unique identifier. For monitor widgets: Customize the label to match your service name. The token already includes which test/project to monitor or run.

<!-- Sipfront Widget (works for Test, Project, or Monitor) -->
<iframe 
    src="https://app.sipfront.com/widget?token=YOUR_TOKEN&bot_id=YOUR_BOT_ID&label=Custom+Label&color=667eea"
    width="400" 
    height="500"
    frameborder="0"
    style="border: none; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);"
></iframe>

<!-- 
  The token determines the widget type (test/project/monitor).
  For test/project: Set bot_id to your bot's unique identifier (required)
  For monitor: bot_id can be any value or omitted (not used)
  Adjust height to 400px for monitor widgets for optimal display
-->

About Widget Tokens

Widget tokens are publishable keys designed specifically for client-side embedding. Unlike API keys, they are safe to expose in public HTML because:

Scoped Access Test/Project tokens can only run ONE specific test or project. Monitor tokens can only view monitoring data for ONE specific test. Tokens cannot list, create, delete, or modify anything.
Domain Restricted Tokens only work on domains you whitelist. If someone steals your token, they can't use it on their own site.
Rate Limited Configure how many test runs per hour (1-100). Prevents abuse even if token is exposed. Monitor widgets are read-only and not rate limited.
Revocable Disable any token instantly without affecting your API keys or other widgets.

Configuration Options

Parameter	Widget Type	Required	Description	Example
`token`	All	Yes	Publishable widget token (includes scope and type)	`pk_widget_abc123xyz`
`bot_id`	Test, Project	Yes	Unique identifier for your bot instance being tested	`bot_12345`
`bot_id`	Monitor	No	Any value (not used by monitor widgets)	`monitor` or `status`
`label`	All	No	Test/Project: Button text. Monitor: Display name	`Test+My+Bot` or `Service+Status`
`show_report`	Test, Project	No	Show "View Full Report" button after test completes	`true` / `false`
`color`	All	No	Brand color (6-digit hex, no # prefix)	`667eea`

Features

Test & Project Widgets

State Persistence Users can navigate away and return - test progress is automatically saved in LocalStorage
Multi-Widget Support Multiple widgets for different bots can run simultaneously on the same page without conflicts
Real-time Updates Progress bar updates every 5 seconds with smart percentage calculation
Public Sharing Test results are automatically made publicly shareable via kiosk URLs

Monitor Widgets

Automatic Display No button clicks needed - monitoring status displays immediately on page load
Live Status Updates Auto-refreshes every 60 seconds to show current operational status (Operational/Degraded/Down)
Availability Tracking Shows uptime percentage color-coded: Green (≥99%), Yellow (<99%), Red (<90%)
Voice Quality Scores Displays per-role voice quality percentages for comprehensive quality monitoring
Uptime Timeline Visual timeline showing up/down periods over the selected time range
Incident Reporting Shows current incidents with reason and duration when service is degraded or down

All Widgets

Brand Customization Customize colors to match your brand identity
Fully Isolated Widget runs in iframe sandbox - won't affect your site's styling or JavaScript

Security

The widget implements enterprise-grade security with publishable keys:

Publishable Widget Tokens Safe to embed in public HTML. Tokens are scoped to a specific test or project and cannot access other resources.
Domain Whitelisting Tokens only work on domains you explicitly allow. Content-Security-Policy headers prevent unauthorized embedding.
Rate Limiting Configurable hourly limits (1-100 tests/hour) prevent abuse even if token is exposed.
Revocable Tokens Disable tokens instantly without affecting other widgets or your API keys.
Session Isolation LocalStorage is isolated per bot_id. Multiple widgets can run on the same page without conflicts.
Session TTL 30-minute timeout automatically clears stale sessions.

Advanced Examples

React Component

import React from 'react';

const SipfrontWidget = ({ 
    token,          // Your widget token (pk_widget_...) - determines type
    botId,          // 'monitor' for monitor widgets, or your bot ID for test/project
    label = 'Test My Bot',
    color = '4f46e5', 
    showReport = true,
    height = 500    // Use 400 for monitor widgets
}) => {
    const widgetUrl = new URL('https://app.sipfront.com/widget');
    widgetUrl.searchParams.set('token', token);
    widgetUrl.searchParams.set('bot_id', botId);
    widgetUrl.searchParams.set('label', label);
    widgetUrl.searchParams.set('color', color);
    widgetUrl.searchParams.set('show_report', showReport);

    return (
        <iframe
            src={widgetUrl.toString()}
            width="400"
            height={height}
            frameBorder="0"
            style={{
                border: 'none',
                borderRadius: '12px',
                boxShadow: '0 4px 12px rgba(0,0,0,0.1)'
            }}
            title="Sipfront Widget"
        />
    );
};

export default SipfrontWidget;

Usage: Test: <SipfrontWidget token="pk_widget_xxx" botId="my_bot" />
Monitor: <SipfrontWidget token="pk_widget_yyy" botId="status" height={400} /> (bot_id can be any value)

Vue Component

<template>
  <iframe
    :src="widgetUrl"
    :width="400"
    :height="height"
    frameborder="0"
    style="border: none; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);"
  ></iframe>
</template>

<script>
export default {
  props: {
    token: { type: String, required: true },      // Widget token (determines type)
    botId: { type: String, required: true },      // 'monitor' or your bot ID
    label: { type: String, default: 'Test My Bot' },
    color: { type: String, default: '4f46e5' },
    showReport: { type: Boolean, default: true },
    height: { type: Number, default: 500 }        // Use 400 for monitors
  },
  computed: {
    widgetUrl() {
      const url = new URL('https://app.sipfront.com/widget');
      url.searchParams.set('token', this.token);
      url.searchParams.set('bot_id', this.botId);
      url.searchParams.set('label', this.label);
      url.searchParams.set('color', this.color);
      url.searchParams.set('show_report', this.showReport);
      return url.toString();
    }
  }
};
</script>

Usage: Test: <SipfrontWidget token="pk_widget_xxx" botId="my_bot" />
Monitor: <SipfrontWidget token="pk_widget_yyy" botId="status" :height="400" /> (bot_id can be any value)

Sipfront Widget Integration Documentation