Overview
Voiceflow integrates with Dixa to move an AI Chat conversation to a staffed support queue. Customers stay in the same Chat interface while a Dixa teammate receives their identity and conversation context, replies and closes the hand-off.
Connect the Dixa account, enable callbacks and configure a Handoff step for the receiving queue. This connection uses Dixa’s Generic API Messaging channel; it does not configure phone routing or SIP.
Examples of when to use Dixa
- Human agent hand-off — connect a customer who needs a person to the appropriate Dixa queue.
- Share customer context — give the receiving teammate the AI exchange or a prepared escalation summary.
- Exchange messages and files — keep the customer and teammate connected, including supporting attachments.
- Return to AI — follow the configured continuation after human support ends.
What you need
- A Dixa administrator, a Dixa API token and a staffed Queue ID. The token must allow the requester lookup/creation, conversation import, internal notes, queue transfer, messaging and close operations used below.
- An editable Voiceflow Chat project with Dixa available in Integrations, a test Environment and a customer interface: the Voiceflow Chat widget or a custom client implementing Chat hand-off events.
- A trusted source for the customer’s external ID, email and name. Do not let a customer choose someone else’s account identifier or email to retrieve their record.
Studio
Use Agent studio to store the connection and configure the Workflow. Your Dixa administrator completes the provider-side callback setup.
Code
Set PROJECT_ID, ENVIRONMENT_ALIAS and VF_TOKEN in your shell. Use a server-side Voiceflow API credential with project access. Examples use cURL, jq and a current Voiceflow CLI. Keep provider credentials and VF_TOKEN out of customer browsers and source control.
Connecting Dixa
Store the API token and authorize Dixa callbacks to Voiceflow.
Prepare the account
Ask a Dixa administrator to create a Dixa API token in Settings → Integrations → API Tokens, following Dixa’s token setup. Grant access to the operations listed in What you need. Voiceflow sends this token directly in Dixa’s Authorization header, without a Bearer prefix.
Obtain the staffed queue’s ID from Settings → Queues, as described in Dixa’s queue hand-off guide. Keep this Queue ID separate from the customer ID and conversation ID.
Enable callbacks
A Dixa administrator must configure an outbound webhook. Saving the Voiceflow connection does not create this subscription.
Add the outbound webhook
In Dixa, open Settings → Integrations → Webhooks → Add outbound webhook. Set the Webhook URL to:
Authorize delivery
Choose a strong callback secret and configure Token authorization, or a custom Authorization header with value Bearer YOUR_CALLBACK_SECRET. In Voiceflow’s Webhook secret key, store only YOUR_CALLBACK_SECRET, without the Bearer prefix.
Dixa’s automatically generated webhook verification secret is for its HMAC signature. Voiceflow’s Dixa connector instead checks the Authorization value. Copying the generated verification secret without configuring this header does not authorize delivery.
Subscribe and filter
Enable Conversation message added, Conversation assigned, Conversation closed, Conversation abandoned and Typing started. Their event identifiers are CONVERSATION_MESSAGE_ADDED, CONVERSATION_ASSIGNED, CONVERSATION_CLOSED, CONVERSATION_ABANDONED and TYPING_STARTED.
Filter to Generic API Messaging and the intended queue. Do not suppress API-originated events needed by this connection. Enable and save the subscription. See Dixa webhook setup for its controls.
Save the connection
Studio
Find Dixa in your project
Open the Chat project in Agent studio. In the left sidebar, open More → Integrations, find Dixa and select Connect.
Enter the credentials
Enter API key and Webhook secret key. Leave Domain (optional) empty for the standard Dixa API host. If your administrator supplies an alternative API base URL, include its scheme and version path; this field is not your workspace’s display name.
Select Connect. This stores the values; it does not test the token or callback subscription.
Check the connection scope
Connect Published first. Where offered, configure a separate Draft override for testing. Draft runs fall back to Published credentials without an override; changing the Environment alone does not isolate the account.
Code
Save dixa-connection.json outside your repository and replace the placeholders. Omit domain to use https://dev.dixa.io/v1.
This stable operation writes the project’s shared Published connection. It has no Environment or Draft-slot selector; use a separate test project to isolate the write.
The response reports Integration dixa connected. This confirms storage, not Dixa authentication or two-way messaging. Continue with the Handoff step.
Replace or disconnect Dixa credentials
Coordinate credential changes with active hand-offs and callback authorization.
Studio
Return to More → Integrations → Dixa to replace or remove the intended connection. Removing Published also removes its Draft override.
Code
Repeat the connect operation to replace Published credentials. To remove both Published and Draft, use DELETE /v1/stable/integration/dixa?projectID=… on the same host, or vf integration disconnect --integration dixa --project-id "$PROJECT_ID".
Active hand-offs retain the credentials captured when they started. Drain those conversations before rotating the token or callback header; replacing project credentials does not update an existing hand-off. Verify a new conversation after the change.
Human agent hand-off
Route the customer to a staffed Dixa queue without changing their Chat interface.
Set the queue and customer
- Queue ID: the receiving Dixa queue’s identifier.
- End user ID: a stable external identifier from your application, not a Dixa conversation ID.
- User email: the customer’s email. Voiceflow looks up this email first, then the external ID, and creates a Dixa requester if neither lookup matches.
- Customer name: the display name used when creating a requester.
- Language: stored with the connection. It does not translate Dixa teammate replies or select a different queue.
Supply a stable nonempty End user ID. Only pass identity belonging to the current customer; an email match takes precedence over the external ID.
Configure and route the Workflow
Studio
Open a Handoff step
In the test Environment, open Build → Workflows. Create Dixa support, add a Handoff step inside a block and choose Dixa as Handoff provider.
Map the queue and identity
Enter Queue ID. For the pilot, use a dedicated test customer. For production, create the customer variables and supply them before Handoff as described in Map production customer data below.
Set context and continuation
Choose Full transcript for Handoff context. Enable Return path and Failure path. Link their exits to fixed follow-up blocks, or leave them unlinked to return control to the calling agent. Add the real fallback contact option to Instructions.
Attach the Workflow
Return to Agent, add Dixa support to Workflows and reference it in Instructions for customers asking for a person. Run a Draft test before publishing. Creating the Workflow alone does not attach it to the agent.
Code
Save dixa-workflow.json. Replace the queue placeholder and use one dedicated test customer. Do not deploy this fixed identity for multiple customers.
This pilot leaves Return and Failure exits unlinked, handing control back to the calling agent. Define the fallback in Instructions or link the exits to Workflow blocks.
Save prepare-dixa-patch.sh. Run it after Workflow creation and agent read succeed. Inspect dixa-created.json for workflow.id, unresolvedReferences and diagnostics first; stop on unresolved values. Keep the returned ID rather than repeating creation after a later failure.
The patch preserves the current Workflow registry and Instructions. Replace the fallback with your real contact option and review agent-patch.json before applying it. Both methods below cover create → read → patch → compile.
After inspecting the create result, prepare and review the attachment:
Apply the reviewed patch and compile Draft:
After inspecting the create result, prepare and review the attachment:
Apply the reviewed patch and compile Draft:
Read the agent back to confirm attachment and routing. Compilation prepares Draft without publishing it. Test Draft, then publish the reviewed Environment before the customer-facing test.
For production, replace the fixed identity using the variable setup below. Writes do not create missing variables; inspect unresolved references and compile again.
Map production customer data
Studio
In your project, open More → Variables and create variables named customer_id, customer_email and customer_name. Leave customer-specific defaults empty. In the Handoff step, insert those variables into End user ID, User email and Customer name. Before entering Handoff, populate them from your authenticated application; for an editor pilot, use a dedicated test identity rather than a shared production default.
Code
- Create
customer_id,customer_emailandcustomer_namewithPOST /v2/stable/variable?projectID=…&environmentAlias=…on the realtime API host. Each body suppliesname,colorand an emptydefaultValue. Alternatively use vf variable create, for examplevf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT_ALIAS" --name customer_id --color-param '#515A63' --default-value '""'. - Read
GET /v2/stable/variable?projectID=…&environmentAlias=…, or vf variable list, to obtain eachvariables[].id. Binding text uses the name, such as{customer_id}; Custom context uses the resource ID. - Read
GET /v1/stable/workflow/$WORKFLOW_ID?projectID=…&environmentAlias=…, or vf workflow get. Find the Handoff step’sidin the response’s top-levelblocks[].steps[]. Use it with Workflow update-step to replace the fixed identity fields. Compile again after the patch. - From your authenticated backend, send the actual values by name in the
variablesmap alongside the launch or text action before the Workflow enters Handoff. Session creation alone does not populate those values. Do not accept another customer’s identifiers directly from an untrusted browser.
Verify routing and replies
Have a teammate available in the test queue. Ask the AI for a person and check that Dixa receives the right requester and assigns the conversation from the intended queue. Have the teammate reply and verify that the customer sees it.
Voiceflow imports the conversation before transferring it to the queue. A queue-transfer failure does not abort the hand-off, so a “Fetching a human agent” message or chat_started trace is not proof of assignment. Check the Dixa queue itself before declaring success.
Sharing customer context
Give the Dixa teammate the AI exchange or a prepared escalation note.
Choose the context
- Full transcript: sends the conversation memory available to the runtime as Customer/Bot lines in an internal note. It does not guarantee the complete stored Transcript archive or generate a new summary.
- Custom: sends a string variable prepared before Handoff, such as the order reference, issue and troubleshooting already attempted.
- None: omits the AI context note.
Context is an agent-only internal note, not a message attributed to the customer. Full transcript escapes customer text; Custom passes the authored string through as note content. Exclude credentials and unrelated records. Arbitrary Configuration keys do not become Dixa custom attributes.
Configure the note
Studio
In More → Variables, create handoff_summary with an empty default. Set it to the escalation summary before Handoff, using a Set step or your trusted application. Open the Workflow’s Handoff step, choose Custom under Handoff context and select that variable. Naming a variable does not produce a summary.
Code
The pilot uses Full transcript. Create handoff_summary using the variable procedure above and retain its variable.id (or find it in variables[].id). Read the Workflow to obtain the Handoff step ID. Update that step with Workflow update-step:
Compile the updated Workflow. Before entering Handoff, send variables: {"handoff_summary":"Order 1042: damaged item; customer requested a specialist."} alongside an authenticated launch or text action. Use your actual, relevant summary. The runtime map uses the name handoff_summary; authoring uses its resource ID. Test the same Environment and execution variant.
Verify staff context
Open the resulting Dixa conversation and confirm the internal note contains the intended exchange or summary. Note creation is best-effort: human support can start without it. Also verify the matched requester because email lookup takes precedence over external ID.
Exchanging messages and files
Relay teammate replies, typing and attachments to the existing customer session.
Keep the conversation connected
Studio
Use the Voiceflow Chat widget for the test. Send a customer message and reply from Dixa. Check that each arrives without starting another Chat. The widget handles teammate messages, assignment, typing and the ended state; test the deployed widget as well as Draft.
Code
Use Socket.IO for asynchronous replies. A completed HTTP Streaming response cannot receive a teammate’s later message. Install socket.io-client on your trusted Node.js server. Use the customer’s existing session key, user ID and execution variant. Start this socket before asking the AI to enter Handoff and keep it running through the exchange; register listeners before connecting:
This pilot resumes Draft; use versionVariant: 'published' for an existing Published session. Use activeVersionID returned by client.started for uploads. This minimal pilot disables automatic reconnect. If the socket disconnects, disable customer controls. Before reconnecting to an already-active hand-off, restore its recorded chat_started configuration and process missed events using Recover an interrupted connection below; a closure may have arrived while disconnected. The server does not automatically resend initial configuration. A new session is not a replacement for an active hand-off. Replace logging with your message UI and handle chat_ended as described below. See Chat hand-off events for the shared connection and customer-action contract.
Send an attachment
Send one file at a time. Dixa hand-off storage accepts files up to 26,214,400 bytes (25 MiB).
Studio
In the active widget, use the attachment control to send one file. Have the teammate open it in Dixa, then send a file back and confirm that the customer can open it. To disable uploads, set disableFileUpload: true in the Handoff step’s Configuration.
Code
Request an upload
Call POST https://general-runtime.voiceflow.com/v1/handoff/file-storage with projectID, the current userID, versionID: activeVersionID from client.started, fileName, fileType and fileSize. Use the resolved execution version; an alias can resolve Published during a Draft test.
Upload the file
POST a multipart form to the returned url, including every returned fields value and the file. Wait for success. The upload URL expires after five minutes.
Send the uploaded reference
Send action.send on the ready socket with action type live-agent-handoff and payload:
Use fields.key from the upload response and the actual metadata. The adapter sends only the first file per action. Follow the handoff action schema for the full envelope.
Receive teammate events
Dixa callbacks produce participant_joined, agent_typing, message_received, file_received and chat_ended events. Only outbound Dixa messages reach the customer; inbound echoes and internal notes are not relayed as customer messages. For a message containing attachments, Voiceflow forwards the first attachment and its associated text. Do not assume a batch of attachments becomes several events.
Verify two-way text and a file in each direction. A successful callback HTTP status alone does not establish delivery: stale conversation IDs and ignored event shapes can still receive HTTP 200.
Recover an interrupted connection
Restore hand-off state before enabling customer controls after a disconnect.
Studio
Test a temporary disconnection in the deployed widget during human support. Confirm the same customer session resumes, later replies arrive and a conversation closed during the interruption stays ended. Do not start a replacement conversation to test recovery of the original one.
Code
The minimal socket example disables automatic reconnect. Add recovery before enabling it:
- Persist the initial
chat_started.config, current hand-off state and the latest receivedtrace.timetimestamp. Keep the same project, user, execution variant and session key. - Register a
session.historylistener before reconnecting. Restore the initial configuration, then include the saved timestamp aslastReceivedAtinclient.start. - Read
session.history.replayin order. For each entry, inspectentry.data: apply only traces withtype: 'live-agent-handoff'and apayload.event. Actions can share the outer type but havepayload.type; they are not teammate events. Apply missedchat_endedbefore allowing further support messages. - Advance the cursor from trace
time, using the entry’s parsedcreatedAttimestamp when needed. Replay contains events after the supplied cursor, not a fresh configuration snapshot. - The server emits replay before
client.started. Re-enable controls only after history has been applied andclient.startedconfirmsnewSessionRequired: false. If it requires a new session, stop and explicitly end recovery of the old one.
Persist this state outside the socket instance if your application can restart during a hand-off. Reconnecting without the cursor and replay handling can miss a closure or leave the wrong return controls visible.
Ending human support
Handle closure and return to the configured AI path explicitly.
Choose the continuation
Studio
Enable Return path to let the customer continue with AI. Link its exit to a follow-up block or leave it unlinked to resume the calling agent. Enable Failure path with a useful fallback. The widget manages customer return controls from this configuration.
Code
Retain config.returnToAI from the initial chat_started event; chat_ended does not repeat that configuration. After chat_ended, when return was enabled, send the control below on the ready socket to close the hand-off and continue the configured Workflow path or calling agent:
When return is disabled, show the ended state instead of continuing the relay. Stop sends after session.ended. A provider closure does not itself perform the custom client’s return action; see customer controls and terminal states.
Dixa Closed and Abandoned callbacks both end the relay. This connector does not reopen a closed Dixa conversation through continue_conversation. A socket reconnect to an existing active session is separate from reopening a closed provider conversation.
Test the finish and fallback
Close the conversation in Dixa and check that the customer sees the ended state. Exercise the configured return to AI and verify the intended follow-up. In an isolated test project, also use an invalid queue and confirm your team detects the missing assignment; a failure path alone cannot catch the best-effort transfer failure.
Before moving customer traffic, complete the Contact Center test and launch checklist with your real token, queue and callback subscription. Keep the previous routing configuration available for rollback.