Troubleshooting

Start with the browser's developer tools: the Console shows the chat's own messages (prefixed [Wireface Chat], with a link to the error's explanation), and the Network tab shows its requests. Booting with debug: true (or data-debug="true") logs every event the chat emits.

WirefaceChat.getState(); // { open, conversationId, visitorId, unread }

The chat doesn't appear

Work through these in order:

1. Is widget.js loading? In the Network tab, widget.js should answer 200. A 404 with "widget.js is not built yet" means the server was started without building the widget.
2. Does the bot load? Look for /v1/widget/bots/<id>/config:
   • 404 (config_not_found): wrong data-bot, or the bot isn't published, or it's paused. Publish it.
   • 403 (origin_not_allowed): your site isn't in the bot's allowed origins. See below.
   • blocked, or no request: a Content-Security-Policy is in the way (connect-src). See CSP.
3. Is it hidden? launcher: { type: 'none' } or hideOnMobile hide the launcher; another element with a higher z-index can cover it (raise the chat's zIndex).
4. Inline layout? The target element must exist when the chat starts; if it doesn't, the console says so and the chat falls back to a launcher.

"This website is not allowed to use this chat"

origin_not_allowed: the page's origin isn't in the bot's allowed origins.

• Add the exact origin under the bot's Security tab and publish: scheme, host and port must all match (https://www.example.com is not https://example.com).
• https://*.example.com covers subdomains but not the bare domain; add both if you use both.
• For local testing add http://localhost:*.
• A page inside another site's iframe also fails: every page up the frame chain must be allowed (the chat window's frame-ancestors). That shows as frame_blocked.

Content-Security-Policy violations

The console names the directive. Add your chat host to:

• script-src (widget.js), connect-src (the bot's settings), frame-src (the chat window) and img-src (the face on the launcher).

Symptoms: network when connect-src blocks the settings request; frame_blocked 15 seconds after opening when frame-src blocks the window. With the npm package under enforced Trusted Types, allow its policy: trusted-types wireface-chat. See Content-Security-Policy.

No sound

• Browsers only play sound after the visitor interacts with the page. Voice started from the chat's microphone button always works; see Voice.
• Text replies are silent: only voice conversations speak. (The face moves its lips to text replies, without sound.)
• Check the device's volume and that the tab isn't muted.

Microphone and camera

mic_denied, mic_unavailable, camera_denied:

• HTTPS. Both your site and the chat server must be https:// (localhost is fine for testing). On plain http the browser never offers the microphone.
• Permission. If the visitor blocked it once, the browser remembers: they can allow it again from the icon in the address bar.
• Permissions-Policy. If your site sends a Permissions-Policy header, it must delegate microphone and camera to the chat host: microphone=(self "https://chat.example.com"). See CSP.
• Another app using the microphone or camera, or no device at all, gives mic_unavailable or camera_denied with the browser's own reason.
• The camera button only shows when the bot's camera is enabled and its brain can see images.

The face looks different, or doesn't move

The full animated face needs WebGL2. Without it (very old devices, some virtual machines, or hardware acceleration turned off in the browser) the chat draws a lighter 2D wireframe of the face instead, and if even that can't load, a still picture; everything else works. Turning hardware acceleration back on in the browser's settings usually brings the full face back. (The webgl_unavailable code is reserved and not raised.)

Visitors who ask their system for reduced motion get a calmer face on purpose.

The chat keeps reconnecting

The header says "Reconnecting..." and messages don't send: the chat window's WebSocket (/v1/widget/ws) isn't getting through.

• A reverse proxy must pass WebSocket upgrades (Upgrade and Connection headers). See Reverse proxy.
• 403 on the socket ("Open the chat through its frame"): the server compares the chat's origin with its own address. Set PUBLIC_URL to the exact public address, and TRUST_PROXY=true behind a proxy.
• Corporate networks and some antivirus software block WebSockets; there's no fallback transport in this version.
• After a fatal error (an origin or identity problem, or too many connections from one address) the chat stops trying until the page is reloaded.

Voice unavailable or busy

• voice_unavailable: voice isn't fully set up for the bot (the Voice tab lists what's missing), a person from your team has the chat, or the voice engine stopped with an error (the message says which).
• voice_capacity: the bot has security.caps.concurrentVoiceSessions voice conversations already.
• spend_cap_reached: a daily cap (security.caps) is used up; it resets at midnight UTC.
• No microphone button at all: voice is off, or its engine isn't fully configured (a missing connection, model or voice).

Provider key errors

The visitor sees "Sorry, I couldn't answer just now" and the admin panel marks the connection.

• invalid: the provider rejected the key (revoked, mistyped, or for another project). Replace it under Providers.
• quota: the account is out of credit or over its spending limit at the provider.
• error: the server couldn't reach the provider: check outbound internet access, a corporate proxy, or the PROVIDER_BASE_URL_* variables.
• A model that disappeared from your account: pick another in the bot's Brain or Voice tab and publish.
• Test on the connection checks the key again. The server log has the provider's own error message.

In previews, the chat itself shows why a reply failed.

"No one from the team is available"

A hand-off needs someone who can take it: within the bot's opening hours (when it has them), and someone from the team (an owner, admin or agent) with the admin panel open, so their presence is online or away. Presence resets to offline when the server restarts, until their panel reconnects. See Human handoff.

The agent doesn't use my page tools

• Client tools are off by default: turn on tools.client.enabled and list the tool names in tools.client.allow (or *) in the bot's Tools tab, then publish.
• The tool must be registered on the page the visitor is on.
• Make the description say when to use it. See Client tools.

Identity errors

• identity_required: the bot requires identity and the page sent no user. Pass it to boot().
• identity_invalid: the hash doesn't match. Hash exactly the id string you pass, with the bot's current identity secret, on your server. It also comes when a different user is signed in to a chat a verified user already has: call shutdown({ forget: true }) on sign-out. See Identity verification.

Still stuck?

Set LOG_LEVEL=debug on the server and reproduce the problem: the log shows each step. The error codes and what causes each are listed in Errors.