> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot live agent handoff

> Follow one test conversation from the handoff step to the support inbox and back. Record timestamps and conversation IDs, keeping secrets out of diagnostic logs.

## Identify the failing stage

Follow one test conversation from the handoff step to the support inbox and back. Record the timestamp, Voiceflow project and transcript IDs, your connection’s conversation ID, and the provider conversation ID. Keep secrets and customer message bodies out of diagnostic logs.

## Choose the symptom

<a id="check-the-connection-in-order"></a>

<Accordion title="No conversation appears">

Check the selected provider, Draft/Live connection, HTTPS Base URL and authentication header. Inspect the create request response. A timeout or transient error can be retried; preserve the idempotency key to prevent duplicate conversations.

</Accordion>

<Accordion title="The conversation reaches the wrong team">

Inspect `queueId` and its server-side mapping. Verify the provider inbox/team exists and the integration credential can use it. Do not assume the same numeric ID means the same team in another account.

</Accordion>

<Accordion title="Human replies never reach the customer">

Check provider webhook delivery, your outbound-event filtering, the conversation mapping, and Voiceflow callback status. For custom callbacks, a 401 points to signature/timestamp validation; a 404 can mean no active conversation matches the project and conversation IDs.

</Accordion>

<Accordion title="Replies appear more than once">

Deduplicate provider event IDs and Voiceflow outbound message IDs. Exclude customer echoes and internal notes. Do not generate a new event ID when retrying the same event.

</Accordion>

<Accordion title="Handoff never ends">

Confirm the provider’s actual resolution event maps to `conversation.ended`. Then check the channel return behavior and the handoff return path. Assignment changes are not resolution.

</Accordion>

<Accordion title="Attachments fail">

Check provider file support, file size, and URL lifetime. Voiceflow-to-service download URLs expire. Agent-to-customer file URLs must be fetchable by the client without a vendor credential. Never expose vendor tokens in a download URL.

</Accordion>

## Repeat the original test

Replay the same scenario with a new test conversation. Confirm delivery once in both directions, closure, return behavior, and transcript continuity. Repeat with a service timeout and a duplicate provider event.

## Collect useful evidence

Share redacted request IDs, timestamps, HTTP status, provider name, environment, and the failing stage with your integration owner or Voiceflow support. Include whether native or Custom Handoff is selected. Do not include authentication headers or webhook secrets.