# Verify and troubleshoot an integration

A build passing is useful evidence. A verified customer journey also proves that
the intended workspace, agent, tools and permissions work together.

## Before calling it complete

- Widget loads, opens, sends a test message and receives a reply in the expected inbox.
- Navigation and rerendering do not create duplicate widgets or conversations.
- Signed-in identity is correct; logout/account switching cannot reveal another user's conversation.
- Each business tool succeeds for an authorized customer, rejects unauthorized access,
  and returns a clear failure when the upstream service is unavailable.
- Mutations retain confirmation and duplicate-request handling.
- Human handoff reaches the intended team when included in the integration.
- Environment setup, resource IDs, and the disable/undo path are documented without secrets.

Use authorized test identities. Distinguish mocked checks from live checks. If
access is missing, report what is verified locally and the exact next action needed.

## Diagnose common failures

| Symptom | Check |
| --- | --- |
| Widget missing | Real inbox ID, client mount, SDK load, consent gate, browser console and CSP |
| `window is not defined` | Initialize in a client component/lifecycle; do not run browser code during SSR |
| Duplicate widget | Mount once, keep config stable, destroy the JS SDK on teardown |
| Headless session rejected | Correct Turnstile setup and token; see the Chat SDK guide |
| User identity rejected | Correct inbox secret, exact authenticated user ID, server-generated HMAC |
| API 401 | `X-API-Key` for org keys, expired credential, missing server configuration |
| API 403 | Matching `orgId`, allowed read/write actions, account approval and feature eligibility |
| Server SDK reaches wrong origin or omits key | Current transport limitation; use the verified REST path |
| MCP lists only public operations | Current Bearer/session versus organization-key mismatch |
| MCP mutation lacks input fields | Discovery may omit the body; inspect full OpenAPI, do not guess |
| Feature present in schema but rejected | Availability and account gates still apply |
| Webhook never delivered | Generic durable outgoing webhooks are currently off |
| Provider connection unavailable | Account/provider eligibility; an entitlement alone does not enable a beta |

## Safe retries

Use bounded request timeouts. Respect Retry-After on throttled requests when
provided. After an ambiguous write result, read current state before retrying.
Do not repeat purchases, sends, bookings or resource creation blindly.

## Get help with useful evidence

Include the package version, framework, environment, endpoint/tool name, timestamp,
HTTP/error code, and request ID if provided. Supply a minimal reproduction using
synthetic data. Remove tokens, authorization headers, cookies and customer content.
Use [Masheev contact](https://masheev.com/contact) for account or provider access.