Deploy WebRTC Agents (Headless Mode)

Use headless mode when you want voice conversations with your Regal AI agent using your own layout and controls, without showing the standard Regal widget UI.

1. Initial setup

Complete the same SDK setup as a normal embed:

Share the whitelist of origins (domains where the widget will run) with your Regal Forward Deployed Engineer. Use your full origin format (https://www.example.com).
Regal will create your SDK instance and return your SDK Instance ID, which you’ll use during widget initialization.

2. Add the widget loader (same as a standard deploy)

In your page <head>:

<script src="https://cdn.regal.io/conversations-sdk/production/regal-widget.js"></script>

3. Initialize in headless mode

At the end of <body>, wait for RegalWidgetLoaded, then call init with headless: true.

Recommended: pass onEvent so you can react to session.voice_started, session.voice_stopped, voice.devices_error, session.stopped, etc. (see Events section).

<script>
(function () {
  function initRegalWidget() {
    window.RegalWidget.init({
      apiUrl: 'https://api.regal.ai',
      brandSlug: '...your brand slug...',
      agentId: '...the UUID of your agent...',
      widgetHeaderText: '...', // still required in config; not shown as UI in headless
      sdkInstanceId: '...the SDK instance ID...',
      headless: true,
      onEvent: function (event) {
        // Example: drive your own UI from event.name / event.data
        // if (event.name === 'session.voice_started') { ... }
      },
    });
  }

  window.addEventListener('RegalWidgetLoaded', initRegalWidget);
  if (window.RegalWidget && typeof window.RegalWidget.init === 'function') {
    initRegalWidget();
  }
})();
</script>

4. Start and stop voice from your UI

After init has run and the widget is ready:

When you'd like to start voice (e.g., following user button click), call window.RegalWidget.voice.startInteraction().

You’ll see session.initiated, then session.agent_ready, then session.voice_started when the mic path is live - at this point, you can consider the user in an active voice session with the agent.

When voice is started, the user will be prompted to grant microphone access through their browser if needed. If the browser blocks or fails devices, expect voice.devices_error.

Optionally, for your own captions / transcript lines, handle session.message_sent and session.message_received in onEvent using data.message, data.participant, and data.channels.

To stop voice, call RegalWidget.voice.stopInteraction().

You'll see session.voice_stopped when the agent is no longer listening / responding to the user. Then, when the session fully times out (as configured on the AI Agent builder), session.stopped will fire.