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 — send a selected support branch to your Voiceflow agent while retaining the public number.
- Human agent hand-off — transfer callers who need a person to a staffed Connect queue.
- Make outbound calls — use a Connect-initiated call and the same tested AI route.
- Use contact context — supply approved contact attributes to a staff assistant through an authorized backend.
- Add 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 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 and project ID. A Voiceflow key does not authorize AWS requests.
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.
Assign and test the AI destination
Studio
Find the Voiceflow phone line
Open your project in Agent studio. In the left sidebar, open Phone numbers and select the connected test line. Copy its full number for your Connect administrator.
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.
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.
Code
Assign the Voiceflow line in Studio
Open Agent studio, 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.
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.
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.
Run the association only after creation succeeds. Use a distinct test flow name; creation is not an update operation. CreateContactFlow validates Published content. AssociatePhoneNumberContactFlow changes the number’s routing and returns no response body on success.
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.
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 happens after the number answers; Voiceflow transfers to that number, not to a Connect queue ID.
Configure the transfer destination
Studio
Open Call forward
In Agent studio, select your phone agent and test Environment. Open Agent → Call forward, enable the tool and choose Phone number.
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.
A fixed escalation branch can use a Workflow Call forward step instead.
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.
Code
Read the existing agent with 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:
This replaces the tool’s configuration. Preserve any existing fields you need, read the agent back and compile the test 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 alone does not create that bridge.
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. 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
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.
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.
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.
Code
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.
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 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 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.
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.
Code
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 and wire it to your application’s contact authorization:
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, 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.
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
Prepare the staff assistant
Open the staff assistant’s project in Agent studio. 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.
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.
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.
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 for regional availability and iframe settings.
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.
Code
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 and client.mjs. In your Node.js 22+ staff application, mount the handler as POST /api/agent-assist:
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.
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:
questionInput, askButton and output are elements in your app’s UI. The workspace initialization and contact scope are AWS interfaces, not a Voiceflow browser SDK. Render answers with textContent; do not automatically send the draft to the customer.
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 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.
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.