Build with

Overview

Voiceflow integrates with Talkdesk to resolve selected inbound calls, transfer callers to human queues and give staff an on-demand assistant inside Talkdesk Workspace. Keep your customer-facing Talkdesk number and choose which call-flow branches reach Voiceflow.

The phone connection uses a Voiceflow number and a separate Talkdesk number for human support. Staff assistance uses your authenticated application in a Workspace Designer card. Neither connection automatically imports Talkdesk customer records, call variables or transcripts into Voiceflow.

Examples of when to use Talkdesk

  • Answer inbound calls — route delivery and policy questions to a Voiceflow phone agent.
  • Human agent hand-off — send callers to a Talkdesk queue when they need a person.
  • Add agent assist — show reviewed policy guidance and reply drafts inside the staff workspace.
  • Test and launch — verify both telephone legs and rehearse routing rollback before moving customer traffic.

What you need

  • A Talkdesk administrator with Studio → View, Manage and Publish permissions, a pilot Incoming call flow and account-owned test numbers. Publish permission is required to assign numbers to flows. In Admin → Preferences, enable Single Device Mode, as required by Talkdesk Studio account settings.
  • A Voiceflow phone project, an editable test Environment and a connected phone number.
  • A separate externally dialable Talkdesk human-support number whose flow bypasses the AI branch.
  • For Code, cURL, jq and the current Voiceflow CLI with Agent v2 support. Set PROJECT_ID, ENVIRONMENT_ALIAS and a server-side personal or service key in VF_TOKEN. Configure CLI authentication with that key, or pass --token "$VF_TOKEN". This key does not authorize Talkdesk administration.

Choose the connection contract

External phone routing and an embedded staff assistant use different setup.

Talkdesk’s Forward to External Number uses SIP INVITE or REFER according to the account type; administrators cannot select the method. Its SIP target option does not establish a configured Voiceflow SIP connection. Follow Telephony for a separately verified SIP setup. The number-based procedure below does not send Talkdesk UUI headers or install a digital-message relay.

Preparing your voice agent

Resolve the supported customer requests before transferring callers to Talkdesk 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 Talkdesk number does not import company policies or create business-system tools.

Studio

1

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.

Connect the agent's instructions to the Playbooks, Knowledge and tools that resolve the caller's request. Photo:

The example retailer uses its own order lookup service. It is not a Talkdesk customer-record API.

2

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:

agent.json
Update the test agent

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 Talkdesk number and send a selected call-flow branch to the AI agent.

Assign the Voiceflow destination

Use a dedicated test line first. Your Talkdesk administrator needs the Voiceflow number and an externally reachable human fallback before editing the Talkdesk flow. Copy the full Voiceflow number, including the country code.

Studio

1

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.

Use this Voiceflow line as the external destination of the Talkdesk test branch. Photo:
2

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

Match the line's Environment and version to the agent you are testing. Photo:

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.

1

Find the connected line

List the workspace

Select the dedicated test line from phoneNumbers. Set PHONE_NUMBER_ID to its id, not its E.164 value. Keep value for the Talkdesk administrator and retain its current voice assignment for rollback.

2

Pin the voice side to the test Draft

Create assignment.json and assign the line

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.

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 Talkdesk administrator. The Talkdesk flow changes below use Talkdesk administration, not the Voiceflow credential.

Route the Talkdesk call-flow branch

In Talkdesk Studio, use a pilot Incoming call flow and test number. Record the previous flow/number assignment before editing. Keep a direct human-support option in the menu.

1

Add the external destination

Add Forward to External Number to the AI branch. In Preferences → External Number, choose manual configuration and enter the Voiceflow line using the country-code and phone-number controls. A variable destination must contain a complete E.164 number. Do not enter the Voiceflow phone resource ID.

2

Choose caller ID and failure handling

In Caller Configuration, select Other account number and an account number eligible for outbound caller ID. An inbound-only Do-Not-Originate number can be blocked by carriers. Contact number passes the caller number; Touchpoint uses the inbound contact point. Choose intentionally: the caller ID Voiceflow receives can differ from the original caller.

Set the external device’s maximum ring time. Connect No answer and Invalid Number exits to human support or a deliberate announcement. See Forward to External Number preferences and the forwarding example for these controls.

3

Publish and assign the pilot number

Save and publish the flow. Back on its Studio flow card, open No numbers → Manage numbers, select the test number, then Save → Confirm. A number belongs to one flow at a time; outbound flows cannot own numbers. If editing an already assigned flow, use its number dropdown. See assigning a flow to a number.

4

Call through Talkdesk

Call the Talkdesk pilot number, select the AI branch and confirm the intended greeting and two-way audio. Separately test each configured failure exit. A direct Voiceflow call does not verify the Talkdesk branch.

Keep customer context explicit

  • Call data: external-number forwarding does not map Talkdesk flow variables, records or transcripts into Voiceflow.
  • Identity: caller ID is not account authentication. Verify protected requests through your own trusted service before returning customer data.
  • Continuation: use the separate human-support route below; do not assume that forwarding resumes the original Talkdesk flow after the conversation.

Human agent hand-off

Transfer callers to a separate Talkdesk number that reaches a staffed queue.

Prepare the Talkdesk human route

Use a separate Incoming call flow and externally dialable Talkdesk number. Keep this path independent of the public menu’s Voiceflow branch so a requested transfer cannot loop back to AI.

1

