Troubleshooting

widget_unavailable (HTTP 404)

Catch-all for “could not broker a token for this widget.” The specific reason is logged server-side (check your API logs for a code: field) but not returned to the client to avoid leaking information.

Sub-reason	Cause	Fix
`widget_not_found`	The `widget-id` doesn’t exist	Check the widget ID in the dashboard; confirm you’re pointed at the right Supabase project
`origin_not_allowed`	Page origin not in the allowed origins list	Add the domain in Widgets → [widget] → Allowed origins
`voice_platform_not_connected`	No Retell/Vapi account connected	Go to Voice platforms and connect your account
`retell_agent_not_configured`	Widget has no agent selected	Open the widget in the dashboard and pick an agent
`decryption_failed`	`VOICE_PLATFORM_KEY_SECRET` mismatch	Reconnect the voice platform account; locally, ensure your `.env` matches the Supabase secret

retell_auth_failed (HTTP 502)

The decrypted Retell API key was rejected by Retell. Either it was rotated/revoked in Retell, or it was pasted with trailing whitespace.

Fix: Go to Voice platforms → [account] → Reconnect and paste the current key.

Card never appears during a call

Work through this checklist in order:

Check API logs for show-card webhook dispatched. If missing, Retell isn’t calling the tool or is calling the wrong URL.
Check the function name in Retell is exactly powsoo_show_card (lowercase, underscores — no typos, no capitalisation).
Check the function type is Server-side with the URL set to https://api.powsoo.com/v1/retell/tools/show-card. A client-side function without a URL will not work — the Retell Web SDK cannot publish data back over the LiveKit data channel.
Check the system prompt instructs the agent to call powsoo_show_card. The LLM won’t use a tool it hasn’t been told about.
Test with the fixture card in the widget playground (http://localhost:5176 → Render email fixture card). If the fixture works but live cards don’t, the issue is in the Retell agent config, not the widget.

The playground dev server runs on port 5176. If that port is taken (e.g. by a leftover process), the server fails to start.

Fix: Kill the conflicting process and re-run pnpm dev.

Mic permission keeps prompting

Browsers cache localhost mic permissions per Chrome profile.

Fix: Open chrome://settings/content/microphone and explicitly allow http://localhost:5176.

Call button doesn’t appear after embedding

The widget loads asynchronously after widget.js is fetched from the CDN. On slow connections it can take 1–2 seconds.

If it never appears:

Open the browser console and look for errors.
Verify https://w.powsoo.com/widget.js loads (no 404).
Make sure the <script> tag is present in the DOM — some CMSes strip inline <script> tags from rich text blocks. Use a dedicated code embed block instead.

SSE stream disconnects frequently

EventSource reconnects automatically, so brief disconnects during a call are handled. If it’s constant:

Check that your reverse proxy isn’t buffering the response. For nginx, add X-Accel-Buffering: no to the upstream response.
Verify Content-Type: text/event-stream is not being overridden.
Cloudflare’s default connection timeout (100s) is shorter than a long call. Either use Cloudflare’s Enterprise streaming support or bypass Cloudflare for the /v1/sessions/*/stream path.