Overview
Voiceflow integrates with Five9 to answer selected inbound calls, return callers to human support and give staff an on-demand assistant beside their CRM call controls. Keep your Five9 customer number and choose which IVR branches reach a Voiceflow phone agent.
The telephone recipe uses an external Voiceflow number and a separate Five9 number for human support. The staff assistant runs in your authenticated CRM beside Five9 Agent Desktop Toolkit Plus. These connections do not automatically copy Five9 call variables, customer records or transcripts into Voiceflow.
Examples of when to use Five9
- Answer inbound calls — route an IVR branch to Voiceflow for delivery updates and policy questions.
- Human agent hand-off — let callers reach a Five9 queue when they need a person.
- Add agent assist — give staff policy guidance and reply drafts beside their Five9 controls.
- Test and launch — verify the caller journey and rehearse routing rollback before changing the public entry point.
What you need
- A Five9 license and an administrator who can edit inbound campaigns, assigned numbers, IVR scripts and skills.
- A Voiceflow phone project, an editable test Environment and a connected phone number.
- A dedicated externally dialable Five9 human-support number that bypasses the AI branch and reaches the receiving queue.
- For Code, cURL, jq and the current Voiceflow CLI with Agent v2 support. Set
PROJECT_ID,ENVIRONMENT_ALIASand a server-side personal or service key inVF_TOKEN. Configure CLI authentication with the same key, or pass--token "$VF_TOKEN". These credentials do not authorize Five9 administration.
Choose the connection contract
Telephone routing, VoiceStream and digital messaging have separate requirements.
Five9’s VoiceStream developer contract defines its own streaming lifecycle. A Voiceflow WebSocket URL is not a substitute for that interface. Open Messaging has separate conversation and delivery requirements. The examples below implement telephone routing and an on-demand CRM assistant, rather than either adapter.
Preparing your voice agent
Resolve the supported customer requests before transferring callers to Five9 staff.
Configure the conversation
Use short spoken replies, ask one question at a time and state when the agent should bring in a person. Attach the Playbooks, Knowledge and tools needed for the requests you actually support. Connecting a Five9 number does not import company policies or create business-system tools.
Studio
Prepare the phone agent
Open the project in Agent studio, select the test Environment, then open Agent → Instructions. Define the support tasks, approved policy sources and transfer conditions. Attach the relevant Playbooks and tools, then insert their resource references in the instructions.
The example retailer uses its own order lookup service. It is not a Five9 customer-record API.
Check speech and escalation
Configure the agent’s Voice settings. Test a policy question, an order question and a request for a person. Configure the actual transfer destination in Human agent hand-off below before testing a phone transfer. Run the agent after edits to compile its Draft before calling the connected line.
Code
Start with an existing phone project and attached Playbooks/tools. Save your Instructions as agent.json; use the names of resources already attached to that agent. These fields leave its existing resource registries and Voice settings unchanged:
Read the agent back with Get agent. Confirm the intended Instructions and tools remain configured. Compile the Draft after edits using Testing and launch below; a saved configuration is not yet proof of a working telephone conversation.
Routing calls to Voiceflow
Keep your Five9 number and send a selected call-flow branch to the AI agent.
Assign the Voiceflow destination
Use a dedicated test line first. Your Five9 administrator needs the Voiceflow number and an externally reachable human fallback before editing the campaign IVR. Copy the complete Voiceflow number, then format the Five9 destination for your domain as explained below.
Studio
Find the AI entry number
In Agent studio, open your phone agent’s project. In the left sidebar, open Phone numbers and find the connected test line. Copy its full number, including the country code.
Select the test version
Open the line’s Environment assignment, choose the test Environment and Draft, then save. Call this number directly and confirm the intended agent answers before testing through Five9.
Code
Use a personal or service key with access to this workspace and phone project. Set WORKSPACE_ID to the workspace containing the connected line. Obtain it through Workspaces, and keep PROJECT_ID and ENVIRONMENT_ALIAS from the agent configuration above. The key needs vf.phone-number:LIST and vf.phone-number:READ for the workspace, plus vf.phone-number:ASSIGN on the target Environment. The number and project must belong to the same workspace.
Find the connected line
Select the dedicated test line from phoneNumbers. Set PHONE_NUMBER_ID to its id, not its E.164 value. Keep value for the Five9 administrator and retain its current voice assignment for rollback.
Pin the voice side to the test Draft
Verify phoneNumber.voice.projectID, environmentAlias and version are the intended project, test alias and draft. Assignment changes the voice side only; it leaves SMS routing unchanged.
Find the connected line
Select the dedicated test line from phoneNumbers. Set PHONE_NUMBER_ID to its id, not its E.164 value. Keep value for the Five9 administrator and retain its current voice assignment for rollback.
Assign and inspect the voice side
Confirm phoneNumber.voice names the intended project, test alias and draft. The --version-param flag selects Draft/Published; it is not a CLI version flag. Only voice routing changes.
Compile the Draft after agent edits, then call the Voiceflow number directly. Confirm the expected greeting and two-way speech before giving the number to the Five9 administrator. The Five9 flow changes below use Five9 administration, not the Voiceflow credential.
Route the Five9 IVR branch
Use a separate inbound pilot campaign and a test number. Your Five9 administrator owns campaign and IVR configuration; the Voiceflow credential does not authorize it. Record the current campaign, number and script assignment before editing.
Prepare the inbound pilot
In VCC Administrator → IVR Scripts, open the pilot script’s properties and select Edit. Add Third Party Transfer to the AI branch. Use the existing menu to keep a direct human-support option. See creating an IVR script.
Set the external Voiceflow number
Open the module’s General tab. Set Third Party Number → Constant to the Voiceflow line’s phone-number value, not its resource ID. Use the format configured for your Five9 domain: E.164-enabled domains can accept the country code with +; domains without E.164 require a 10-digit NANP number without a leading 1 or punctuation. Confirm the actual format with your Five9 administrator.
Set completion and failure behavior
Set Ringing Timeout (seconds) and Max Time of 3rd Party Call (seconds) for the pilot; the documented maxima are 30 seconds and 3,600 seconds respectively. Decide whether Return After 3rd Party Call is appropriate and connect the module’s error path to human support or an announcement. Test this separately from Voiceflow’s explicit human transfer. Third Party Transfer settings also include recording, interruption and data-transfer controls; they do not automatically exchange Voiceflow session data.
Assign the test number and run the campaign
In Five9 Admin Console, open the inbound campaign’s Interaction Flow, configure its schedule/timezone and select the pilot IVR script. In VCC Administrator → Campaign Properties → DNIS → Add, select an available account-owned test number, then OK → Save/Apply. A number belongs to one campaign. Start the pilot campaign and confirm it is running. Call the test number, choose the AI branch and verify two-way speech. See campaign configuration, DNIS assignment and starting campaigns.
Keep customer context explicit
- Call data: this telephone route does not map Five9 call variables, contact records or transcripts into Voiceflow. Five9’s KVList send/receive controls require additional configuration and a compatible data exchange; entering a phone number does not provide it.
- Identity: caller ID is not account authentication. Use your own trusted service to verify requests before returning protected customer data.
- Continuation: use the separate human-support number below for a requested transfer. Test Five9’s configured return/interruption behavior; do not assume a transferred call resumes the original IVR.
Human agent hand-off
Transfer callers to a separate Five9 number that reaches a staffed queue.
Prepare the Five9 human route
Give the return number its own inbound campaign/IVR path that bypasses the AI branch. This must be an externally reachable Five9 number: an internal loopback number cannot receive a call from Voiceflow.
Route to the receiving skill
In the return IVR, connect Incoming Call → Skill Transfer. In Skill Transfer → Skills, select the receiving human queue. Do not leave Skills empty: Five9 then routes to the unassigned Default queue. Use a single queue when that is the intended destination.
Configure unavailable-agent handling
In General, set Max Queue Time, the options for busy and not-ready/logged-out agents, and the voicemail or subsequent-module path on timeout. Connect the module’s error branch to a deliberate fallback. Test with no agents ready as well as an answered call. See Skill Transfer settings.
Confirm the external entry
Assign the human-support number under the return campaign’s DNIS tab, select this IVR and start the campaign. Call the number directly. Confirm it reaches the human queue without playing the AI-entry menu before configuring Voiceflow.
Configure Call forward
Use Call forward when the caller requests a person or needs an action outside the AI agent’s supported tasks. Set the destination to the dedicated Five9 human-support number, not the public number that routes to AI.
For inbound calls, Caller ID passthrough is off by default, so the receiving Five9 route can see the Voiceflow line rather than the original caller number. Enable it only when you want to pass through the caller ID Voiceflow received, and test the result through both telephone legs. The first Five9 transfer may already have changed it; caller ID remains separate from customer authentication.
Studio
Open the phone agent's transfer tool
In Agent studio, select the test Environment and open Agent → Call forward. Enable the tool and choose Phone number.
Set the human destination
Enter the dedicated Five9 return number with its country code. Describe the requests that require a person, then close the editor to return to the agent.
Test with an answered call
Use a connected telephone line for the transfer check below: prototype test calls cannot forward.
Code
Save this configuration as transfer.json, replacing the illustrative number with your actual human-only Five9 number. Updating the tool replaces its settings; preserve existing extension, message or caller-ID options if you use them.
Read the agent back, confirm the return number, compile the test Draft and place a real call through Five9. A successful PATCH or CLI exit does not prove the receiving queue answered.
Set callerIDPassthrough to true for the optional inbound behavior described above; the example retains the default.
Understand what crosses the transfer
Test by calling through the Five9 test number and asking the AI for a person. Have a teammate answer the human queue; confirm two-way audio and that the AI stops speaking.
- Queue selection: Five9’s receiving IVR and Skill Transfer module choose the queue. Call forward dials a phone number, not a Five9 queue ID.
- Customer context: this phone transfer does not deliver an automatic summary, transcript or Five9 call variables. Have the human confirm the case reference, or implement a separately authorized business-system context exchange.
- Failures: a rejected forward can end the call; this path does not expose an automatic Voiceflow busy/no-answer recovery branch. Test the destination’s closed-hours and unavailable-agent behavior.
Adding agent assist
Give staff policy guidance and reply drafts beside Five9 Agent Desktop Toolkit Plus in their CRM.
This is an on-demand assistant, separate from the caller’s phone session. Staff ask a question and review the suggestion before speaking or sending it to the customer. The recipe does not listen to calls, transcribe audio or send customer replies automatically.
Use a separate assistant with only read-only Knowledge/Playbooks and no customer-mutating tools or Workflows. The staff endpoint authorizes case access; it does not restrict which tools the agent can execute.
Prepare the staff assistant
Studio
Open a separate staff-assistant project in Agent studio → Agent → Instructions. Tell it to answer the staff member, use approved Knowledge and label suggested customer replies. Keep the assistant read-only; the application below does not propagate staff permissions into agent tool calls.
Publish to a dedicated test Environment. Give your integration developer the project ID and Environment alias, and provision a server credential through your team’s secret-management process. Obtain the authenticated application URL and approved CRM deployment before continuing below.
Code
Your Voiceflow builder or integration developer prepares a separate Chat project with at least one task Playbook and approved Knowledge, sets staff-facing Instructions and publishes its test Environment. Use the agent-assist setup guide for the project and context workflow, Agent v2 to configure it and Publish Environment to create its Published version. Read the agent back and confirm every attached tool/Workflow is read-only; Instructions alone do not restrict tool execution.
Set VF_ASSIST_PROJECT_ID to that separate project’s ID, VF_ASSIST_ENVIRONMENT_ALIAS to its published test Environment and VF_ASSIST_API_KEY to a server-side personal/service credential authorized to read/run that project. Keep these separate from the phone project’s configuration. Have the builder verify an approved policy answer before connecting staff. Download assist.mjs and client.mjs. Mount the handler as a same-origin POST /api/agent-assist route in your Node.js 22+ staff application:
Implement requireStaff(request) with the application’s verified staff session. Implement loadCaseForStaff(staff, caseId) against your trusted case service: return {id: caseId, context: approvedText} only if that staff member can read the case; otherwise return null. Set the allowed fields on the server. A Five9 sign-in or browser-supplied case ID is not authorization to your case service. Apply your host’s CSRF protection for cookie sessions.
The handler starts an isolated Voiceflow session, sends launch, then streams the staff question with the authorized context. Voiceflow credentials and runtime session keys stay on the server. Build a case picker from the staff member’s authorized cases; a Five9 telephone transfer does not populate it automatically.
casePicker, questionInput, askButton and output are elements in your application’s UI. Populate the picker through an authenticated case-list endpoint; reauthorize each request in the handler. Clear its selection and any pending answer when staff finish or change the case. Render suggestions with textContent, not innerHTML.
Add assistance beside Five9 in your CRM
The Five9 CRM SDK embeds Agent Desktop Toolkit Plus (ADT) inside a CRM web page. Your developer places the authorized Voiceflow assistant beside ADT in that page. This is not an arbitrary application embedded into the standalone Five9 desktop.
Prepare the authenticated staff workspace
The integration developer deploys the staff application over HTTPS, mounts the assistance endpoint and provides a case picker backed by your trusted case service. The Five9 administrator supplies the account’s regional ADT URL, assigned staff account, station and test campaign. Confirm staff can sign in to the CRM and read only their permitted cases.
Keep the existing Five9 desktop integration
Use Five9’s basic CRM integration to host ADT. If your CRM already owns Five9’s search, screen-pop and logging callbacks, add the assistant beside that existing integration. A second crmApi().registerApi(...) owner can interfere with the original callbacks. The manual case picker below needs no new Five9 callback registration.
Studio
Ask your integration developer to deploy this workspace and share the HTTPS URL. Sign in with your pilot Five9 account and your CRM account, choose the test case and request a suggestion. Five9 sign-in alone does not grant access to the case service.
Code
For an existing ADT host, keep its current setup and add your assistant UI beside it. For a new host, Five9’s US example uses this iframe; replace the host with the regional URL confirmed by your administrator:
When creating a new CRM integration, also implement the search, screen-pop and logging callbacks required by the Five9 tutorial. Load its documented five9.crm.sdk.js, obtain window.Five9.CrmSdk.crmApi() and call registerApi(...) from the CRM’s single callback owner. Use real CRM operations, not the tutorial’s mock records. Keep that Five9 integration separate from the Voiceflow case authorization and assistance endpoint above.
Test the staff workflow
Take a pilot call through ADT. Select an authorized CRM case and ask for policy guidance; confirm the reply stays staff-facing. Change cases during a response: the old request must abort and its output must clear. Have staff review drafts before speaking or sending them to the customer.
Keep assistance separate from call control
- Case selection: this example uses an authorized CRM case, not an automatic Five9 transcript feed. An external telephone transfer does not populate the case picker.
- Read-only scope: the assistant suggests answers; it does not change Five9 records, transfer the live call or submit a customer reply.
- Browser messages: if you add Five9 SDK events, use the documented SDK lifecycle and preserve the CRM’s callback owner. A browser event is not staff or case authorization.
Testing and launching
Prove the telephone and staff-assistance paths before routing customer traffic.
Compile and call the test Draft
Studio
After changing the agent, run a test from Agent → Run. Keep the isolated phone line assigned to the test Environment’s Draft, then place a real call through the Five9 test number. Studio’s test conversation alone cannot verify external telephone routing.
Code
Compile after agent or tool edits. The line assigned earlier must target this same Environment’s Draft:
Confirm the compile succeeds, then call the Five9 test number. This is the phone path; creating a text runtime session is not an equivalent test.
Exercise the complete journey
- Self-service: a policy question and a real test-order question reach the intended Playbook and produce spoken replies.
- Human agent hand-off: a request for a person reaches the human-only Five9 number, a teammate answers and both parties can hear each other. Confirm no route loops back to the AI branch.
- Unavailable destination: exercise the Five9 module’s error/return handling and the human queue’s closed-hours handling separately.
- Caller exit: hang up during the AI conversation; verify the telephone leg ends. Check that the external destination does not leave a connected call leg behind.
- Agent assist: confirm sign-in, allowed/denied case access and clearing a pending answer when changing case inside the actual authenticated CRM workspace.
Publish and retain rollback
Studio
In the test Environment, choose Publish, enter a release name and publish the tested configuration. Open Phone numbers, select the connected line’s Environment assignment, change Draft to Published and save. Keep the intended Environment selected.
Code
Publish only after the Draft telephone checks pass. This creates a release and updates that Environment’s Published version:
Check the returned release/Environment, then read the phone line back using the API or CLI get command above. Confirm phoneNumber.voice.version is published with the intended project and Environment alias. Publishing alone does not change a Draft line’s assignment. The API procedure reuses assignment.json from Routing calls to Voiceflow.
Call the Published line again before changing the public Five9 number to the approved IVR script. Retain the previous Five9 IVR script and DNIS/campaign assignment and the prior Voiceflow release so the administrator can restore routing if the live test fails.
Use the shared Test and launch your integration guide for the release handover.