Build with

Overview

Voiceflow integrates with Zendesk so your AI agents can resolve customer requests using ticket history, customer records and Help Center articles, then bring in your support team when needed.

Studio

In Agent studio, choose the connection for your task: ticket tools, Help Center import or Sunshine Conversations handoff.

Code

Use Voiceflow’s API or CLI to execute Zendesk actions from your backend or attach them to an agent or Playbook.

Requests use https://realtime-api.voiceflow.com, a Voiceflow API credential, a project ID and an Environment alias. Authorize ticket tools and inspect their schemas before calling a ticket action. Verify imported Help Center content with a Knowledge Base diagnostic query; asynchronous human replies use the Chat handoff event contract.

Attach the Zendesk actions your support agent needs. Photo:

Examples of when to use Zendesk

Use the integration to keep customer requests and the information needed to resolve them together:

Choose ticket tools to work with support records, Help Center import to answer from articles, or Sunshine Conversations for live support. Each uses its own authorization; ticket-tool OAuth does not connect the other two.

Connecting ticket tools

Authorize Zendesk actions that read and update support records.

You need a Voiceflow project you can edit and access to the Zendesk resources your actions will use. Ticket tools use Zendesk OAuth and your Zendesk subdomain. Help Center import and Sunshine handoff have their own setup below.

Ticket tools act through the connected account. Before exposing existing tickets to a customer-facing agent, implement the customer-to-ticket access check; the connection itself does not verify the chatting customer’s access.

Connect and prepare actions

Studio

1

Open the Zendesk connection

In your project’s left sidebar, open More → Integrations and click Connect on the Zendesk card. You can also open Manage from an attached Zendesk tool.

In your project’s left sidebar, open More → Integrations, then select Connect on Zendesk. Photo:
2

Authorize your Zendesk account

Enter your Subdomain URL, select Connect and complete the Zendesk authorization in the browser. Use the account containing the tickets, users and organizations you intend to access.

Enter your Zendesk subdomain, then select Connect to authorize the account in your browser. Photo:
3

Add an action to your agent

Return to Agent, click + beside Global tools and select the Zendesk action you need. Open the attached tool to write its Trigger, review the inputs and configure Capture response when you need the result later.

The tool editor displays Zendesk is connected when its connection is available. Run a test action and verify its result before relying on it in a customer conversation.

Code

Zendesk ticket tools require browser OAuth before API or CLI execution. Complete this setup in Voiceflow once for the account you intend to use; the generic Connect integration API does not replace it.

1

Open Zendesk in Agent studio

Open Agent studio in your browser and select the Voiceflow project you’ll use with the API or CLI. In the left sidebar, expand More if needed, select Integrations, then click Connect on the Zendesk card.

In your project’s left sidebar, open More → Integrations, then select Connect on Zendesk. Photo:
2

Authorize the Zendesk account

Enter your Subdomain URL, select Connect and complete Zendesk’s authorization in the browser. Use the account containing the tickets, users and organizations your calls will access.

Enter your Zendesk subdomain, then select Connect to authorize the account in your browser. Photo:
3

Confirm the connection and continue in code

Return to Integrations and check Zendesk’s Connected status. Continue below to prepare the Voiceflow credential and inspect the action schema. A stored connection does not verify an action; check its returned result when you make the first call.

Use a Voiceflow bearer credential with access to the project and Environment. Set these values in your shell before using either interface:

Both curl and the CLI read VF_TOKEN; a CLI sign-in is another option for CLI-only work. The CLI examples request JSON output so returned provider fields are retained. Keep this token on your backend or development machine, outside customer-facing browser code.

Standalone action calls need the connection and schema, not a tool attachment or compilation. After discovering the actions, go straight to Creating tickets or another action. Steps 2–4 below are for making an action available to the agent. Use a current Voiceflow CLI with integration add-tool and workflow update-step support for the CLI procedures.

1

