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.
Examples of when to use Zendesk
Use the integration to keep customer requests and the information needed to resolve them together:
- Import help articles — import Help Center articles into Knowledge for the agent to use in its answers.
- Record a request for follow-up — collect the customer’s details and create a ticket for your support team to handle later.
- Continue an existing case — retrieve a ticket the customer may access, update its status or add an internal note.
- Human agent hand-off — continue the live conversation in Zendesk Agent Workspace with its customer context.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add the catalog action
For an agent attachment, if the chosen action’s integrationToolID is null, add it to the catalog. This example adds Find ticket:
Keep the returned integrationToolID. Adding the catalog definition does not attach it to the agent or authorize Zendesk.
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.
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:
successreports whether the action completed without an error;errorcontains the failure reason when it did not.output.datacontains the Zendesk result whensuccessistrueandtruncatedisfalse. On failure,outputisnull. The record shape depends on the action.truncated: truemeans 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.latencyMsmeasures 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: inspecterror;outputisnull. 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,ENVIRONMENTand 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.
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.
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.
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.
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:
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.
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.
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 inspect document.chunks and document.metadata:
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.
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.
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.
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
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.
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.
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:
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.
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.
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.
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
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.
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.
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:
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,solvedorclosed.priority:low,normal,highorurgent.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 thefieldsinput 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:
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.
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.
Set the callback and subscriptions
Set Webhook endpoint URL to:
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.
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.
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 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.
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.
Store the Sunshine connection
A successful response reports Integration sunshine connected. Verify a real exchange after configuring the Workflow.
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.
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.
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.
Store the Sunshine connection
A successful response reports Integration sunshine connected. Verify a real exchange after configuring the Workflow.
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 with --cursor when more results or blocks remain. Read the step’s current content and links before editing.
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.
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.startedbefore sending messages. - Render incoming
action.traceevents with typelive-agent-handofffor the active conversation. - Send customer text with
action.send, usingaction.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:
- Request an upload slot from
POST https://general-runtime.voiceflow.com/v1/handoff/file-storagewithprojectID,userID,versionID(the active Environment alias),fileNameandfileType. The session must already have an active handoff. - POST a multipart form to the returned
url, including every returnedfieldsentry and the file. Confirm the upload succeeded before sending the action. - Send
action.sendwithaction.type: "live-agent-handoff"andpayload.type: "file_upload". Itsfilesarray contains the uploaded object key asid, plusname,sizeand MIMEtype. Sunshine processes only the first file in that array; send one attachment per action. - Render
action.tracepayloads withevent: "file_received"using theirfile.url,file.nameand optionalfile.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.
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 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.
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:
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
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.
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:
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
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.
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.