Troubleshooting
Find the cause of an integration issue without depending on internal widget markup.
Error reference
| Code | Next step |
|---|---|
| invalid_configuration / initial_configuration_only | Fix option names, values or startup timing. |
| invalid_argument / validation_error | Check arguments and field-level details. |
| widget_hidden / widget_unavailable | Show the installation or check targeting, availability and domain settings. |
| section_hidden / feature_unavailable | Enable the section or capability in widget settings. |
| prechat_required | Let the visitor complete the displayed form. The draft is preserved. |
| no_active_conversation / conversation_not_found | Open an authorized active conversation first. |
| session_expired | Reset or identify again with a fresh proof. |
| offline / timeout | Check connectivity. Avoid blind retries of in-flight sends. |
| extension_error / listener_error | Fix the extension or callback; other listeners continue. |
| native_bridge_disabled / invalid_native_command | Enable the bridge and validate the command envelope. |
| widget_destroyed | Mount a fresh installation before issuing commands. |
| command_failed | Inspect the safe message and server validation details; refresh if needed. |
The widget does not appear
- Confirm the public key and loader URL.
- Check the browser Network panel for CSP, allowed-domain or network errors.
- Check hideWidget, device visibility, path targeting and support availability.
- Check for duplicate scripts or an embedded container that does not exist.
- Use the Settings preview for appearance and the installed widget to test API behavior.
History is missing
Use the same stable signed subject and widget key. An unverified email does not authorize another session’s history. A browser may block or partition storage; signed identity lets the authorized account recover its own history. An ended latest conversation deliberately opens Home; select Messages to view it.
A method is undefined
Use the full installation snippet’s bootstrap, the explicit q queue, or call after the loader has run. Do not call getState synchronously before the SDK exists. Existing one-line snippets do not define early method stubs.
Styles do not apply
Panel and launcher CSS are separate. Use documented hooks and !important for built-in declarations. The loader may reject imports or resource URLs. Check light/dark state, mobileMode and the panel iframe’s own media-query width.
Readiness fails
ready rejects after 30 seconds if the loader cannot complete its handshake. Verify network access, the allowed domain and frame/script CSP. Error callbacks cannot fire if the browser blocks the loader script itself.