> ## 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.

# Connect Voiceflow to Front

> Build and test a two-way live agent handoff connection with Front. Customers stay in Voiceflow while your team replies from your support platform.

## What you will build

Customers stay in their Voiceflow conversation while your team replies from Front. Your service translates the platform’s conversation operations and events into the [live agent handoff system](/docs/documentation/handoff/overview).

This is a developer implementation guide, not a native connector. The API approach has been reviewed against provider documentation; a live account test is required before rollout.

## Before you begin

You need a Front API token and permission to configure a custom channel in a test inbox, an HTTPS service, and access to Custom Handoff in Voiceflow. Start with [the shared connection starter](/docs/developers/handoff/connect). Choose one test customer and one support destination.

Incoming acceptance returns a message UID; the conversation is created asynchronously. Persist the thread reference immediately and reconcile the Front conversation ID afterward.

## Implement the connection

<Steps>
<Step title="Prepare the support workspace">
In Settings → Inboxes, add a Custom channel. Enable replies through the same channel and set its Outgoing URL to your verified provider receiver.

Confirm a teammate can receive and answer a manually created test conversation before adding Voiceflow.
</Step>
<Step title="Implement conversation creation">
Send the first customer message to the channel Incoming URL. Set `metadata.thread_ref` to your connection conversation ID.

Example provider request body for `POST /channels/CHANNEL_ID/incoming_messages` (replace illustrative IDs):

```json
{
  "sender": {
    "handle": "customer-123",
    "name": "Alex"
  },
  "body": "Customer requested human support.",
  "metadata": {
    "thread_ref": "CONNECTION_CONVERSATION_ID"
  }
}
```

Use the starter’s `create(request, connectionId)` hook. Persist the provider ID and connection ID together. Forward relevant context as an initial summary or supported private note; never inject internal metadata into customer-visible replies.
</Step>
<Step title="Forward customer messages">
Send subsequent customer messages to the same Incoming URL with the same `metadata.thread_ref`.

Implement the starter’s `message(providerConversationId, message)` hook. Deduplicate the Voiceflow message `id`. For the first test, support text and explicitly reject unsupported files rather than acknowledging and dropping them.
</Step>
<Step title="Receive human replies">
Handle the custom channel’s outgoing message callbacks. Use the public text and author, and resolve the mapped conversation. Verify Front’s documented request signature before accepting the callback.

After provider authentication succeeds, look up the mapped connection ID and send a normalized `message.received` event to the starter’s authenticated `/events` route. Include a stable provider event ID, timestamp and human display name. Do not manufacture an `agent.joined` event merely because a conversation was created.
</Step>
<Step title="Implement closure">
Resolve the mapped Front conversation through its conversation update API. Map its actual resolution/archival signal to the handoff end event according to your chosen closure policy.

Implement the `end(providerConversationId)` hook. Deliver `conversation.ended` for provider-initiated closure. Make both paths idempotent so a reflected closure cannot trigger an endless loop.
</Step>
<Step title="Connect and test in Voiceflow">
Configure your service in **Settings → Integrations → Custom Handoff**, then follow [Set up live agent handoff](/docs/documentation/handoff/setup). Set Queue ID only when your service has a documented mapping. Publish to a test environment and use the actual customer channel.
</Step>
</Steps>

### Provider mapping

Use `metadata.thread_ref` as the stable integration thread key. After an accepted incoming message, resolve its `message_uid` through the message resource alias before relying on the Front conversation ID. Handle this asynchronously; a slow Front lookup must not cause repeated creation. Archive/resolve actions and message callbacks are different event paths—implement both.

## Verify a complete handoff

Run this acceptance sequence with a teammate in Front:

1. Escalate and confirm exactly one conversation appears in the intended inbox.
2. Check the customer identity and escalation context.
3. Send “customer test 1” from Voiceflow and “human test 1” from the support inbox. Both must arrive once.
4. Add a private note; it must not reach the customer.
5. Replay the same customer-message ID and provider event ID; neither should duplicate a message.
6. Close from the support inbox and verify the configured return-to-AI path.
7. Repeat with invalid credentials and an unavailable provider; verify the fallback.

If messages disappear, inspect the provider delivery log, the ID mapping and Voiceflow callback response in that order. A successful create call alone does not establish that the connection works.

## Reference and next steps

[Provider setup/API documentation](https://dev.frontapp.com/docs/creating-a-custom-channel) · [Provider messages/events documentation](https://dev.frontapp.com/reference/receive-custom-messages)

[Connection API](/docs/developers/handoff/connection-api) · [Event contract](/docs/developers/handoff/webhook-events) · [Troubleshooting](/docs/documentation/handoff/troubleshooting)

Before production, replace in-memory state with durable storage, implement the provider’s retry/refresh rules, and test attachment and routing support only if your deployment needs them.