FAQ and Troubleshooting

This page covers the issues most likely to appear after deployment: installation mistakes, queue problems, widget-domain failures, missing AI replies, email inbox errors, and stale analytics.

1) The app loads but some pages fail after install

Check the basics first: valid .env values, database connectivity, storage link, and migrations. If attachments or branding uploads are missing, the storage link is usually the first thing to verify.

php artisan optimize:clear
php artisan config:clear
php artisan migrate --force
php artisan storage:link

2) AI replies or training jobs never finish

Most AI and document workflows are queued. If the queue worker is not running, the UI may accept the action but no processing will happen.

3) The widget script loads but bootstrap returns 403

A 403 on widget bootstrap almost always means the request origin is not included in that widget's allowed domains. Add the exact live domain in Chat > Widgets and test again from the real host.

4) Visitors can chat but AI never answers

• Confirm the widget has AI enabled.
• Confirm an active OpenAI provider config exists for the workspace.
• Confirm the queue worker is running.
• Confirm the provider API key is valid.
• Confirm knowledge-only mode is not blocking answers because retrieval scored too low.

5) Inbound email returns 403 or 404

A 404 usually means the email channel is inactive or missing. A 403 usually means the X-Aibot-Email-Secret header does not match the stored channel secret.

6) Password reset or reply-by-email does not send

Verify SMTP from the settings screen and double-check sender credentials. Shared hosting environments often block outbound SMTP combinations that work on local machines.

7) Webhooks are created but downstream systems reject them

Confirm the destination accepts JSON POST requests and verify the HMAC signature using the endpoint signing secret. Delivery logs store the last response status and error body so you can inspect failures without packet captures.

8) Dashboard totals look stale

Reporting data is cached per workspace and filter set for five minutes. Wait for the cache window to expire or generate new records that change the workspace report stamp.

9) FAQ items do not show in the public help center

Confirm the FAQ is approved and published, the source is active, and the workspace slug in the help-center URL is correct.

10) The product looks empty in screenshots

Use Platform Ops > Demo Import to generate a sample workspace with a conversation, lead, ticket, and trained knowledge source. This is the fastest way to populate the dashboard and reports for previews.