Discover the available actions

Inspect the selected Environment’s action schemas before constructing inputs:

Read tools[].toolName, inputs and integrationToolID. A null ID means the catalog action has not been added to this Environment; it can still be executed directly. connected reports stored connection keys, not whether Zendesk will accept the current credentials. Standalone execution uses the Environment’s Draft and its Draft connection override when present, otherwise the Published connection.

2

Add the catalog action

For an agent attachment, if the chosen action’s integrationToolID is null, add it with the API. This example adds Find ticket:

Keep the returned integrationToolID. Adding the catalog definition does not attach it to the agent or authorize Zendesk.

3

Attach and configure the action

Save this test-agent attachment as zendesk-tool.json, replacing YOUR_INTEGRATION_TOOL_ID with the Find ticket ID from the previous step. Its descriptions guide the agent; they do not enforce ticket access. For customer-facing reads, enforce the access check before executing the action.

Create the attachment once:

target: {"global": true} attaches it to the agent. For one Playbook, use target: {"playbookID": "YOUR_PLAYBOOK_ID"} instead. Set description to explain when to call the action; inputVariables configures what the agent must supply. Create tool also accepts captureResponse when later actions need the result. Inspect a real result before choosing response paths.

4

Verify the agent's use of the action

Compile the Environment’s Draft after editing the attachment:

A successful compile returns message and durationMs; it does not publish the Environment. Then run a Draft test conversation asking about a ticket you can inspect. Check that the agent calls Find ticket with that ID and uses the returned record. The standalone examples below test individual actions; they do not verify agent routing.

Use the returned data

Studio

Use Capture response on the attached tool to retain a result for later steps. Run the action and inspect its actual result before configuring an object path; the returned fields differ by action.

Code

For standalone calls, check the execution envelope before reading output:

  • success reports whether the action completed without an error; error contains the failure reason when it did not.
  • output.data contains the Zendesk result when success is true and truncated is false. On failure, output is null. The record shape depends on the action.
  • truncated: true means the output or error exceeded 64 KB. A shortened output arrives as a JSON string rather than an object; do not treat it as a complete structured record.
  • latencyMs measures execution time around the call.

HTTP 200 and a zero CLI exit status alone do not establish action success. For an agent attachment, use captureResponse to map verified result paths into variables. The Zendesk action reference and execution contracts own the exact schemas.

Test safely

Ticket creation, comments and updates change data in Zendesk. Use a test account or your team’s test-data process. After a timeout, inspect Zendesk before retrying: a failed or missing response does not prove the write did not occur. The examples on this page use illustrative Northstar Supply records; replace their IDs and values with your own test data.

Manage or repair the Zendesk connection

Check the account and reconnect in your Voiceflow project's integration settings.

Studio

In the same project, open More → Integrations. Manage on a connected Zendesk card opens its disconnect confirmation; it does not edit the saved account. To replace the connection, review the affected scope in that confirmation, select Disconnect, then Connect on Zendesk and authorize the intended account. Actions using the disconnected account fail until it is reconnected. Verify a read such as Find ticket before retrying a write.

For a failed action, check the selected project, required inputs and the actual Zendesk record. Tool authorization and Help Center import are separate; repair the connection used by the failing capability.

Code

  • HTTP failure: inspect the status and response body before reading an execution envelope. A mismatched integration/tool name is rejected before execution. Unknown brace tokens such as {customer_id} are also rejected: a standalone run has no conversation variables. Pass the actual value; only existing project secrets can be substituted in top-level string inputs.
  • HTTP 200 with success: false: inspect error; output is null. Check the required inputs, account-scoped IDs and provider authorization. A timeout does not establish that a write failed—inspect the record before retrying.
  • Unexpected account or record: verify PROJECT_ID, ENVIRONMENT and the Draft/Published connection used by the standalone run. A stored-connection flag alone does not validate the credentials.

