Overview
Voiceflow integrates with UJET to pass an AI Chat conversation to a staffed support menu. Keep the customer in the same Chat interface while a UJET teammate receives their identity and conversation context, replies and closes the hand-off.
The connection needs UJET account credentials, signed callbacks to Voiceflow and a Handoff step selecting the menu and customer. Saving credentials does not register callbacks or prove that staff replies can reach the customer. This page covers the Chat connector; it does not configure UJET phone routing or SIP.
Before a customer launch, confirm the connector’s greeting with your Voiceflow contact. The current implementation uses a fixed Turo Support greeting, even with wait estimates disabled. It also marks the UJET customer as verified: only enter this hand-off after your trusted application authenticates the customer. Collecting an email address is not verification.
Examples of when to use UJET
- Human agent hand-off — route an authenticated customer’s support question to a staffed UJET menu.
- Share customer context — give the teammate the AI exchange or a prepared escalation summary.
- Exchange messages and photos — relay support replies and let the customer send a supporting image.
- Resume or return to AI — continue an eligible dismissed Chat or follow the configured AI continuation.
What you need
- A UJET administrator who can supply the tenant hostname, API key, webhook signing secret and numeric Menu ID for a staffed Chat menu.
- An editable Voiceflow Chat project, a test Environment and a customer interface: the Voiceflow Chat widget or a custom client implementing Chat hand-off events.
- A trusted application supplying a stable customer ID and email after authentication. Do not let an unauthenticated customer choose another person’s ID.
Studio
Use Agent studio to store the connection and configure the Workflow. Your UJET administrator still needs to enable provider-side event delivery.
Code
Set PROJECT_ID, ENVIRONMENT_ALIAS and VF_TOKEN in your shell, using a server-side Voiceflow API credential with project access. Examples use cURL, jq and a current Voiceflow CLI. Keep provider keys and VF_TOKEN out of customer browsers and source control.
Connecting UJET
Store the account credentials and enable signed Chat callbacks.
Prepare the tenant and callback
Ask your UJET administrator for these values. The UJET Apps API places API credentials under Settings → Developer Settings → API Credentials.
- Domain: the hostname after its first label, without
https://or a path. - Subdomain: the first hostname label. For
support.tenant.example, use Subdomainsupportand Domaintenant.example. - API key: the Apps API credential. Requests use the subdomain as Basic-auth username and this key as password.
- Secret key: the Chat webhook signing secret, distinct from the API key.
Have the administrator register Chat event delivery to:
Include participant_joined, participant_left, message_received, chat_ended, chat_dismissal_warning, chat_dismissed, transfer_started, transfer_accepted and transfer_failed. Have the administrator confirm the actual registration in your tenant; Connect does not create it.
Callbacks require x-signature-timestamp and x-signature: primary=…. Voiceflow checks Base64 HMAC-SHA256 using the Secret key over the timestamp followed by the JSON-serialized event body. Use the same signing secret on both sides. An HTTP 200 alone is not proof that the event matched an active Chat; verify a staff reply and closure in the customer’s interface.
Save the connection
Studio
Find UJET in your project
Open the Chat project in Agent studio. In the left sidebar, open More → Integrations, find Ujet and select Connect.
Enter the account and signing credentials
Enter Domain, Subdomain, API key and Secret key, then select Connect. Use the test tenant and signing secret from callback setup.
Check the stored scope
Connect Published first. Where the connection control offers a Draft override, configure it separately. Draft execution falls back to Published credentials without an override. Saving the form stores credentials; it does not test UJET authentication or two-way messaging.
Code
Save ujet-connection.json outside your repository and replace the placeholders:
This stable operation writes the project’s shared Published connection. It has no Environment or Draft-slot selector. Use a separate test project when you need to isolate this write.
The response reports Integration ujet connected. It confirms storage, not provider access or callback registration. Continue with the Handoff step and test a real exchange.
Replace or disconnect UJET credentials
Understand shared credentials and Draft overrides before changing the account.
Studio
Return to More → Integrations → Ujet to replace the connection in the intended slot. Removing Published also removes its Draft override. Test a new Chat after changing the API key or signing secret.
Code
Repeat the connect request to replace Published credentials. To remove the connection, use DELETE /v1/stable/integration/ujet?projectID=… on the same API host, or vf integration disconnect --integration ujet --project-id "$PROJECT_ID". Stable disconnect removes both Published and Draft slots. Stop routing new customers and account for active Chats before rotating credentials.
Human agent hand-off
Select the staffed menu and map the authenticated customer into UJET.
Set the destination and identity
Use the administrator’s numeric Menu ID and confirm that menu accepts Chat in the chosen Language. User ID is your trusted external customer identifier; User email is that customer’s email. Voiceflow exchanges the external ID for UJET’s numeric user ID. Neither is the Chat conversation ID.
Your identity service must authenticate the customer before the Workflow reaches Handoff because the adapter marks them as verified. A typed email or random browser ID is not a substitute.
Configure and route the Workflow
Studio
Open the Handoff step
In the test Environment, open Build → Workflows. Create UJET support, add a Handoff step in a block and select Ujet as Handoff provider.
Map the menu and customer
Enter Menu ID and Language. Bind User ID and User email to variables populated by your authenticated application before this step. For an isolated pilot, use one dedicated, already-verified test customer.
Set context and continuation
Select Full transcript under Handoff context. Enable Return path and Failure path. Link their exits to the intended follow-up and fallback, or leave them unlinked to return control to the calling agent. In Instructions, name the approved contact option to offer when human support cannot start.
Attach and test the Workflow
Return to Agent, add UJET support to Workflows and reference it in Instructions for authenticated customers asking for a person. Run a Draft test before publishing. Saving a Workflow does not automatically attach it to the agent.
Code
Save ujet-workflow.json. Replace the sample Menu ID and identity with one dedicated, authenticated test customer. Do not deploy this fixed identity for multiple customers.
The pilot enables Return and Failure but leaves their exits unlinked, handing control back to the calling agent. Define the fallback in Instructions, or link the exits to fixed Workflow blocks.
Save the following as prepare-ujet-patch.sh. Run it only after the Workflow creation and agent read succeed. Inspect ujet-created.json for workflow.id, unresolvedReferences and diagnostics first; stop on unresolved values. Retain the returned Workflow ID instead of repeating creation after a later failure.
This preserves the existing Workflow registry and Instructions. Replace the fallback with your real contact option and review agent-patch.json before applying it. Each method below runs the same complete create → read → patch → compile sequence.
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, create the customer variables first, populate them from your trusted application and replace the fixed identity with names such as {customer_id} and {customer_email} using Workflow update-step. Inspect unresolved references and compile again. Unknown variable names can remain literal text; writes do not create them automatically.
Verify the hand-off
Have a teammate available on the test UJET menu. Start a Chat as the verified test customer and ask for a person. Check the receiving menu, customer identity and greeting. Have the teammate reply and confirm the customer sees it in the same Chat. Do not launch while the tenant-specific greeting issue is unresolved.
Sharing customer context
Send the AI exchange or a prepared escalation summary to the receiving teammate.
Choose what staff receive
- Full transcript: formats the conversation memory available to the runtime as User and Agent messages. It does not guarantee a copy of the complete stored Transcript archive.
- Custom: sends a string prepared before Handoff, such as order reference, problem and steps already attempted. Exclude credentials and unrelated customer records.
- None: omits AI conversation context.
UJET receives this content as AI Summary custom data, alongside the Voiceflow project ID and a transcript ID when one exists. Full transcript does not generate a new summary. Arbitrary Configuration keys are not automatically forwarded as UJET custom data.
Configure the context
Studio
Open the Workflow’s Handoff step and choose Handoff context. For Custom, select an existing variable and populate its string value before entering Handoff. A variable name alone does not produce a summary.
Code
The pilot uses Full transcript. To send a prepared summary, patch the existing Handoff step using Workflow update-step:
Use an actual project variable ID, not a brace expression. Populate the active session’s string value before running the Workflow, then compile after changing its configuration.
Check staff visibility
Open the test Chat in UJET with the receiving teammate. Confirm that its custom data contains the correct customer’s reference and escalation reason, and is accessible in the staff workspace. Chat creation alone does not prove that visibility.
Exchanging messages and photos
Keep the customer connected while UJET teammates reply and receive supporting images.
Send and receive text
Studio
Use the Voiceflow Chat widget for the test. Send a customer message, reply from UJET and confirm both arrive without opening a new Chat. Test the deployed widget as well as the editor’s Draft run.
Code
Keep the existing session connected through Socket.IO. A completed HTTP Streaming response cannot receive a staff reply that arrives later. Install socket.io-client in your trusted Node.js backend. This example uses project authorization headers and must not be copied into a customer browser. Use the current session’s user ID and key, and choose the same Draft/Published variant. Register listeners before connecting:
This pilot resumes Draft. Use versionVariant: 'published' for an existing Published session. Capture activeVersionID from client.started for uploads. Use the key from the customer’s current session, not a replacement session. Keep project credentials on your trusted server. Replace logging with your message UI and implement the terminal states below. See Chat hand-off events for private-project authorization, reconnect replay using lastReceivedAt and session.history, and the complete event contract.
Send a customer photo
Studio
Use the active widget’s attachment control to send one image and have staff open it in UJET. The current UJET widget picker accepts images and has a 100 MB client limit; this is not a verified provider API maximum. Set disableFileUpload: true in the Handoff step’s Configuration if your workflow should not accept uploads.
Code
- Request
POST https://general-runtime.voiceflow.com/v1/handoff/file-storagewith activeprojectID,userID,versionID: activeVersionIDfromclient.started,fileName,fileTypeandfileSize. Use the resolved version ID for this active hand-off; an alias alone can resolve Published during a Draft test. - POST a multipart form to the returned
url, including every returnedfieldsvalue and the file. Wait for upload success. - Send
action.sendwith action typelive-agent-handoffand payload{ "type": "file_upload", "files": [{ "id": "UPLOADED_FIELDS_KEY", "name": "damage.jpg", "type": "image/jpeg", "size": 12000, "status": "uploaded" }] }. Use the returnedfields.keyand actual file metadata.
The adapter processes only the first file per action and registers it as a photo. Send one image at a time; do not infer arbitrary-document support or a provider size limit from a client-side picker. Use the handoff action schema for exact fields.
Verify the exchange
Confirm two-way text and that staff can open the customer’s image. Incoming UJET agent-message content is rendered as text; do not assume staff-sent attachments produce a separate downloadable-file event for the customer. Test your intended content before enabling it.
Returning and resuming
Handle dismissed Chats, human closure and the customer’s return to AI explicitly.
Choose the continuation
Studio
Enable Return path when the customer should continue with AI after human support. Link its exit for a fixed follow-up, or leave it unlinked to resume the calling agent. Enable Failure path and prepare a useful fallback. The widget manages return and continue controls.
Code
Configure the Handoff step’s return/failure settings and links. In the custom client:
- For
chat_dismissed, offer Continue and sendcontinue_conversationon the same hand-off. Success retains the UJET Chat ID. - For
chat_endedwith return enabled, sendreturn_to_voiceflowto continue the configured path or calling agent. - For
chat_endedwith return disabled, offer a new conversation instead of resuming the ended relay.
Send the chosen control on the ready socket from the messages example. For example, when the active trace says the Chat is dismissed:
Provider closure alone does not perform your custom client’s return action. Follow the trace’s return configuration and stop sending after session.ended; see customer controls and terminal states.
Test recovery before launch
- Connection failure: verify a useful fallback instead of indefinite waiting.
- Dismissal: dismiss and continue a test Chat. A UJET 409 on resume means try again later; it does not conclusively prove the contact center is outside business hours. A fatal resume error ends the hand-off.
- Closure: have staff end support and verify the intended AI continuation or new-conversation option.
- Missing replies: check callback URL, subscriptions, signing secret and active Chat ID. Unknown or stale Chat callbacks can still receive HTTP 200.
- Partial creation: check UJET for an existing Chat before repeating a failed attempt. Creation can succeed before custom-data submission fails and is retried; do not assume duplicate prevention.
UJET language and wait estimates
Distinguish translated notices from staff messages and queue policy.
Hand-off notices use French for fr…, Spanish for es…, and English otherwise. Staff messages are not translated. An enabled wait estimate is a projected connection time in the user’s timezone, not queue position. If the lookup fails, Chat can still start with the no-estimate greeting.
The fixed Turo greeting applies to both variants; disabling wait estimates does not remove it. Dismissal notices also use fixed translated wording, not a dynamic countdown or a configurable UJET timeout policy.