> For the complete documentation index, see [llms.txt](https://docs.sentifyd.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sentifyd.io/troubleshooting-and-requirements.md). # 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. {% hint style="warning" %} **One avatar per page.** Running two Sentifyd web components on the same page (two `` elements, two `` 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. {% endhint %} *** ### 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**: `` for standard voices, `` 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](/manual-web-integration/quick-start-guide.md)) | | `Too many login attempts` (429) | Rate limiting after repeated failures | Wait a moment and retry; fix the underlying credential error | {% hint style="warning" %} 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. {% endhint %} ### 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](/features/adding-mcp-tools-to-your-avatar.md) for setup options and design guidance. ### Still stuck? Email **** 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)