To replace the ticket connection, open Agent studio, choose the project identified by PROJECT_ID, then open More → Integrations. Select Manage on Zendesk, review the disconnect confirmation and affected scope, then select Disconnect. This interrupts actions using that connection. Select Connect on Zendesk and complete browser authorization for the intended account. Check Zendesk is connected, then rerun Find ticket before retrying a write. The initial connection steps show the navigation and authorization dialog without leaving Code.

The generic disconnect endpoint rejects Zendesk’s service-owned credentials. Ticket tools, Knowledge import and Sunshine handoff use distinct connections; repair the one used by the failed operation.

Import help articles

Import Zendesk articles so your agent can answer from your support knowledge.

Help Center content enters Voiceflow through the Zendesk Knowledge source, separately from ticket-tool authorization. Its import controls let you select a brand and filter articles by language, category, labels and user segments. You can preserve the Zendesk structure and import article metadata.

Import and check your articles

The Help Center connection requires browser authorization in Agent studio. Complete it once for the Help Center you will import; the ticket-tool OAuth connection does not authorize this import.

1

Open Knowledge base in Agent studio

Open Agent studio and choose the project that will use these articles. In Code, this is the project identified by PROJECT_ID. In the sidebar, open Build → Knowledge base, then Add data source → Zendesk.

Open Knowledge base in the project that will use your Help Center articles. Photo:
2

Authorize your Help Center

Enter its Subdomain URL, select Connect and complete Zendesk authorization in the browser. The Import from Zendesk dialog is the next configuration screen.

Authorize the Help Center separately from the ticket tools. Photo:
3

Choose and import your articles

Select the required Brand. Narrow the selection with Locales, Categories, Labels and User segments, then check the matching article count on Import data sources. A failed count or a zero match prevents importing; correct the connection or filters first. Choose the destination Folder, organization and refresh settings described below, then select Import data sources.

Select the brand and article filters before starting the import. Photo:

Studio

Find an expected article in Knowledge base and open its content after processing completes. Test a question covered by that article with Knowledge retrieval available to the agent, then compare the answer with Zendesk’s source article.

Code

After the browser import, return to your terminal. Verify the imported documents in the same project and Environment before using their content:

1

Find an imported article

List the Knowledge documents and locate an article you selected in the import:

The response contains documents[]. Select the article’s id and wait for status.type: "SUCCESS" before testing retrieval; PENDING and INITIALIZED are not completion, and ERROR needs investigation. Use Read document for its chunks and metadata.

Set DOCUMENT_ID to the returned article ID, then read its content:

Inspect document.chunks and document.metadata.

2

Check retrieval against the source

Ask a question covered by one of the imported articles. This example retrieves Draft chunks without synthesizing an answer:

Read answer.chunks[] and compare each chunk’s documentID, source and content with the imported article. With synthesis: false, answer.output is null; an empty answer string is not the retrieval success check. This query is a build-time diagnostic, not the agent’s runtime retrieval endpoint.

Choose how imported content is organized

Configure these controls in Import from Zendesk before starting the import:

  • Preserve Zendesk structure groups articles by language, category and section within the selected folder.
  • Import Zendesk metadata adds article category, section, tags, labels and language. These keys replace matching metadata entered in the import form.
  • LLM chunking strategy controls preparation for retrieval. For example, Smart chunking groups content by topic; Keep each document in one chunk retains the article together, except documents over approximately 30,000 characters. Inspect the resulting chunks before relying on a strategy.
  • Refresh rate defaults to Never. Daily, Weekly and Monthly are scheduled alternatives when the workspace has the Knowledge refresh entitlement. The control is disabled without that entitlement.

Keep imported articles current

A Zendesk source entry groups and manages its imported articles. Its filters determine which articles remain in that source: the next sync can remove articles that no longer match. Importing a source also adopts existing Zendesk documents that match its filters. Review the brand and filters before changing them.

