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
No conversation appears
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.
The conversation reaches the wrong team
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.
Human replies never reach the customer
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.
Replies appear more than once
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.
Handoff never ends
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.
Attachments fail
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.
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.