---
title: "Report Widget Voice Failure"
method: POST
path: "/api/livechat/public/{widget_key}/voice/report-failure"
tags: ["livechat", "livechat"]
---

# Report Widget Voice Failure

`POST /api/livechat/public/{widget_key}/voice/report-failure`

## Request

- Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dialogbrain.com/api/livechat/public/{widget_key}/voice/report-failure`
- Auth: none declared

Record a livechat-widget voice failure so it reaches Sentry.

WHY THIS EXISTS: the embedded widget aliases `@sentry/nextjs` to a no-op
stub (frontend/src/livechat-widget/sentry-stub.ts — the Next SDK can't be
bundled into a third-party-site IIFE without dragging Next/`process` in and
crashing the voice path, PR #3107). So the browser's
`captureVoiceStartError` reports NOTHING: visitors saw only a red banner
and we were blind. On 2026-07-28 a lost NAT rule for the LiveKit media port
broke voice for every visitor and produced ZERO Sentry issues — it surfaced
only through client complaints. The widget now POSTs here and the BACKEND
(whose Sentry works) reports it.

Auth: the visitor session token — the same gate as voice/dispatch — plus the
origin check, so this is not an open write-to-Sentry endpoint. Reporting
itself is best-effort: a telemetry failure must never propagate back into
the visitor's call path, so the body is wrapped and the endpoint still 204s.

## Path parameters

- `widget_key` string, required

## Headers

- `X-Session-Token` string, nullable

## Request body

- VoiceFailureReport: Widget-side voice-failure telemetry. Every field is optional and length-capped: this is best-effort diagnostics from an untrusted browser, recorded for triage — never trusted as truth and never used to drive logic.
  - `error_name` string, nullable
  - `error_message` string, nullable
  - `call_id` string, nullable
  - `stage` string, nullable
  - `http_status` integer, nullable
  - `browser` string, nullable
  - `user_agent` string, nullable
  - `in_app_browser` string, nullable
  - `mic_permission` string, nullable
  - `secure_context` boolean, nullable
  - `media_devices_present` boolean, nullable
  - `user_activation` boolean, nullable

## Response `204`

Successful Response

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/77bef09a9209?raw)