Skip to main content
All methods exist in three places - use whichever fits your setup:
  1. The <voiceai-widget> DOM element
  2. The object returned by VoiceAIWidget.init()
  3. window.VoiceAIWidget.* (proxies to the first mounted instance)
// All three are equivalent on a single-widget page:
document.querySelector('voiceai-widget').startCall();
instance.startCall();
window.VoiceAIWidget.startCall();

​
The readiness model

The widget fetches its configuration asynchronously after the script loads. You do not need to wait - startCall() and sendChatMessage() are safe to call immediately:
  • A startCall() made before the widget is ready is buffered (one pending start) and fires right after widget.ready.
  • sendChatMessage() calls made before ready are FIFO-queued and flushed in order.
The widget.ready event exists so careful integrators can gate their UI - for example, enabling the button only when the widget is ready. Its payload tells you which modes (voice, chat) the widget supports.

​
At a glance

MethodWhat it does
startCall()Starts a voice call.
stopCall()Ends the active call.
sendChatMessage(text)Sends a chat message, auto-starting a session if needed.
endChatSession()Ends the active chat session.
acceptConsent()Records consent and resumes the paused action.

​
startCall()

Starts a voice call. 
widget.startCall();
Edge behavior:
  • Called before the config loads → buffered (one pending start), fires right after widget.ready.
  • Called while a call is active or connecting → no-op plus a console.warn.
  • Voice not enabled on the widget (or no voice assistant configured) → fires widget.error.

​
stopCall()

Ends the active call. Also works for calls started from a visible launcher. 
widget.stopCall();
Edge behavior: no-op when idle. Always safe to call.

​
sendChatMessage(text)

Sends a chat message. Auto-starts a chat session if none is active - there is no separate “connect” step. 
widget.sendChatMessage('Hi! What are your opening hours?');
Edge behavior:
  • Called before ready → messages are FIFO-queued and flushed in order.
  • Empty or whitespace-only text → ignored.
  • Chat not enabled (or chat assistant missing for Retell/ElevenLabs) → fires widget.error.

​
endChatSession()

Ends the active chat session (server-side end plus cleanup). The next sendChatMessage() starts a fresh session. 
widget.endChatSession();
Edge behavior: no-op when there is no session. Clears any queued messages.

​
acceptConsent()

Records the visitor’s consent (persisted in localStorage under the widget’s configured key) and automatically resumes the action that triggered widget.consent-required - the pending call starts, or the queued chat message sends. 
widget.addEventListener('widget.consent-required', () => {
  // show your own consent UI, then on accept:
  widget.acceptConsent();
});
Edge behavior: no-op if consent wasn’t requested. “Declining” is simply not calling it.
See Consent in Headless Mode for the full consent flow, including the compliance responsibilities that come with rendering your own consent UI.