If Knowledge base instead lists separately imported articles without a Zendesk source entry, open the individual article to manage its refresh. The source-level Filters, Excluded documents and Restore controls below belong to a Zendesk source entry.

Update a Zendesk source

Change article filters, sync the source and restore an excluded article.

Open Agent studio, choose the same project, then open Build → Knowledge base and select its Zendesk source entry.

1

Review and save the source filters

Open Settings → Filters. Select the intended brand, locales, categories, labels and user segments, then close the dropdown to save each selection. They apply on the next sync; check which articles they will retain.

2

Sync and inspect the result

Open the source’s More menu and choose Re-sync, or wait for its configured Refresh rate. Wait for syncing to finish, then check the document list and open a changed article. A sync failure requires repairing the Knowledge connection before trying again.

3

Restore an excluded article

In Settings → Filters → Excluded documents, select Restore beside the article. Sync again and confirm the article returns if it still matches the filters. Source-level metadata and chunking changes apply to newly added documents; existing documents retain their own metadata and prepared chunks.

Code

The provider’s import settings are managed in this GUI. After syncing, return to Code and run the document and retrieval checks against the updated content. Keep the document ID returned by Voiceflow; the Zendesk article ID is not interchangeable with it.

An expected Help Center article is missing

Check the Knowledge connection, selected brand and article filters.

Studio

Confirm that the Knowledge connection targets the intended Help Center. Review the brand, languages, categories, labels and user segments used for the import. Find the article in Zendesk, then compare it with the imported content in Voiceflow. A connected ticket tool does not establish that a Knowledge import ran.

If the article is present but the answer is wrong, inspect its actual content and the agent’s Knowledge retrieval configuration before importing it again.

Code

List the Knowledge documents in the requested project and Environment and check whether the article was imported. If it exists, inspect its status, chunks and metadata, then run the retrieval check against a question covered by the source article.

If it is missing, follow the Help Center authorization and article-selection steps in this Code view. Open Agent studio in the same project, then Build → Knowledge base → Add data source → Zendesk to repair that Knowledge connection and check the selected brand and filters. A successful ticket action does not establish that Knowledge import ran. Compare the returned chunks with the source before retrying an import.

Creating tickets

Capture a customer’s request as a new Zendesk support ticket.

Create ticket requires subject, description, requesterName, requesterEmail and comment. Put the issue and requested outcome in comment, which becomes the first ticket message; description does not replace that comment. priority and account-specific custom fields are optional. The connector creates the ticket with status new and returns the created ticket result.

Configure ticket creation

Studio

Review the ticket inputs and describe when the agent should create a ticket. Photo:
1

Add Create ticket

Add Zendesk → Create ticket to the agent’s Global tools or to the relevant Playbook. In its Trigger, describe the customer request that should create a ticket and require confirmation before the write.

2

Supply the request details

Have the agent collect the requester’s name and email, a subject, a description and the initial comment. For a deterministic Workflow, choose Create ticket in an Integration step and map these inputs from fixed test values or conversation variables.

3

Run and verify one ticket

Test a confirmed support request. Open the resulting ticket in Zendesk and check its requester, subject, comment and status. If using Capture response, inspect the returned result before selecting the path to the ticket ID.

Code

Use the prepared project and action schema. This example creates one ticket with illustrative Northstar Supply details:

Check success: true, error: null and truncated: false before reading the created ticket at output.data. An illustrative, abridged result looks like this; the IDs and timing are example values:

Created ticket — abridged example

Retain output.data.id for later actions. Confirm the record and its first comment in Zendesk once; repeating a successful create call can create another ticket.

Follow a damaged-item request

Connect the customer's request, ticket reference and later status check.
1

Record the confirmed request

Maya asks for a replacement for the broken mug in order NS-1042. Confirm those details, then create the ticket shown above. Creating a ticket records the request; it does not issue a replacement.

2

Give the customer the ticket reference