Select the receiving queue

Connect the flow’s incoming call to Assignment and Dial. Configure its assignment to the intended Queue and set the waiting/agent-availability preferences. Have a pilot staff member sign in and become available in that queue. See Talkdesk call routing.

2

Handle unavailable staff

Connect No answer, Maximum waiting time reached and No match found to your chosen fallback, such as voicemail or an announcement. Unconfigured optional exits end the flow and hang up. Test busy staff and no matching available agents. If calls need a closed-hours route, configure a Time-Based Rules component before Assignment and Dial; account Business Hours alone does not route the call. See Assignment and Dial exits.

3

Publish and prove the human number

Save and publish this flow, then use its number dropdown → Manage numbers → Save → Confirm to assign the human-support number. Call that number directly and confirm a teammate answers without entering the AI menu. Give its full country-code number to the Voiceflow builder.

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 Talkdesk human-support number, not the public number that routes to AI.

For inbound calls, Caller ID passthrough is off by default, so the receiving Talkdesk 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 Talkdesk transfer may already have changed it; caller ID remains separate from customer authentication.

Studio

1

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.

2

Set the human destination

Enter the dedicated Talkdesk return number with its country code. Describe the requests that require a person, then close the editor to return to the agent.

Forward to the human-only Talkdesk number, never to the public number's AI branch. Photo:
3

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 Talkdesk number. Updating the tool replaces its settings; preserve existing extension, message or caller-ID options if you use them.

transfer.json
Set the human destination

Read the agent back, confirm the return number, compile the test Draft and place a real call through Talkdesk. 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 Talkdesk 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: Talkdesk’s receiving Assignment and Dial component chooses the queue. Call forward dials a phone number, not a Talkdesk queue ID.
  • Customer context: this phone transfer does not deliver an automatic summary, transcript or Talkdesk 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 configured hours and unavailable-agent behavior.

Adding agent assist

Give staff policy guidance and reply drafts inside their Talkdesk workspace.

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

Keep suggestions staff-facing and require human review before replying to the customer. Photo:

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 Talkdesk card 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:

Authorize the staff member and selected case

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 Talkdesk 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 Talkdesk telephone transfer does not populate it automatically.

Request a suggestion from the embedded application

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 the assistant to Talkdesk Workspace

Your developer deploys the HTTPS staff application and same-origin assistance endpoint above. Your Talkdesk administrator adds that application to the workspace using a Render Iframe card. Publishing a card alone does not display it: the card must be in a Panel rendered by an installed Canvas.

1

Prepare the application URL and staff access

Obtain the deployed assistant URL from the integration developer. The application needs its own staff sign-in, authorized case picker and case service. Its frame policy must allow the actual Talkdesk ancestor origins. Test authentication in the embedded browser context, including your browser’s third-party-cookie restrictions. Keep credentials out of the URL; Talkdesk variables are context hints, not staff authorization.

2

Create and publish the card

In the Talkdesk dock, open Workspace Designer → Cards → Create card. Enter a name and create the card. In Automation Designer, connect Card Trigger → Render Iframe. Open that component and set source to your assistant’s HTTPS URL. Enable Allow scripts and Allow same origin for the application and its same-origin endpoint; enable forms or popups only if your implemented sign-in requires them. This text assistant does not need microphone or camera access. Save, then save and publish the automation from its header. See Render Iframe and creating an iframe card.

3

Place the card in a Panel

Return to Workspace Designer → Panels, create or edit the pilot Panel, select Add card and use + to add the published assistant card. Size it for the staff workflow and save the Panel. See Panels.

4

Install and publish the call-workspace Canvas

Open Workspace Designer → Canvas. Install Conversations App Canvas Tab for the pilot users/roles; this Canvas appears during inbound and outbound calls. Edit its automation, connect Canvas Trigger → Render Panel, name the component, select the pilot Panel and save. Save and publish the Canvas flow. If your workspace already has a Canvas, preserve its existing cards and routing. See Canvas installation, Render Panel and publishing the Canvas flow.

5

Check the embedded staff experience

Take a pilot call in Talkdesk Conversations and open the Canvas tab. Sign in to the assistant, select an authorized case and request policy guidance. Confirm the suggestion stays staff-facing and denied cases remain inaccessible. If embedded sign-in is blocked, resolve the application’s frame/cookie setup before rolling out the card; staff can use its authorized standalone URL in the meantime. Change cases during a response: the old request must abort and its output must clear. Have staff review drafts before using them.

Keep assistance separate from call control

  • Case selection: use the application’s authorized case picker. This procedure does not automatically feed Talkdesk’s current call or live transcript into the assistant.
  • Read-only scope: the assistant suggests answers; it does not update Talkdesk records, transfer a live call or send a customer reply.
  • Authentication: a Talkdesk sign-in, iframe variable or browser message does not authorize access to your case service. The application must verify that access on every request.

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 Talkdesk 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:

Compile the test Draft

Confirm the compile succeeds, then call the Talkdesk 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 Talkdesk number, a teammate answers and both parties can hear each other. Confirm no route loops back to the AI branch.
  • Unavailable destination: exercise the Talkdesk flow’s No answer and Invalid Number exits and the human queue’s configured hours/availability 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 installed Talkdesk Canvas and authenticated assistant.

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:

Publish the tested Environment

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 Talkdesk number to the approved Incoming call flow. Retain the previous Talkdesk flow/number 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.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.