Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Troubleshooting & Requirements

Browser & Device Requirements

  • Browser: A current version of Chrome, Edge, Firefox, or Safari. The 3D avatar requires WebGL support (available in all modern browsers unless disabled by policy or very old GPU drivers).

  • HTTPS: Microphone access requires a secure context. The page embedding the avatar must be served over HTTPS (or localhost during development).

  • Audio: Speakers/headphones for voice output; a microphone for voice input. Text chat works without either.

  • Network: Standard HTTPS/WebSocket connectivity. Real-time avatars additionally use WebRTC; very restrictive corporate firewalls that block WebRTC media can prevent real-time audio.

One avatar per page. Running two Sentifyd web components on the same page (two <sentifyd-bot> elements, two <sentifyd-realtime> elements, or one of each) is not supported and is a common source of failures. Make sure your page — including templates, themes, and tag managers that might inject a second copy — embeds exactly one avatar.

The avatar doesn't appear

  • Confirm the script tag is present and loading (check the browser's Network tab):

    • Standard: https://frontend.sentifyd.io/sentifyd-bot/main.js

    • Real-time: https://frontend.sentifyd.io/sentifyd-realtime/v1/main.js

  • Use the component that matches the avatar's voice mode: <sentifyd-bot> for standard voices, <sentifyd-realtime> for real-time. A mismatch will fail to connect.

  • Check that both avatar-id and either api-key or token-endpoint are set on the element.

  • Make sure only one Sentifyd component is present on the page (see the note above).

  • Open the browser console — the component logs descriptive errors for every failure mode below.

Authentication errors

The browser console shows the login failure reason:

Symptom / status
Cause
Fix

Avatar not found (404)

Wrong avatar-id, or the avatar was deleted

Copy the ID from the avatar page ("Actions" > "Details")

Unauthorized (401)

Wrong or rotated API key, or the site's domain is not in the avatar's allowed domains

Verify the API key; add the exact domain in the Website Deployment modal (see the Quick Start Guide)

Too many login attempts (429)

Rate limiting after repeated failures

Wait a moment and retry; fix the underlying credential error

The allowed domain must match the domain the page is actually served from. If you deploy the same embed to staging and production, add each domain. Testing from a different subdomain is a common cause of 401 errors.

No sound / avatar is silent

  • Browsers block audio autoplay until the user interacts with the page. The widget automatically unlocks audio on the first click or tap — make sure the user has interacted with the widget (this also applies after a page reload with a resumed conversation).

  • Check the device's output volume and that the browser tab is not muted.

  • On iOS, ensure the physical silent switch is off.

Microphone problems

  • Permission denied: If the user dismissed or blocked the mic prompt, re-enable it via the browser's site settings (padlock icon in the address bar), then reload.

  • No prompt at all: The page is probably not served over HTTPS — browsers only allow microphone access on secure pages.

  • Mic busy or missing: Another application may be holding the microphone, or the operating system's microphone permission for the browser is disabled (common in macOS and Windows privacy settings).

  • Echo / avatar hears itself: Echo cancellation is enabled by default. If users are on loudspeakers in a noisy or kiosk setup, prefer headphones, or disable barge-in so the avatar doesn't listen while speaking.

Real-time avatar issues

  • Real-time avatars stream audio over WebRTC. If audio never starts on a corporate network, ask IT whether WebRTC/UDP media is blocked.

  • If the session drops after being idle, simply click the widget to reconnect — idle sessions are disconnected to save resources.

WordPress specifics

  • The Sentifyd Avatar WordPress plugin has its own settings panel, which overrides the customization saved on the Avatar Page. Configure widget appearance in the plugin settings.

  • Select the correct voice mode in the plugin settings: choose the real-time option for real-time avatars and the standard option for standard-voice avatars. The plugin embeds the matching component for you — a mismatch with the avatar's actual voice mode will fail to connect.

MCP tools not working

  • The endpoint URL must be publicly reachable — URLs resolving to private or local addresses (e.g., localhost, 192.168.x.x) are rejected for security.

  • Your MCP server must respond to the initial connection within a few seconds, or its tools are skipped for that conversation.

  • See Adding MCP Tools to Your Avatar for setup options and design guidance.

Still stuck?

Email info@sentifyd.io and include:

  1. Your avatar ID

  2. The domain where the avatar is embedded

  3. Browser + OS version

  4. Any errors from the browser console (screenshots welcome)

PreviousShort-lived Avatar Tokens (Advanced)NextUsage Statistics