After creation succeeds, confirm the reference to Maya. Have your application retain the actual returned ticket ID with its verified customer record. The example ID 8422 is illustrative.

3

Continue the same case

When Maya returns, verify her identity and ticket access before retrieving the ticket. Share the permitted status information; keep internal notes private. If she needs a live exchange with your team, use Sunshine handoff rather than creating another follow-up ticket.

Ticket creation best practices

Collect the details that let a support teammate continue the request.
  • Confirm the customer’s identity and request before creating the ticket.
  • Distinguish a new request from an existing ticket so the agent chooses creation or update deliberately.
  • Include the customer’s requested outcome in the description and the relevant conversation context in the comment.
  • Review any ticket already created before retrying a failed or timed-out call.

Finding and updating tickets

Retrieve a known ticket and change its status, priority or assignee.

Find ticket requires ticketID and returns that ticket. It is an ID lookup, not a general ticket search. Update ticket requires ticketID and accepts optional status, priority, comment, assignee and custom fields. The assignee is an email address.

Verify the customer’s ticket access

These actions use the connected Zendesk account; they do not verify that the chatting customer may access the supplied ticket. A ticket ID, email address or tool Trigger is not an access check.

Studio

Have your application’s implementing team verify the customer and which ticket they may access. Obtain the permitted ticket ID from that flow before running the Integration step. Do not let an agent-selected ID bypass that check. Use your team’s test ticket while configuring the action.

Code

On your backend, authenticate the customer and check their access to the requested ticket before calling Find ticket or Update ticket. Pass the permitted ID to the action; reject an unauthorized request before execution. Use a ticket from your team’s test account for the examples below.

Read before changing a ticket

Studio

Use the existing ticket ID and configure the fields the agent may update. Photo:
1

Read the existing ticket

Add Find ticket to the verified flow and supply its permitted ticket ID. Inspect the found ticket before allowing an update; do not replace that ID with one supplied in chat.

2

Configure the intended change

Add Update ticket and describe in its Trigger when a change is appropriate. Supply the same ticket ID and only the fields you intend to change. For a Workflow, use separate Integration steps to retrieve and update the ticket.

3

Verify the update

After testing, open the same ticket in Zendesk and confirm the changed field. Configure Capture response if later steps need the current status.

Code

Read the ticket before changing it. Replace the illustrative ID with the permitted ticket ID from your backend’s access check:

Inspect the returned record, then update that same ticket:

After a successful, untruncated execution, read the ticket at output.data and verify its ID and status. Confirm the status on the same ticket in Zendesk. A ticket ID from another account is not interchangeable with one in the connected account.

Choose the ticket fields to update

Use the accepted status and priority values and the connected account's custom fields.
  • status: new, open, pending, hold, solved or closed.
  • priority: low, normal, high or urgent.
  • assignee: the Zendesk assignee’s email.
  • comment: a comment to add as part of the update. The dedicated Add ticket comment action explicitly creates an internal note.
  • fields: custom fields for this account. The action schema identifies the fields input but does not enumerate Zendesk field IDs or dropdown options.

Zendesk determines whether a requested change is permitted for that record and account. Inspect action errors before reporting success.

Code

For Create ticket or Update ticket, inputs.fields is an object whose values are Zendesk custom-field objects, rather than a flat field-name/value map:

Custom field inside inputs — example

Replace the example field ID and value with those from the connected account. Use Zendesk’s ticket-field API to discover IDs and options; those requests use Zendesk authorization, not your Voiceflow bearer token. Do not infer provider field IDs from get-schema.

Human agent hand-off

Pass the conversation and customer context to Zendesk Agent Workspace.

