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

# Amazon Connect integration

> Connect Voiceflow AI agents to Amazon Connect call flows, human support queues and a staff assistant.

## Overview

Voiceflow integrates with Amazon Connect so you can answer selected customer calls with an AI agent, transfer callers to your contact-center team and give staff an on-demand assistant. Keep your existing Connect number and queues; choose which calls reach Voiceflow in your Connect flow.

The phone connection uses a Voiceflow phone number and a separate Connect number for human support. Staff assistance uses an application your team hosts in the Connect agent workspace. These are separate connections: routing a call does not install a staff application or copy Connect contact attributes into Voiceflow.

### Examples of when to use Amazon Connect

- **[Answer inbound calls](#routing-calls)** — send a selected support branch to your Voiceflow agent while retaining the public number.
- **[Human agent hand-off](#human-agent-hand-off)** — transfer callers who need a person to a staffed Connect queue.
- **[Make outbound calls](#outbound-calls)** — use a Connect-initiated call and the same tested AI route.
- **[Use contact context](#contact-context)** — supply approved contact attributes to a staff assistant through an authorized backend.
- **[Add agent assist](#agent-assist)** — let a teammate request policy guidance or a reply draft without leaving their workspace.

### What you need

- A Connect administrator who can edit and publish a test flow, manage its phone number and configure the receiving queue.
- A ready Voiceflow phone agent, an editable test [Environment](/docs/documentation/deploy/environments) and a connected phone number. Give the Connect administrator that number in E.164 format.
- A **different Connect number** for human support. Its inbound flow must reach the staffed queue, bypassing the AI branch.
- For Code, an AWS IAM role for the operations you run, the Connect instance ID and AWS Region, plus a server-side [Voiceflow API credential](/docs/api-reference/authentication) and project ID. A Voiceflow key does not authorize AWS requests.

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

<a id="routing-calls"></a>

## Routing calls to Voiceflow

Keep your Connect number and route a selected branch to the AI agent.

Use a test number or isolated branch first. In the Connect admin website, open **Routing → Flows** and copy the existing inbound flow. Add **Transfer to phone number** with the Voiceflow number as its destination. Keep your current queue route available for transfer failures. Check that the destination country is allowed for your Connect instance; see [AWS external-number transfers](https://docs.aws.amazon.com/connect/latest/adminguide/transfer-to-phone-number.html).

### Assign and test the AI destination

#### Studio

### 1. Find the Voiceflow phone line

Open your project in [Agent studio](https://creator.voiceflow.com). In the left sidebar, open **Phone numbers** and select the connected test line. Copy its full number for your Connect administrator.

Voiceflow phone numbers page with the Amazon Connect AI entry line — Give the Connect administrator the AI entry number, separate from the human return number.

### 2. Choose the Environment and version

Open the line's Environment assignment, select the test Environment and **Draft**, then save. Call the Voiceflow number directly and confirm that the intended agent answers before changing Connect routing.

Phone line assignment with Main and Draft selected — Point the test line at the version you intend to exercise.

### 3. Connect the test branch

Have your Connect administrator publish the copied flow and assign it to the test Connect number. Call that Connect number. Confirm that its selected branch reaches the same Voiceflow greeting and that speech works in both directions.

#### Developer

### 1. Assign the Voiceflow line in Studio

Open [Agent studio](https://creator.voiceflow.com), select the phone agent's project, then choose **Phone numbers** in the left sidebar. Open the connected test line's Environment assignment, select the test Environment and **Draft**, and save. Record the full phone number and assigned version. This phone-line assignment is a required Studio step; do not call the private workspace route with a project API key.

Required Studio assignment for the Amazon Connect test phone line — Complete the phone-line assignment before configuring the AWS flow.

### 2. Obtain the prepared Connect flow

Ask the Connect administrator to build the test flow described above, wire its failed-transfer exits to the existing human route and export its JSON as `connect-ai-flow.json`. Obtain the instance ID, Region, test phone-number ID and previous flow ID. The phone-number ID is the Connect resource identifier, not its E.164 telephone number. Keep the previous flow ID for rollback.

### 3. Publish and associate the test flow

Use AWS CLI v2 with an IAM role allowing `connect:CreateContactFlow` and `connect:AssociatePhoneNumberContactFlow` for these resources. Set `AWS_REGION`, `CONNECT_INSTANCE_ID` and `CONNECT_TEST_PHONE_ID` to the values supplied by the administrator.

```bash title="Publish the exported flow and assign a test number"
set -euo pipefail
CONNECT_FLOW_ID=$(aws connect create-contact-flow \
  --region "$AWS_REGION" --instance-id "$CONNECT_INSTANCE_ID" \
  --name 'Voiceflow AI test' --type CONTACT_FLOW --status PUBLISHED \
  --content file://connect-ai-flow.json --query ContactFlowId --output text)

aws connect associate-phone-number-contact-flow \
  --region "$AWS_REGION" --instance-id "$CONNECT_INSTANCE_ID" \
  --phone-number-id "$CONNECT_TEST_PHONE_ID" --contact-flow-id "$CONNECT_FLOW_ID"
```

Run the association only after creation succeeds. Use a distinct test flow name; creation is not an update operation. [CreateContactFlow](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateContactFlow.html) validates Published content. [AssociatePhoneNumberContactFlow](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociatePhoneNumberContactFlow.html) changes the number's routing and returns no response body on success.

### 4. Verify through Connect

Call the test Connect number and exercise the AI branch. Confirm the intended Voiceflow agent answers and two-way speech works. A successfully created flow is not proof that Connect can dial the Voiceflow destination.

### Caller identity and transfer behavior

Keep telephone identity separate from customer authentication and contact context.

Connect can pass the original caller ID when no custom caller ID is configured, but carriers can alter it. Treat the number as a routing hint, not proof of customer identity. A PSTN call does not carry Connect's contact ID, attributes or a Voiceflow summary.

If you enable **Resume flow after disconnect**, configure and test the resulting continuation and failure branches in Connect. It is not a Voiceflow escalation event. Verify that an AI-to-human transfer cannot send the caller through the AI branch again. Do not assume an external transfer inherits Connect recording or preserves one contact ID across both systems.

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

## Human agent hand-off

Send callers to a dedicated Connect number that routes directly to your team.

Have your Connect administrator claim or select a return number and assign a published inbound flow that uses **Set working queue → Transfer to queue**. Include the queue in the receiving staff's routing profile and arrange an answered test call. Connect's [queue routing](https://docs.aws.amazon.com/connect/latest/adminguide/transfer-to-queue.html) happens after the number answers; Voiceflow transfers to that number, not to a Connect queue ID.

### Configure the transfer destination

#### Studio

### 1. Open Call forward

In [Agent studio](https://creator.voiceflow.com), select your phone agent and test Environment. Open **Agent → Call forward**, enable the tool and choose **Phone number**.

### 2. Set the human route

Enter the Connect return number, including its country code. Describe when to transfer, such as a customer asking for a person or needing an account action the AI cannot complete.

Call forward configured with a separate Amazon Connect human-support number — Transfer to the human-only Connect number, never back to the AI entry route.

A fixed escalation branch can use a [Workflow Call forward step](/docs/documentation/build/steps/call-forward) instead.

### 3. Exercise the hand-off

Call the Connect test entry, ask the AI for a person and have a teammate answer the receiving queue. Confirm both parties can hear each other and that the AI stops speaking. Test with a connected phone line; prototype test calls cannot forward.

#### Developer

Read the existing agent with [Get agent](/docs/api-reference/agent/get-agent). Set `VF_PROJECT_ID`, `VF_ENVIRONMENT_ALIAS` and `VF_API_KEY` on your server. Replace the example return number with the administrator's staffed Connect number:

```bash title="Configure the Connect human destination"
curl --fail-with-body --silent --show-error --request PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$VF_PROJECT_ID&environmentAlias=$VF_ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_API_KEY" --header 'Content-Type: application/json' \
  --data '{"callForwardTool":{"enabled":true,"addressType":"phone","address":"+14165550145","description":"Transfer when the caller asks for a person or needs an account action the AI cannot complete.","messages":null,"toolSound":null}}'
```

This replaces the tool's configuration. Preserve any existing fields you need, read the agent back and [compile the test Environment](/docs/api-reference/environment/compile-environment). Confirm the test phone line targets that Environment's Draft. Make a real test call through Connect and verify an answered queue transfer and two-way audio.

### Context and failure boundaries

- **Customer context:** a phone transfer does not send a transcript or Connect attributes. Keep any context exchange in an authenticated backend with an explicit contact mapping; do not correlate customers solely by caller ID.
- **Human briefing:** this Call forward route does not give the receiving agent an automatic warm-transfer summary.
- **Failed transfer:** a rejected transfer can end the call. There is no automatic Voiceflow busy/no-answer recovery branch on this path. Test the receiving flow's capacity and closed-hours behavior before launch.
- **SIP:** the steps here use telephone numbers. Do not enter an Amazon Connect instance URL as a SIP address. A separate SBC or Chime bridge needs its own verified design; [general SIP setup](/docs/documentation/deploy/phone/connect-with-sip) alone does not create that bridge.

<a id="outbound-calls"></a>

## Making outbound calls

Let Connect dial the customer, then run the tested flow to Voiceflow.

Use the published Connect AI flow from [Routing calls to Voiceflow](#routing-calls). This approach keeps Connect as the call originator. The flow still needs permission to dial the Voiceflow destination after the customer answers. Connect attributes remain in Connect; they are not injected into the AI call.

### Start and verify a test call

#### Studio

### 1. Prepare the Connect-owned route

Give your Connect administrator the tested flow ID and Voiceflow number. Have them confirm outbound calling is enabled and supply an instance-owned caller ID number. Keep the Voiceflow test line assigned to the intended Environment/version.

### 2. Request one controlled outbound call

Have your integration developer call **StartOutboundVoiceContact** using the Code instructions, with a test customer's number and a stable request token. Ask for the returned contact ID. This action runs in AWS; there is no Connect campaign button added to Studio.

### 3. Answer and check the journey

Answer the test call, confirm the intended AI greets you, then request human support. Verify that the human-only return route works. The returned contact ID proves request acceptance, not that a customer answered.

#### Developer

Use AWS CLI v2 and an IAM role allowing `connect:StartOutboundVoiceContact`. Obtain the tested `CONNECT_FLOW_ID`, `CONNECT_INSTANCE_ID`, `AWS_REGION` and instance-owned `CONNECT_SOURCE_NUMBER` from the administrator. Set `CUSTOMER_NUMBER` to the E.164 test destination and `CALL_REQUEST_ID` to a unique value for this logical call attempt.

```bash title="Place a Connect-originated test call"
aws connect start-outbound-voice-contact \
  --region "$AWS_REGION" --instance-id "$CONNECT_INSTANCE_ID" \
  --contact-flow-id "$CONNECT_FLOW_ID" \
  --source-phone-number "$CONNECT_SOURCE_NUMBER" \
  --destination-phone-number "$CUSTOMER_NUMBER" \
  --client-token "$CALL_REQUEST_ID" \
  --attributes '{"reason_for_contact":"Delivery follow-up"}'
```

Retain the response's `ContactId`. Reuse the same request token for retries of that attempt so a transport retry does not deliberately create another call. Use a new token for an intentional new call. Verify customer answer, AI routing and human transfer through the actual telephone path. See [StartOutboundVoiceContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartOutboundVoiceContact.html) for allowed destinations and request errors.

### Choose which system originates the call

Keep Connect-owned calling distinct from Voiceflow-owned calling.

Connect-originated calls use AWS credentials, a Connect caller ID and a Connect flow. A [Voiceflow-originated outbound call](/docs/api-reference/agent-runtime/voice/phone-calls) instead uses a connected Voiceflow provider number and Voiceflow authorization. It does not create a Connect contact just because the agent can later transfer to Connect. Choose one originator for each job and retain that system's call identifier.

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

## Using contact context

Read approved Connect attributes on your server before asking the staff assistant.

For staff assistance, use the active Connect contact to load approved context. The application's backend must verify staff access first. A contact ID received from a browser is not authorization to read it, and a telephone transfer does not establish a trustworthy mapping between Connect and Voiceflow.

### Prepare the contact data

Have the Connect administrator populate `case_reference`, `reason_for_contact` and `product` with **Set contact attributes** in the test flow. Agree which values may leave Connect before wiring the loader.

#### Studio

Ask your developer to implement the contact loader below. Give the developer the approved field map and a populated test contact.

Obtain the signed-in staff application URL, an accessible test contact and a contact the test staff member cannot access. Confirm that the first shows the agreed fields and the second is refused. Do not paste AWS access keys or customer contact dumps into agent instructions.

#### Developer

Install `@aws-sdk/client-connect` in the staff application's server. Use its IAM role with `connect:GetContactAttributes` and the correct Region/instance. Download [contact-context.mjs](/docs/examples/amazon-connect/contact-context.mjs) and wire it to your application's contact authorization:

```js title="Load authorized Connect context"
import { ConnectClient, GetContactAttributesCommand } from '@aws-sdk/client-connect';
import { createContactLoader } from './contact-context.mjs';

const loadCaseForStaff = createContactLoader({
  client: new ConnectClient({ region: process.env.AWS_REGION }),
  GetContactAttributesCommand,
  instanceId: process.env.CONNECT_INSTANCE_ID,
  authorizeContact,
});
```

Implement `authorizeContact(staff, contactId)` using your trusted staff assignment/case service: return the **initial contact ID** only when this staff principal may access that contact in this instance; otherwise return `null`. The server sets the instance ID. Do not accept an instance or initial-contact ID supplied by the browser without checking it.

The loader calls [GetContactAttributes](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetContactAttributes.html), keeps only the three agreed fields and returns `{id, context}` for the assistant handler. Keep the allowlist aligned with the Connect flow's populated attributes. Check that a forbidden contact causes no AWS read, then confirm the allowed context reaches the assistant. AWS authorization failures must stop the request, not fall back to browser-provided data.

<a id="agent-assist"></a>

## Adding agent assist

Give staff policy guidance and draft replies inside the Connect workspace.

This is an on-demand staff application: the human remains in the customer conversation and reviews every suggestion. It does not automatically listen to calls, transcribe audio or send replies to customers.

### Connect the staff application

#### Studio

### 1. Prepare the staff assistant

Open the staff assistant's project in [Agent studio](https://creator.voiceflow.com). In **Agent**, check that its instructions answer the staff member, label suggested customer replies and use approved Knowledge. Use a read-only assistant; the example does not pass staff permissions into agent tool calls.

Staff assistant instructions for policy guidance and reviewed reply drafts — Keep the human responsible for reviewing and sending the customer reply.

Publish to a dedicated test Environment. Give your developer the project ID and Environment alias; provision their server credential through your approved secret-management process.

### 2. Obtain the ready staff application

Have your developer deploy the authenticated application described in Code, including the contact loader above. Obtain its HTTPS URL, approved Connect instance/origin, required app permissions and signed-in test staff accounts. Verify that unauthorized contacts are refused before adding it to the workspace.

### 3. Register and open the app

Have the Connect administrator add a **Standard application** under **Integrations** in the AWS Connect console, set the HTTPS access URL and **Per contact** scope, associate the instance and grant the app to the staff security profile. These are AWS controls, not Voiceflow's Integrations catalog. Follow [AWS app registration](https://docs.aws.amazon.com/connect/latest/adminguide/3p-apps.html) for regional availability and iframe settings.

### 4. Check a staff suggestion

Open the application from the Connect workspace's **Apps** launcher while handling a test contact. Ask how to handle its issue. Confirm that approved context appears in the answer, the draft remains staff-only and closing that contact clears its application state.

Staff assistant proposes a response for human review — Validate the assistant's content in Studio, then separately test delivery and contact access in Connect.

#### Developer

### 1. Mount the authenticated assistant endpoint

Start with a ready read-only Voiceflow assistant's project ID, Published test Environment alias and server API credential. Download [assist.mjs](/docs/examples/contact-center-assist/assist.mjs) and [client.mjs](/docs/examples/contact-center-assist/client.mjs). In your Node.js 22+ staff application, mount the handler as `POST /api/agent-assist`:

```js title="Use the Connect contact loader with the assistant"
import { createAssistHandler } from './assist.mjs';

export const POST = createAssistHandler({
  projectID: process.env.VF_PROJECT_ID,
  environmentAlias: process.env.VF_ENVIRONMENT_ALIAS,
  apiKey: process.env.VF_API_KEY,
  requireStaff,
  loadCaseForStaff,
});
```

Use `loadCaseForStaff` from the preceding section. Implement `requireStaff(request)` with your application's verified staff session; return its principal or `null`. Apply the host's CSRF protection when using cookies. Neither opening an iframe nor receiving a Connect contact ID signs the staff member into your backend.

The handler authorizes the contact, starts an isolated Voiceflow conversation, sends `launch`, then streams the staff question and approved context. AWS credentials, the Voiceflow API key and runtime session key stay on the server.

### 2. Bind the active Connect contact

Install `@amazon-connect/app` in the browser application and initialize the workspace SDK. Register the application with **Per contact** scope so its lifetime matches that contact:

```js title="Bind and clear the workspace contact"
import { AmazonConnectApp } from '@amazon-connect/app';
import { askAssist } from './client.mjs';

let contactId;
let pending;
AmazonConnectApp.init({
  onCreate: event => {
    const scope = event.context.scope;
    contactId = scope?.type === 'contact' ? scope.contactId : undefined;
    questionInput.disabled = !contactId;
  },
  onDestroy: () => {
    contactId = undefined;
    pending?.abort();
    output.textContent = '';
    questionInput.disabled = true;
  },
});

askButton.onclick = async () => {
  if (!contactId) return;
  pending?.abort();
  pending = new AbortController();
  const active = pending;
  output.textContent = '';
  try {
    for await (const text of askAssist({
      caseId: contactId, question: questionInput.value, signal: active.signal,
    })) {
      if (pending === active && contactId) output.textContent += text;
    }
  } catch (error) {
    if (pending === active && !active.signal.aborted) output.textContent = 'Assistance unavailable. Try again.';
  }
};
```

`questionInput`, `askButton` and `output` are elements in your app's UI. The [workspace initialization](https://docs.aws.amazon.com/agentworkspace/latest/devguide/getting-started-initialize-sdk.html) and [contact scope](https://docs.aws.amazon.com/agentworkspace/latest/devguide/integrate-with-contact-data.html) are AWS interfaces, not a Voiceflow browser SDK. Render answers with `textContent`; do not automatically send the draft to the customer.

### 3. Deploy and register the app

Host the app on HTTPS with staff authentication and a Content Security Policy permitting only the intended Connect workspace to frame it. Have the Connect administrator open **Integrations → Add integration** in the AWS Connect console. Register a **Standard application** with this HTTPS access URL and **Per contact** scope, associate the target instance, then grant the application to the test staff member's security profile. See [AWS application registration](https://docs.aws.amazon.com/connect/latest/adminguide/3p-apps.html) for required IAM permissions and iframe configuration. The application must authenticate successfully inside that iframe; test the actual browser/SSO setup, not just a standalone URL.

### 4. Verify isolation and delivery

Test an active contact, no active contact, unauthorized contact, denied AWS read and interrupted stream. Verify that closing a contact cancels its answer and clears the UI. Staff must see guidance for their authorized contact only; neither credentials nor customer messages should be emitted to the browser console.

### Release or roll back the connection

Change the customer route only after the complete test journey works.

After testing, publish the Voiceflow Environment and point the production phone line at **Published**. In Connect, release the tested flow to the intended entry number. Confirm the route once more through that public entry point.

To stop routing new calls to the AI, restore the previous Connect flow association. Keep the human-only number available. Disable the staff application's instance/security-profile access separately if that connection must stop too; changing the phone route does not remove the app. For a fuller acceptance checklist, use [Test and launch your integration](/docs/guides/integrations/contact-centers/test-connection).
