VocoAgents Widget Documentation

Installation

Add the widget to your website with these two lines of code:

<vocoagents-browser-agent-widget></vocoagents-browser-agent-widget>
<script src="https://widget.vocoagents.com/vocoagents-widget.umd.js"></script>

That's all: your website's domain is registered with your agent, so the widget finds it by itself. Keep the closing tags — HTML has no self-closing <script /> or custom elements. Running several agents on one domain? Add agent="AGENT_SLUG" to pick one.

Element Attributes

Attribute	Required	Description
`agent`	No	An agent slug — only when one domain runs several agents. Without it the widget uses the agent registered for your domain.
`persona`	No	Start on a specific persona (its name or key) when the page itself chooses who speaks. Visitors can still switch with the widget's own persona dots.
`data-extract-metadata`	No	Set to "false" to disable automatic URL parameter extraction (default: true)

JavaScript API

The widget exposes a global window.voco object:

`start(context?)`

Start a voice call with optional context data.

window.voco.start({
  dynamic_data: {
    name: 'John',
    account_id: '12345'
  },
  metadata: {
    source: 'pricing-page'
  }
})

context.dynamic_data - Key-value pairs passed to the agent (accessible in agent scripts)

context.metadata - Additional metadata for tracking

`stop()`

End the current call.

window.voco.stop()

`on(event, callback)`

Subscribe to widget events.

window.voco.on('call:started', (data) => {
  console.log('Call started:', data.callId)
})

`off(event, callback)`

Unsubscribe from widget events.

window.voco.off('call:started', myCallback)

State Properties

Property	Type	Description
`isConnected`	boolean	True when a call is active
`isConnecting`	boolean	True when connecting to a call

Events

Event	Description	Event Data
`call:starting`	Call is initiating	context, timestamp
`call:started`	Call connected successfully	callId, context, timestamp
`call:ended`	Call ended	callId, context, timestamp, duration

Look & Personas

The widget's look is set on your agent — not in your HTML — so it's always the same everywhere it appears and changes without touching your site:

Avatar — the face (and talking animation) of the persona speaking.
Personas — with two or more, small dots under the avatar let visitors choose who they talk to.
Call-to-action, brand name, color and icon and text direction.

The former styling attributes (poster, cta-text, cta-bg-color, …) are no longer read.

Complete Example

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>

  <!-- VocoAgents Widget -->
  <vocoagents-browser-agent-widget></vocoagents-browser-agent-widget>
  <script src="https://widget.vocoagents.com/vocoagents-widget.umd.js"></script>

  <!-- Custom integration -->
  <button id="startCallBtn">Talk to AI Agent</button>
  <script>
    document.getElementById('startCallBtn').addEventListener('click', () => {
      if (window.voco) {
        window.voco.start({
          dynamic_data: { name: 'Visitor' }
        })
      }
    })

    // Listen for events
    const checkVoco = setInterval(() => {
      if (window.voco) {
        window.voco.on('call:started', () => console.log('Call connected!'))
        window.voco.on('call:ended', () => console.log('Call ended'))
        clearInterval(checkVoco)
      }
    }, 100)
  </script>
</body>
</html>