Zendesk live-agent handoff uses Sunshine Conversations to pass the conversation to Zendesk Agent Workspace. It is a live message exchange, separate from creating a support ticket for later follow-up.

  • Customer identity: use a stable End user ID. Sunshine reuses an existing personal conversation for that identity, so a later handoff can return to the same conversation rather than always creating a new ticket.
  • Context visibility: a full transcript or custom context is posted as a conversation message attributed to the customer. It is not a private internal note. Include only content suitable for that conversation.
  • Files: customers and support teammates can exchange attachments during the live handoff. This is separate from the ticket comment tool, which adds an internal text note.

Configure the Sunshine reply webhook

Your Sunshine app needs an Agent Workspace switchboard integration and a webhook that sends human replies and conversation-ending events to Voiceflow. Connecting Sunshine in Voiceflow stores credentials; it does not create this webhook. Complete the provider setup before saving the Voiceflow connection in either Studio or Code.

1

Open the Sunshine conversations integration

In Zendesk Admin Center, open Apps and integrations → Integrations → Conversations integrations. Create a conversations integration for Voiceflow, or edit its existing webhook. Use a Sunshine Conversations integration, rather than a Zendesk Support webhook.

2

Set the callback and subscriptions

Set Webhook endpoint URL to:

Sunshine callback URL

Under Webhook subscriptions, select:

  • conversation:message — delivers the support teammate’s messages and attachments.
  • switchboard:releaseControl — tells Voiceflow that the human conversation has ended.
  • switchboard:passControl:failure — tells Voiceflow that the handoff could not be completed.
3

Copy the webhook's shared secret

Save the conversations integration and copy its generated Shared secret. Use this value as Webhook secret in the Voiceflow connection below. Sunshine sends it in the X-Api-Key header, which Voiceflow checks against the stored value. The Sunshine API Key secret is a separate credential.

Zendesk’s conversations integration setup explains the provider controls. If you manage Zendesk configuration programmatically, register the same callback and subscriptions through the Sunshine Conversations webhook API.

Connect and configure handoff

Studio

In your project, open More → Integrations → Sunshine Conversations. Enter your Zendesk Subdomain, Sunshine App ID, Key ID, Key secret and the Webhook secret copied above, then select Connect. These credentials belong to the Sunshine connection, not the Zendesk ticket-tool OAuth connection.

Connect Sunshine Conversations separately from the Zendesk ticket tools. Photo:
1

Choose the support connection

In Build → Workflows, open the Workflow that will connect the customer to a person. Add or open its Handoff step, then select Sunshine Conversations as Handoff provider.

Map the customer and Zendesk routing fields in the Handoff step. Photo:
2

Map customer identity and routing

Set End user ID to a stable customer identifier and supply the customer’s User email, Customer name and Language as needed. Use Group ID, Brand ID and Priority to populate the Zendesk ticket’s routing fields. Group ID identifies a Zendesk group; it does not create a queue or assign a queue position. Accepted priorities are low, normal, high and urgent.

3

Choose context and continuation

Choose Handoff context: Full transcript, a Custom variable containing a string, or None. Connect the Failure path to a useful fallback. Enable and connect Return path if the customer should be able to return to the AI agent after human support.

Code

The Sunshine connection is independent of Zendesk ticket OAuth. You need its Subdomain, App ID, Key ID, Key secret and the webhook’s shared secret from the provider setup above. Use the Voiceflow bearer credential and project ID from setup.

Before the configuration calls below, create a Workflow containing a Handoff step in a block. The example reads and updates that existing step; it does not create the Workflow, connect its paths or attach it to your agent. Define the customer variables used in the configuration and connect the step’s failure and return paths before testing.

Save sunshine-connection.json outside your repository and replace the credential placeholders. Set webhookSecret to the generated shared secret of the Sunshine webhook, not the API key’s secret:

This call stores the project’s Published connection credentials; it is not scoped by ENVIRONMENT and does not publish a Workflow. Connecting reports that credentials were stored, not that a live exchange succeeded. Direct API and CLI clients can make this request; MCP clients must use the browser connection instead.

1

Store the Sunshine connection

