Overview
Voiceflow integrates with Kustomer so your AI agents can work with customer records and support conversations, answer from approved help articles, and bring in a human teammate. Connect Kustomer in the app, then add the actions your agent needs.
- Recognize a customer and use their authorized support history.
- Record a support request with the confirmed issue and the right assignee.
- Import help articles to ground answers in your support content.
- Human agent hand-off to continue a live Chat conversation with your team.
Helping your support teammates? Follow Kustomer agent assist to install a staff assistant in the Kustomer workspace. This manual covers the integration’s actions, Knowledge and customer hand-off.
Connecting Kustomer
Authorize the account and prepare its built-in actions.
Prepare the connection
A Kustomer administrator supplies the org slug and a server API key from Settings → Security → API Keys. For northstar.kustomerapp.com, the slug is northstar.
Grant only the Kustomer roles needed for your workflow:
Check the exact operation’s Authorization block in Kustomer’s API reference. Finding a record does not authorize every update to it. Keep the key on the server; never ask the customer or the agent model to provide it.
Studio
Open Kustomer in Integrations
Open your project in Agent studio. In the left sidebar, expand More, select Integrations, then choose Connect on Kustomer.
Save the account credentials
Enter Org name and API key, then select Connect. Webhook signing secret (optional) is needed for human hand-off; tools and article imports do not require it.
Connect Published first. If the connection offers a Draft override, use it for sandbox actions. Without an override, Draft runs use Published credentials. Changing the Environment does not by itself change the Kustomer account. Article imports use the Published connection.
Attach the first action
Return to Agent, select + beside Global tools, and choose Kustomer → Find customer. In the editor, set Trigger to explain when to look up the verified customer. Review its inputs and create a text variable kustomer_customer_id in More → Variables with an empty default. In Capture response, map customer.id into it after a successful lookup. Use that variable for a later customer action.
For a Playbook-specific action, add it to that Playbook’s tools instead. A connected account alone does not attach tools.
Check the customer lookup
Use a sandbox customer and run the action with an email you can inspect. Check the current result’s customer.id and the matching record in Kustomer. Then test a conversation that invokes the action; the agent should use that returned record, and offer your support fallback when lookup fails.
Code
Use a server-side Voiceflow API credential, cURL and jq. Set VF_TOKEN, PROJECT_ID and ENVIRONMENT in your shell; examples use ENVIRONMENT=main. For CLI calls, configure the same credential using the CLI authentication guide.
Save the following outside source control as kustomer-connection.json, with your actual slug and key:
This operation replaces the project’s Published connection. It has no Environment or Draft-slot selector. Use a separate test project for isolation; connecting through the API is credential storage, not a successful provider test.
Expect Integration kustomer connected. Then read the catalog and test an action using the workflow below. The catalog’s connected flag reports stored credentials, not whether Kustomer accepts them. Standalone execution uses the selected Environment’s Draft, with its Draft connection override when present and Published otherwise.
Execute an action
Save a request from the relevant section as request.json. Each request has a catalog toolName and typed inputs.
Check success, error, output and truncated, not just HTTP status. For example, a successful customer lookup returns the record at output.customer. Stop on failure or truncation; never treat a retained ID from an earlier call as current success. A timeout after a write leaves its outcome uncertain: inspect Kustomer before retrying.
Let the agent use the action
Add the catalog action
Read tools[].toolName, inputs and integrationToolID in kustomer-schema.json. If Find customer’s ID is null, add it once:
The CLI equivalent is vf integration add-tool --integration kustomer --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --tool-name kustomer_find_customer. Keep its integrationToolID; this operation does not attach it.
Create the attachment
Save this as kustomer-tool.json, replacing YOUR_INTEGRATION_TOOL_ID. This sandbox example lets the model collect an email; production customer-history access needs the identity check below.
Or use vf --output-format json tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" < kustomer-tool.json. For a Playbook, replace target with {"playbookID":"YOUR_PLAYBOOK_ID"}. Review existing attachments before repeating creation.
Compile and test a conversation
Or use vf environment compile --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT". Compilation prepares Draft; it does not publish. Run a Draft conversation, ask about the test customer’s profile, and verify the action inputs and returned record inform the reply. Repeat with an unknown email and confirm no earlier customer’s data appears.
Replace or disconnect the connection
Coordinate key rotation with Draft overrides, article refresh and active hand-offs.
In More → Integrations → Kustomer, manage the intended Published or Draft connection. Removing Published also removes its Draft override. Reconnect with the new key, then test a read and each required write before retiring the old key.
For Code, repeat the connect operation to replace Published. DELETE /v1/stable/integration/kustomer?projectID=…, or vf integration disconnect --integration kustomer --project-id "$PROJECT_ID", clears the stored Published and Draft slots. The stable deletion path clears credentials; the Studio/provider disconnect also stops Kustomer article refresh jobs. Before API deletion, set affected imports to Never in Knowledge and verify that scheduled refresh is stopped.
Replacing credentials does not update active hand-offs’ stored credentials. Finish those sessions before changing the callback secret. A same-org reconnect with an empty signing-secret field preserves the stored secret; supply a new value to rotate it.
An action cannot access Kustomer
Check the account, operation permissions and connection slot.
Check the org slug, key expiry and the exact operation’s roles. An accepted connection or populated catalog does not prove provider permission. Test a permitted read against a known record in the intended account. If Draft uses the wrong account, inspect its override and Published fallback. Fix credentials or access before repeating a failed write.
Finding and updating customers
Match a verified customer and keep their permitted profile details current.
Before returning a profile or support history, your application must authenticate the person and authorize the Kustomer record. An email match is a lookup, not identity verification. For production, the application developer creates verified_customer_email in More → Variables with an empty default, authenticates the customer, and supplies that email in the Chat action variables before the lookup runs. Obtain that variable mapping and an allowed/denied test account from the developer. Verify it through the actual signed-in application; Studio Run does not automatically receive backend identity. Instructions and Trigger text do not enforce the access policy.
Find customer tries email, phone, then external ID and returns the first match. Supplying several values does not require them all to match. Send one trusted identifier, then verify the returned ID belongs to the authenticated customer.
Studio
Configure the customer action
Add Kustomer → Find customer to the agent or Playbook. Insert {verified_customer_email} as the provided email value, disable model fulfillment for it, and keep the other lookup inputs unset. For a sandbox test, enter maya@northstar.example manually.
Use the matching record
Test the lookup and inspect customer.id. Create kustomer_customer_id in More → Variables with an empty default. In Capture response, map customer.id to it, then insert {kustomer_customer_id} in the next action’s customerID input and disable model fulfillment for that provided value. Clear the variable before a new lookup; only continue after the current action succeeds. Have the agent answer from the current permitted fields; if lookup fails, ask the customer to use your approved support route rather than disclosing another record.
Create or update after confirmation
Use Create customer only when your authorized lookup found no existing profile. Use Update customer with the verified customerID for confirmed changes. Collect the intended values, confirm the change, run the action once and inspect the same record in Kustomer. An API error after creation is not permission to create another profile.
Test a known customer, an unknown identifier and a denied customer. The agent must not expose data on a failed or unauthorized lookup. Test the create/update paths with disposable profiles and confirm the reply describes only the successful change.
Code
Save this as request.json and run the execution workflow after your backend’s identity check:
Use output.customer.id only after current success and the ownership check. To create or update, replace the request with the appropriate operation and confirmed values:
For agent use, add and attach the chosen action with input names from its schema. Populate identity from trusted application state rather than model guesses. In a Draft conversation, ask for the confirmed profile change and verify customer.id and the changed field before letting the agent report success. Simulate a missing match and provider failure; neither may reuse a previous result.
Set custom attributes
Use fields discovered from the connected Kustomer resource.
The tool editor loads the connected resource’s custom fields using org.permission.metadata.read. Configure only the fields needed for the task. Customer, conversation and company schemas can differ, as can Draft and Published accounts.
For a standalone Code request, custom uses objects with id and value, not a flattened provider payload. For example, an existing numeric field can use "custom":{"Customer tier":{"id":"tierNum","value":2}}. Replace the ID with your actual field name. Empty values are omitted; number and boolean field suffixes are converted before the Kustomer request. This is not a field-deletion interface. Discover and verify the field in your account before attaching it to an agent.
Creating support requests
Record a confirmed issue as a Kustomer conversation for your team.
Create conversation opens a support record for an existing customerID. It requires a name (the subject). Optional inputs are priority from 1 to 5, assignedUserID, assignedTeamID and custom attributes.
The action creates status open. It does not add an initial message or notify the customer. Add the confirmed issue as an internal note, and let your team’s configured Kustomer routing handle the work. For an immediate two-way Chat transfer, use Human agent hand-off.
Studio
Attach Create conversation
Add Kustomer → Create conversation to the agent or the support Playbook. Set its Trigger to run only after the customer confirms the request. Use the verified customerID from customer lookup, collect the issue and write a concise subject in name. Keep optional routing fields unset unless your administrator supplied the destination IDs.
Retain the new conversation ID
Test with a disposable customer. Create kustomer_conversation_id in More → Variables with an empty default. In Capture response, map conversation.id into it. In Add internal note → conversationID, insert {kustomer_conversation_id} as the provided value and disable model fulfillment. Clear the variable before creation and continue to the note only on current success; a previous value is not a successful new request. The agent should confirm that the request was recorded only when this call succeeded.
Test the customer journey
Ask, “The mug in order NS-1042 arrived cracked. Can your team help?” Confirm the issue when prompted. Check that exactly one open conversation appears for the correct customer, then verify any follow-up note uses that new ID. On failure, the agent must offer your support route without inventing a request reference.
Code
After the customer has confirmed the issue, save this as request.json with the authorized customer ID and execute it once:
Keep output.conversation.id on current success. An assignment ID is an existing Kustomer user or team ID, not a display name. The agent attachment uses these same input names; bind customer/routing IDs to trusted state and let the agent collect the confirmed subject.
Run a Draft conversation with the damaged-mug request and confirmation. Verify one open record belongs to the intended customer and that the agent reports the returned reference. If a later note fails, retain the created conversation and repair the note; do not repeat creation. After a timeout, inspect the customer’s conversations before deciding whether to retry.
Managing conversations
Read an authorized request before changing its status or assignment.
The customer-list action returns the provider’s response page, not a complete paginated history. Latest message is the newest message in the conversation; inspect its direction and author before treating it as a teammate reply. It does not retrieve internal notes.
Updates accept status open, snoozed or done and priority 1–5. Use only the snooze behavior your Kustomer configuration supports; this action has no snooze-duration input. Enforce customer-to-conversation access before reading or changing any thread.
Studio
Read the permitted conversation
Add Find conversation, or Find customer’s conversations, to the relevant agent or Playbook. Supply the authorized ID from your backend, not an unverified customer claim. In a sandbox conversation, ask for the test request’s status and confirm the agent uses the current result.
Configure a confirmed update
Add Update conversation. Set its Trigger for the specific permitted change and retain the same conversationID. Set only the intended status, priority or assignee inputs. Have the customer or support operator confirm consequential changes before the action runs.
Check the result and failure path
Run the confirmed update, read the same conversation again and inspect the changed fields. To use Find latest message, add it separately and check message.attributes before quoting text. Test an empty thread and an invalid ID; the agent must explain that it could not confirm the latest state instead of using cached details.
Code
Use the execution workflow with one of these requests at a time:
Read output.conversation, output.conversations or output.message for the chosen operation. Re-read after updating. An empty list is different from an execution error; neither confirms a customer’s entire support history.
For agent use, attach only the required actions and provide authorized IDs. Test a request for the existing case’s status, then a confirmed update. Verify the resulting agent reply matches the current readback. Missing IDs, no messages and provider errors must produce your fallback without leaking another thread or claiming a successful change.
Managing teams and companies
Validate a routing team or update an authorized company record.
Find team reads an existing teamID; it does not search for a team by name. Update company takes companyID and optional name (at least three characters), externalID, domains and custom attributes. Company changes affect the company record, so restrict them to authorized staff workflows.
Studio
Prepare the approved IDs
Ask your Kustomer administrator for the existing team or company ID. Attach Find team for a routing check, or Update company in the authorized staff Playbook. Keep company updates outside customer-controlled paths.
Configure and check the action
For Find team, supply teamID and inspect team.id and its name. For Update company, supply the verified companyID, collect and confirm only the intended fields, then inspect the returned company and the saved record in Kustomer.
Test with an allowed sandbox team/company, then an invalid ID. The agent should use the current team result or confirm the saved company change, and give a clear fallback if the action fails. A successful team lookup does not prove live hand-off queue configuration.
Code
Execute the operation with administrator-provided IDs:
Use output.team or output.company on current success. domains is an array; externalID maps to the provider’s externalId. Omitted fields remain unset in the request. For custom fields, use the custom-attribute format.
If an agent needs this capability, attach it to the staff Playbook with the trusted record ID and a specific invocation condition. Verify a confirmed sandbox change in a Draft conversation and in Kustomer, then deny an unauthorized company. Failed execution must not produce a success statement or a response from the previous company.
Import help articles
Use approved Kustomer articles as your agent’s Knowledge.
Article import uses the Published Kustomer connection and its org.permission.kb.read permission. The API key for actions can serve both jobs when it has the required roles; attaching a tool does not import content.
Studio
Open the Kustomer import
In your project’s Knowledge base, choose Add data source → Kustomer. If asked to connect, enter the Published org slug and API key from Connecting Kustomer.
Select the approved content
Set the filters, check the matching source count and choose the folder, chunking and refresh settings. Select Import … data sources to start the import.
Verify the agent's answer
Wait for processing to finish, open an imported document and check its text and language. Enable the agent’s Knowledge base system tool and ask a policy question whose answer is in that article. Check the answer and source, then ask a question the article does not answer; the agent should acknowledge the gap.
Code
The native Kustomer import is configured in the browser. Open Agent studio, select the project, then Knowledge base → Add data source → Kustomer. The administrator supplies the Published org slug/key; choose the approved filters and processing options, then select Import … data sources. Wait for processing and inspect the imported text before using it from Code.
Use List documents to find the imported records in the intended Environment and Query Knowledge Base for a diagnostic retrieval check. These calls do not authorize or create a native Kustomer import.
Finally, enable Knowledge for your agent and run a Draft conversation asking a question from an imported article. Confirm the answer uses the approved content and its source. A document listing or diagnostic query alone does not establish that the agent used it. Test an unanswerable question as well.
Refresh or remove imported content
Check refresh behavior, changed filters and content removal before relying on updated answers.
Use the Knowledge source’s available sync/refresh controls and inspect the completed document status. Where a managed integration source is offered, its synchronization can reconcile newly matching articles and changed filters. Existing individual imports are not automatically equivalent to a managed source; review the interface’s adoption notice before changing their behavior.
For an existing individual import, re-import with the intended filters to bring in matching translations and update matching records. Narrowing filters alone does not prove previous documents were removed: inspect the old documents and remove content the agent must no longer retrieve. After an article edit, removal or permission change, verify both the Knowledge text and a fresh agent answer. Remove unwanted sources using Knowledge’s deletion controls; a stopped refresh schedule is not deletion.
Before disconnecting, set refresh to Never for the affected imports. Reconnect an expired key, run a refresh/import and check the actual result; reconnecting does not by itself prove stale documents recovered.
Human agent hand-off
Continue a live customer Chat with a Kustomer teammate.
This path uses Voiceflow’s Kustomer Handoff provider. The widget or your custom Chat client remains the customer’s interface; your teammate works in Kustomer. The connection can create or reuse a customer and opens a new conversation for the hand-off.
The same Kustomer credential also needs a Webhook signing secret. Despite the field’s name, this adapter checks the literal x-vf-secret callback header; it does not validate Kustomer’s raw webhook HMAC. A Kustomer administrator or developer must configure the formatted callback workflows. Saving the in-app connection does not create them.
For production, create customer_id, customer_email and customer_name in More → Variables, leaving defaults empty. Your authenticated application supplies their verified values in the Chat action request variables before the Workflow runs. Insert those variable references in the identity fields; do not share the pilot’s fixed customer across sessions.
Studio
Have the administrator prepare callbacks
Give the Kustomer administrator the callback setup. Obtain the receiving queue ID, the shared callback secret, and confirmation that human messages and closure reach Voiceflow. This is separate from saving the org/API key.
Save the hand-off connection
Return to More → Integrations → Kustomer, enter the org/API key and Webhook signing secret, then save the connection. Use the callback secret supplied by the administrator.
Configure the Handoff step
Open a support Workflow, add a Handoff step, choose Kustomer, and supply the required queue and verified identity. Choose the context your support team needs and configure Return and Failure behavior.
Attach the support Workflow
In Agent → Workflows, add the saved Workflow and explain in Instructions when to use it, such as when a customer requests a person. Test the complete exchange before publishing. A configured step alone does not route the agent to it.
Code
Use the same connection operation, adding credentials.secretKey with the callback header secret. It updates Published; use your test project. Have the Kustomer administrator configure the callback workflows and supply the receiving queue ID before testing. The Workflow below uses one dedicated test customer; replace all pilot identity values before production.
Save kustomer-workflow.json. Replace the queue placeholder and use one dedicated test customer. Do not deploy this fixed identity for multiple customers.
This pilot leaves Return and Failure exits unlinked, handing control back to the calling agent. Define the fallback in Instructions or link the exits to Workflow blocks.
Save prepare-kustomer-patch.sh. Run it after Workflow creation and agent read succeed. Inspect kustomer-created.json for workflow.id, unresolvedReferences and diagnostics first; stop on unresolved values. Keep the returned ID rather than repeating creation after a later failure.
The patch preserves the current Workflow registry and Instructions. Replace the fallback with your real contact option and review agent-patch.json before applying it. Both methods below cover create → read → patch → compile.
After inspecting the create result, prepare and review the attachment:
Apply the reviewed patch and compile Draft:
After inspecting the create result, prepare and review the attachment:
Apply the reviewed patch and compile Draft:
A custom customer interface must implement the Chat handoff event contract: keep the active session connected, render teammate replies, send subsequent customer messages through handoff requests and handle completion. Do not use the Custom Handoff connection API for the built-in Kustomer provider.
Run the full exchange test through that client and the teammate’s Kustomer workspace. A successful compile, connection response or chat_started event does not prove a human reply reached the customer.
Configure Kustomer callbacks
Studio
Ask your developer to deploy the supplied callback normalizer with persistent state and an approved list of human teammate IDs. Give them the Code instructions in this section. Obtain the worker’s HTTPS callback URL, its ingress secret, the separate Voiceflow callback secret, and confirmation that failed jobs remain queued for recovery.
Your Kustomer administrator then saves and enables two Workflows: a message trigger reconciles outbound replies and Voiceflow-origin seed messages, and a status-change-to-done trigger queues closure. Both call that worker with its ingress header; they do not post raw events directly to Voiceflow. The developer supplies the exact trigger/body mapping below as the setup handoff.
Before continuing, have the developer show a queued callback draining successfully, and have the administrator confirm both Workflows are enabled. Then run the customer exchange test below, including a final reply followed immediately by resolution. A saved connection or a queued callback does not prove delivery.
Code
The supplied callback normalizer checks approved human authors, rereads Kustomer and queues replies before closing the Voiceflow hand-off. Your developer hosts it; the Kustomer administrator connects two Workflows to it. No customer API key or message text belongs in a public URL.
Deploy the callback worker
Download callbacks.mjs, start.mjs and the deployment notes into one directory. Use Node.js 22.13+ with SQLite available, one worker process and a private persistent state volume. Put an HTTPS reverse proxy in front of its loopback listener with a 64 KiB body limit and rate limits.
Set these server environment values, then run node start.mjs:
The developer hands the administrator https://YOUR_CALLBACK_HOST/kustomer/callbacks, the ingress secret and an operational check that the worker is running with its state volume. This address is your service, not a new Voiceflow endpoint.
Create the two Kustomer Workflows
In Settings → Platform → Workflows, create one Workflow per row. Add a REST API: JSON action. Use the builder’s sample output to select the paths; Kustomer trigger output flattens attributes and relationships.
For each action, set method to post, uri to your callback-worker URL and json to true. Add Content-Type: application/json and x-kustomer-callback-secret headers. Store that header’s value in a secret Workflow variable and insert it by its actual variable ID.
The reply action’s data is:
The closure action’s data is:
The Voiceflow-origin condition is required: a human reply can arrive before the connector has seeded its first message. That later seed queues another reconciliation. Unrelated conversations with no Voiceflow-origin messages are ignored. For the named [Voiceflow] hand-offs, an early closure stays queued until its seed appears; its closure count is retained. Keep that title prefix when resolving a hand-off.
Save and enable both Workflows. Inspect each REST action’s response; 202 means the hint was queued. It does not certify delivery to the customer. Configure the administrator’s error handling for non-2xx responses and review failed runs. Do not point raw Kustomer outbound webhooks directly at Voiceflow.
Verify normalized delivery
The worker rechecks the provider record, confirms Voiceflow-origin messages and forwards only public outbound text from the administrator-approved human IDs. It excludes automated messages, the connector’s own messages and internal notes. On closure, it drains qualifying unsent messages before sending end, checking the provider’s message count, the closure event’s count, newly queued hints and resolved state.
The worker posts the normalized message_received and end bodies to https://general-runtime.voiceflow.com/handoff/webhook/kustomer. It retains failed jobs for retry; the supplied node start.mjs service reports a redacted pending-job count and failure reasons to stderr at most every 30 seconds. A custom host can inspect callbacks.pending(). Histories above 500 messages or inconsistent provider snapshots stop delivery rather than silently losing the final reply.
Ordinary event replay is deduplicated in persistent state. Delivery remains at least once: a crash between Voiceflow accepting a reply and the worker recording it can produce a duplicate after recovery. Keep the normal support route available, and complete the rapid reply-and-resolution test below before release.
Test the live exchange
Request a human from the customer interface
Open a fresh sandbox Chat, ask for a person and check that the intended Workflow runs. Verify the correct customer, new conversation, queue and permitted transcript or summary in Kustomer. If identity lookup misses, check that a new customer was intended rather than assuming a profile was reused.
Exchange messages in both directions
Have the human teammate send a public reply and confirm it appears in the customer interface. Send a customer follow-up and confirm it appears in the same Kustomer conversation. Add an internal note and trigger a bot reply; neither may be forwarded as a human message.
Check completion and fallback
Send a final reply, then resolve the conversation. Confirm the reply reaches the customer before the end event and that the configured Return path runs. Test rapid reply-and-resolution as well. Use an invalid queue to verify the initial connection Failure path and approved support alternative. Separately interrupt callback delivery after a successful connection: confirm the worker retains the pending job, restore delivery and check the customer receives it. A later callback outage does not automatically take the initial Failure path.
The customer never receives a reply
Check normalized callbacks, human filtering and the active customer connection.
Inspect the Kustomer Workflow run and REST response. Match the exact conversationId, body type and x-vf-secret. Verify the message is a public outbound human reply and the customer session still consumes hand-off events. A successful write to Kustomer is only one direction of the conversation. Fix delivery before treating the hand-off as ready.
Include files in a hand-off
Respect this provider's upload shape and test the customer-visible result.
The Kustomer adapter’s customer upload path requires file size, uploads to the provider’s storage fields and attaches the file to the conversation message. It handles the first file in a file-upload request; send and verify one file at a time. Custom clients must follow the Chat upload contract rather than posting a local file URL. The normalized teammate-reply callback above carries text; it does not establish inbound staff-file rendering.