Troubleshooting

The most common issues, with the exact error to look for and the fix. Almost everything here shows up in your browser's network tab or the ingest API's response codes, so start there.

The widget doesn't appear

You pasted the wrong key type. The widget takes your pk_ public key; the events SDK takes your wk_ write key. If you put a wk_ key in the widget snippet, the widget's config request fails with 401 Invalid or inactive widget key. Copy the real snippet from the Widget settings page — it has the right key filled in.

The widget is switched off. An inactive widget returns the same 401. Check that the widget is active in your Widget settings.

The script is blocked. Ad blockers and strict Content-Security-Policy headers can stop widget.js from loading — the network tab shows the request blocked or missing entirely. For CSP, allow https://app.airhop.ai in script-src (the loader), frame-src (the chat iframe), and connect-src (the API).

Your origin isn't on the allow-list. If you configured allowed origins for the widget, requests from anywhere else get 403 Origin not allowed. Origins must match exactly — scheme, host, and port — so https://app.acme.com does not cover https://acme.com or http://localhost:3000. Add each origin you serve from, or leave the list empty to allow all.

Events aren't arriving

Key mix-up, the other direction. Sending events with the widget's pk_ key returns 401 { "message": "Invalid ingestion key." }. Events authenticate with your wk_ write key (behind the Install snippet button on the Activation page) or your sk_ secret key.

The batch is too big. More than 5,000 calls in one request returns 413 { "error": "batch too large" } and nothing is ingested. Split the batch.

You are being rate limited. Over 6,000 requests per minute per key returns 429. Batch more calls per request instead of retrying faster — the limit counts requests, not calls.

The call is silently dropped. A 200 counts calls received, not calls that survive validation — a track with no event name, or a call with an unrecognized type, is accepted and then discarded. Check the call against the call object reference.

Confirm data is flowing. The onboarding Go-live step runs a live "is data flowing?" check — it polls your event count, identified people, and the latest event name, and lights up as soon as the first events land. Use it as your end-to-end test instead of tailing logs.

identify isn't linking users

Identity verification is on, but you aren't signing. When a widget has identity verification enabled, an identify without a valid user_hash is not rejected — it is quietly treated as anonymous, so the conversation won't attach to the user. Compute HMAC-SHA256(user_id, widget identity secret) on your server and pass it as user_hash in the identify call. See Security and data.

No stable anchor. An identify needs at least a user_id or an email to bind to; a name alone identifies nobody.

The agent's answers are stale

Knowledge sources re-sync on a per-type cadence: Gmail hourly, Slack every 3 hours, helpdesks daily, and website crawls weekly (a full crawl is heavy). So a docs change you shipped this morning may not be answerable until the next crawl. Two fixes:

• Hit Re-sync on the source to queue an immediate refresh.
• Shorten the source's sync interval if it changes often — each source's cadence is overridable.

Unchanged documents are detected and skipped, so re-syncs are cheap. See Connect your knowledge.

Why did my conversation auto-close?

Airhop resolves conversations that have gone quiet, so open-queue and resolution counts stay honest. Two timers:

• Answered and quiet — 12 hours. If the last message is a confident agent answer and the customer never replied (they got their answer and left without saying thanks), the conversation resolves after 12 idle hours.
• Idle — 3 days. Any other conversation with no new messages resolves after 3 days.

A conversation still waiting on a human — an open escalation — is never auto-closed. And resolution is not final: a new customer message reopens the thread and the agent picks it back up.

Handover emails aren't arriving

Check who is configured to be notified. Escalations go to your workspace's handover email list (set during onboarding's Handover step or in team settings), plus any per-widget override, plus every member if you enabled notify-all. If nothing is configured, Airhop falls back to emailing your whole team rather than dropping the escalation silently — so "no email at all" usually means it went to someone unexpected, or:

It's in spam. Escalation emails come from your workspace's dedicated address at in.airhop.ai. Search for that domain and mark it as safe — you will be replying to these emails to answer customers, so they need to land in the inbox.

Escalations also appear in the dashboard conversation view regardless of email delivery, so nothing is ever lost — check there while you sort out delivery.