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

# UJET integration

> Connect Voiceflow Chat to UJET support with customer context, signed callbacks and conversation recovery.

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

**Warning:** 
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](#human-agent-hand-off)** — route an authenticated customer's support question to a staffed UJET menu.
- **[Share customer context](#customer-context)** — give the teammate the AI exchange or a prepared escalation summary.
- **[Exchange messages and photos](#support-messages)** — relay support replies and let the customer send a supporting image.
- **[Resume or return to AI](#returning-and-resuming)** — 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](/docs/documentation/deploy/environments) and a customer interface: the Voiceflow Chat widget or a custom client implementing [Chat hand-off events](/docs/api-reference/agent-runtime/chat/handoff).
- 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](https://creator.voiceflow.com) to store the connection and configure the Workflow. Your UJET administrator still needs to enable provider-side event delivery.

#### Developer

Set `PROJECT_ID`, `ENVIRONMENT_ALIAS` and `VF_TOKEN` in your shell, using a server-side [Voiceflow API credential](/docs/api-reference/authentication) with project access. Examples use cURL, jq and a current [Voiceflow CLI](/docs/cli/install). Keep provider keys and `VF_TOKEN` out of customer browsers and source control.

<a id="start-with-the-shared-guides" />

<a id="connecting-ujet"></a>

## 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](https://externals.ujet.co/apidocs/apps/publication.html) 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 Subdomain `support` and Domain `tenant.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:

```text title="Voiceflow UJET callback"
https://general-runtime.voiceflow.com/handoff/webhook/ujet
```

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

### 1. Find UJET in your project

Open the Chat project in [Agent studio](https://creator.voiceflow.com). In the left sidebar, open **More → Integrations**, find **Ujet** and select **Connect**.

Integrations navigation spotlighted beside the UJET Connect card — Open More → Integrations in the same project as the Chat agent.

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

UJET connection dialog with its four account and signing fields — Store the tenant host, API key and webhook signing secret separately.

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

#### Developer

Save `ujet-connection.json` outside your repository and replace the placeholders:

```json title="ujet-connection.json"
{
  "integration": "ujet",
  "credentials": {
    "domain": "YOUR_UJET_DOMAIN",
    "subdomain": "YOUR_UJET_SUBDOMAIN",
    "apiKey": "YOUR_UJET_API_KEY",
    "secretKey": "YOUR_UJET_WEBHOOK_SECRET"
  }
}
```

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.

#### API

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/integration/ujet?projectID=$PROJECT_ID" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @ujet-connection.json
```

#### CLI

```bash
vf --output-format json integration connect --integration ujet \
  --project-id "$PROJECT_ID" < ujet-connection.json
```

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.

#### Developer

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.

<a id="human-agent-hand-off"></a>

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

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

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

UJET Handoff editor with Menu ID, Language, User email and User ID — Route the verified customer to the intended UJET menu and language.

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

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

#### Developer

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.

```json title="ujet-workflow.json"
{
  "name": "UJET support",
  "entry": "handoff",
  "blocks": [{
    "key": "handoff",
    "name": "Connect UJET support",
    "steps": [{
      "kind": "handoff",
      "content": {
        "config": {
          "provider": "ujet",
          "menuID": "123",
          "userID": "customer-ns-2048",
          "userEmail": "ada@customer.example",
          "userLanguage": "en"
        },
        "handoffContext": { "type": "full" },
        "returnPath": true,
        "failPath": true
      }
    }]
  }]
}
```

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.

```bash title="prepare-ujet-patch.sh"
set -euo pipefail
WORKFLOW_ID=$(jq -er '.workflow.id' ujet-created.json)
jq --arg id "$WORKFLOW_ID" '
  .agent | {
    workflows: ((.workflows // []) + [{workflowID: $id, description: null}]),
    instructions: ((.instructions // "") + "\nFor an authenticated customer asking for a person, use `UJET support`. If it cannot connect, offer the approved alternative contact route.")
  }
' agent-before.json > agent-patch.json
```

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.

#### API

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @ujet-workflow.json > ujet-created.json

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS&includeInstructions=true" \
  --header "Authorization: $VF_TOKEN" > agent-before.json
```

After inspecting the create result, prepare and review the attachment:

```bash
bash prepare-ujet-patch.sh
cat agent-patch.json
```

Apply the reviewed patch and compile Draft:

```bash
curl --fail-with-body --silent --show-error --request PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @agent-patch.json

curl --fail-with-body --silent --show-error --request PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT_ALIAS/compile?projectID=$PROJECT_ID" \
  --header "Authorization: $VF_TOKEN"
```

#### CLI

```bash
vf --output-format json workflow create --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" < ujet-workflow.json > ujet-created.json

vf --output-format json agent get --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" --include-instructions > agent-before.json
```

After inspecting the create result, prepare and review the attachment:

```bash
bash prepare-ujet-patch.sh
cat agent-patch.json
```

Apply the reviewed patch and compile Draft:

```bash
vf --output-format json agent update --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" < agent-patch.json

vf --output-format json environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS"
```

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](/docs/cli/commands/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.

<a id="customer-context"></a>

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

#### Developer

The pilot uses Full transcript. To send a prepared summary, patch the existing Handoff step using [Workflow update-step](/docs/cli/commands/workflow/update-step):

```json title="Handoff context patch"
{
  "kind": "handoff",
  "content": {
    "handoffContext": {
      "type": "custom",
      "variableID": "YOUR_EXISTING_VARIABLE_ID"
    }
  }
}
```

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.

<a id="support-messages"></a>

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

#### Developer

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:

```js title="Receive replies on the existing Chat session"
import { io } from 'socket.io-client';
const socket = io('https://general-runtime.voiceflow.com', {
  path: '/v4/interact/socket', autoConnect: false,
  transports: ['websocket'],
  extraHeaders: {
    'x-voiceflow-project-id': process.env.PROJECT_ID,
    authorization: process.env.VF_TOKEN,
  },
});
let ready = false;
let activeVersionID;
socket.on('connect', () => {
  ready = false;
  socket.emit('client.start', {
    projectID: process.env.PROJECT_ID, userID: 'CURRENT_VF_USER_ID',
    environmentID: process.env.ENVIRONMENT_ALIAS,
    versionVariant: 'draft', sessionKey: 'CURRENT_SESSION_KEY',
    config: { modality: 'chat' },
  });
});
socket.on('client.started', ({ newSessionRequired, versionID }) => {
  if (newSessionRequired) {
    ready = false;
    console.error('The current session could not resume; do not replace an active handoff.');
    socket.disconnect();
    return;
  }
  activeVersionID = versionID;
  ready = true;
});
socket.on('action.trace', ({ trace }) => {
  if (trace.type === 'live-agent-handoff') console.log(trace.payload);
});
socket.on('disconnect', () => { ready = false; });
socket.on('session.ended', () => { ready = false; });
socket.on('error', error => console.error(error));
socket.on('connect_error', error => console.error('Connection failed:', error));
socket.connect();

function sendSupportMessage(message) {
  if (!ready) throw new Error('Wait for the current session to resume.');
  socket.emit('action.send', {
    action: { type: 'live-agent-handoff', payload: { type: 'message', message } },
  });
}
```

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](/docs/api-reference/agent-runtime/chat/handoff) 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.

#### Developer

1. Request `POST https://general-runtime.voiceflow.com/v1/handoff/file-storage` with active `projectID`, `userID`, `versionID: activeVersionID` from `client.started`, `fileName`, `fileType` and `fileSize`. Use the resolved version ID for this active hand-off; an alias alone can resolve Published during a Draft test.
2. POST a multipart form to the returned `url`, including every returned `fields` value and the file. Wait for upload success.
3. Send `action.send` with action type `live-agent-handoff` and payload `{ "type": "file_upload", "files": [{ "id": "UPLOADED_FIELDS_KEY", "name": "damage.jpg", "type": "image/jpeg", "size": 12000, "status": "uploaded" }] }`. Use the returned `fields.key` and 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](/docs/api-reference/v4interact/interact-non-stream#streaming-action) 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.

<a id="returning-and-resuming"></a>

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

#### Developer

Configure the Handoff step's return/failure settings and links. In the custom client:

- For **`chat_dismissed`**, offer Continue and send `continue_conversation` on the same hand-off. Success retains the UJET Chat ID.
- For **`chat_ended` with return enabled**, send `return_to_voiceflow` to continue the configured path or calling agent.
- For **`chat_ended` with 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:

```js title="Continue a dismissed UJET Chat"
if (ready) {
  socket.emit('action.send', {
    action: {
      type: 'live-agent-handoff',
      payload: { type: 'continue_conversation' },
    },
  });
}
```

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](/docs/api-reference/agent-runtime/chat/handoff#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.