A successful response reports Integration sunshine connected. Verify a real exchange after configuring the Workflow.

2

Read the Workflow and Handoff step

List Workflows to find its server-issued ID:

Read the chosen Workflow and locate its existing Handoff step in blocks[].steps[]:

Workflow lists return nextCursor; Workflow reads return truncated.nextCursor. Pass the returned value as the next request’s cursor when more results or blocks remain. Read the step’s current content and links before editing.

3

Set the Sunshine destination and customer mapping

Save sunshine-handoff.json. Replace the sample Zendesk group and brand IDs with your account’s IDs. The variable names in braces must already exist in your project; use the names that hold your actual customer identity.

Inspect unresolvedReferences and read the step back before testing. Unknown variable names can remain literal text. This patch leaves the step’s existing return/failure settings and links in place; verify that the Workflow reaches the Handoff step and its enabled exits lead to the intended blocks.

4

Compile and verify the configured path

Compilation prepares the Environment’s Draft; it does not publish it. Run a Draft test, then publish the reviewed configuration before testing the customer connection. Use the exchange checks below with a real support teammate.

Receive and send support messages

Studio

The Voiceflow Chat widget handles sending and receiving human-support messages. The exchange checks below verify the configured customer connection.

For your own Chat interface, switch to Code for runtime message handling.

Code

Implement the live-agent handoff runtime events in your custom Chat client. Register listeners before connecting and wait for the existing session to resume before sending customer messages.

  • Resume the existing Chat session with the Socket.IO connection and wait for client.started before sending messages.
  • Render incoming action.trace events with type live-agent-handoff for the active conversation.
  • Send customer text with action.send, using action.type: "live-agent-handoff", payload.type: "message" and the message text.
  • Follow the trace’s return configuration when offering return-to-AI controls; do not create a replacement session to resume the handoff.

Use the linked runtime reference for the complete connection example, event shapes and terminal states. Voiceflow manages the Sunshine Conversations relay; you do not need to deploy a Custom Handoff service for this connection.

Share files during handoff

Customer uploads are limited to 25 MB per file (26,214,400 bytes). Choose a smaller file before uploading if it exceeds that limit.

Studio

During the live conversation, use the Chat widget’s attachment control to send a file and have the support teammate open it in Agent Workspace. Have the teammate send a file back and check that the customer can open it. The Handoff step’s Configuration JSON can disable customer uploads with disableFileUpload: true; leave it unset or set it to false to allow attachments.

Code

A custom client must upload the file before sending its runtime action:

  1. Request an upload slot from POST https://general-runtime.voiceflow.com/v1/handoff/file-storage with projectID, userID, versionID (the active Environment alias), fileName and fileType. The session must already have an active handoff.
  2. POST a multipart form to the returned url, including every returned fields entry and the file. Confirm the upload succeeded before sending the action.
  3. Send action.send with action.type: "live-agent-handoff" and payload.type: "file_upload". Its files array contains the uploaded object key as id, plus name, size and MIME type. Sunshine processes only the first file in that array; send one attachment per action.
  4. Render action.trace payloads with event: "file_received" using their file.url, file.name and optional file.type. Confirm the human can open the customer upload and the customer can open the reply attachment.

Use the handoff action schema for exact file fields. The optional custom-client example below includes the upload sequence. Do not send provider credentials to the customer’s browser.

Verify the exchange

Publish the configured Environment and test through your customer-facing Chat connection. Confirm that the conversation reaches Agent Workspace with the intended requester, group and brand. Have a teammate reply and check that the customer receives the message. Exchange an attachment in each direction and confirm both can open it. Then check closure, the configured return to AI and a failed-connection fallback. If replies or closure never reach the customer, check the Sunshine webhook’s callback URL, subscriptions and shared secret. Saving the step or creating a ticket alone does not verify a live handoff.

Handle handoff in a custom Chat client

Resume the existing session, receive human replies and send customer messages.

Studio

The Voiceflow Chat widget handles the runtime connection. For a custom Chat interface, use the Code instructions in this section.

Code

Install socket.io-client in your application. Replace the placeholders with the active conversation’s project, user, Environment alias and session key. This example assumes public API access. For a private project, use an authorized trusted client and keep the project API credential on your server.

Resume the existing human conversation

Replace the log handler with your application’s message rendering. Gate return-to-AI controls on the handoff trace’s configuration and handle its terminal states using the Chat handoff event contract. An SSE turn cannot receive a human reply that arrives after that response has ended.

Working with ticket comments

Add an internal support note or retrieve the latest ticket comment.

Add ticket comment requires ticketID and comment. It writes an internal note (public: false) and returns the ticket update result. Find latest comment requires ticketID and returns the last comment from the ticket’s comment list. The note action does not send a public reply to the customer.

Use the permitted ticket ID for both actions. Internal notes can contain staff-only information; customer access to a ticket does not authorize disclosing every comment.

Add or read a comment

Studio

Add ticket comment writes an internal note to the selected ticket. Photo:
1

Add the note action

Add Add ticket comment to the agent, Playbook or Workflow. Supply the known ticket ID and the note your team needs, such as a confirmed replacement preference. Check that it appears on the correct ticket with internal visibility.

2

Retrieve the latest comment

Use Find latest comment when the agent needs the most recent ticket comment. Inspect the result before configuring Capture response. Internal notes can contain staff-only information; decide which details the agent may share.

Code

Add an internal note to a known ticket:

To retrieve the latest comment on that ticket:

After a successful, untruncated execution, output.data is the updated ticket for Add ticket comment and the comment object for Find latest comment. Verify the internal note on the correct ticket, and inspect the retrieved comment’s public value before sharing its text with a customer.

Finding users and groups

Retrieve a customer by email or a support group by ID.

Find user requires email. The runtime searches Zendesk with that email and returns the first user in the result. Find group requires groupID and returns that group. These actions read records; they do not create users or groups.

Retrieve the matching record

Studio

Use the customer's confirmed email for Find user. Photo:
1

Find the customer

Add Find user, collect the customer’s confirmed email and map it to email. Inspect the returned record before using it for ticket creation or personalization. A lookup result is not proof that the person chatting owns that email.

2

Find a support group

Add Find group and supply a known groupID for support routing. Configure Capture response when another step needs the user or group data. Verify the result against a record you can locate in Zendesk.

Code

Look up the customer by their confirmed email:

To retrieve a known support group:

After a successful, untruncated execution, output.data is the matched user or group. No match is an action failure, not a successful empty result. Confirm the returned record in Zendesk. An email lookup does not authenticate the person chatting, and Find group does not create a group.

Updating organizations

Change an existing organization’s details and routing settings.

Update organization requires organizationID. Optional changes include name, details, domainNames, externalID, groupID, notes, tags, sharedComments, sharedTickets, url and custom fields. It returns the updated organization result.

Use this action in a staff-controlled administration workflow. Organization routing and ticket-visibility changes affect more than one customer’s request; do not expose them as customer-selected changes.

Apply an organization change

Studio

Limit organization updates to the fields your workflow is intended to change. Photo:
1

Configure the organization update

Add Update organization to the relevant agent, Playbook or Workflow. Supply the Zendesk organization ID and only the intended fields. Give the tool a specific Trigger so unrelated requests do not change organization-wide settings.

2

Check the changed record

Run against an organization you can inspect, then open the same record in Zendesk and confirm the changed fields. Review visibility changes such as sharedTickets and sharedComments before enabling them.

Code

Update a known organization’s notes:

After a successful, untruncated execution, inspect the organization at output.data and confirm its notes in Zendesk. For fields, use the connected account’s organization-field IDs and object values; review sharedTickets and sharedComments before changing organization-wide visibility.

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