Build with

Use this guide when your platform does not have a page in the integration catalog. If a provider guide exists, start there: it contains the account setup, mappings and checks for that platform.

Before you begin

  • Choose one task to connect, such as looking up an order, answering from approved articles or connecting a support teammate.
  • Have a Voiceflow project you can edit and a test account in the external system. Obtain that system’s API or hosted MCP documentation and the permissions for your task.
  • Use a dedicated test project for initial credentials. Creating or changing a Secret’s default also updates Main’s Published value; a named Environment’s Draft value is separate from its Published value.
  • For customer records, have your application verify the customer and supply their record ID. A token authorizes the system connection; it does not establish the customer’s identity.
  • For human support, have a developer who can build and host the connection service and a teammate who can test replies.

Studio

Open your project in Agent studio. The instructions below use its tool editor, Knowledge base and Handoff settings.

Code

Use your backend with a Voiceflow API credential, project ID and test Environment. Tool management uses your Voiceflow bearer token; the public Knowledge API below uses a separate project API key. Keep provider credentials on your backend or in Secrets. The linked API and CLI references define the exact request shapes and commands.

Choose the connection for your task

These connections can be used together. An action that reads an article does not import it into Knowledge; creating a support ticket does not establish live handoff.

Connect data and actions

Choose API tool when you need to configure a specific HTTP request. Choose MCP when the platform exposes a hosted server with tools for the same task.

1

Define and authorize the request

Take the method, URL, required headers and request body from the external system’s API contract. Start with a read operation on a test record. Store the credential in a Secret; bind customer identifiers to values verified by your application.

2

Create and test the tool

Studio

Open Agent → Global tools → + → API. Configure the request, then bind its credential input to the Secret. Supply the test record’s ID, run the tool and inspect the returned status and body. The API tool instructions cover request and response configuration.

Code

Use Create API tool to save the request in your test Environment. Retain its ID, inspect its input schema and use Execute API tool with those inputs. Check the execution result and the provider’s response body. The API-tool CLI reference provides the command path for the same resources.

3

Make it available to the agent

Studio

Keep the tool in Global tools, or add it to the relevant Playbook. Describe when to call it and which response fields to use. Run a conversation with the verified test identity and confirm the agent uses the returned record.

Code

Use Create tool to attach the saved API tool to the agent or Playbook. Read its input IDs before binding defaults; a saved API request alone is not an attachment. Run a conversation and confirm the correct tool and record were used.

Import help articles

1

Prepare approved content

Ask the content owner for public article URLs or an approved text/file export. An API token for record operations does not automatically authorize a Knowledge import. Keep private customer records out of content intended for general answers.

2

Import and check processing

Studio

Open Knowledge base → Add data source. Choose URL, Plain text or the matching file source, then import the approved material. Wait for processing to finish before testing retrieval.

Code

Use Create document with the approved URL or file and your project API key. Retain data.documentID and read its processing status with Get document, using that key and the same projectEnvironmentIDOrAlias. Wait for data.status to become SUCCESS; inspect an ERROR before retrying. Omitting the Environment can read a different document set.

3

Verify an answer uses the source

Enable Knowledge for the agent, ask a question answered by the imported material and inspect the retrieved source and answer. Importing content is separate from configuring ongoing updates; agree who will refresh or replace it when the original changes.

Human agent hand-off

1

Build the two-way connection service

Have a developer follow Connect your support platform. The service opens a provider conversation, forwards customer messages, receives human replies and sends signed callbacks to Voiceflow. It must retain the customer/conversation mapping and exclude private notes and echoed messages. Start with text; enable files only after implementing delivery in both directions.

2

Connect the service and route escalation

Studio

Obtain the deployed HTTPS URL, service authorization and separate callback signing secret from the developer. In your project, open Integrations → Custom Handoff → Connect and enter those values. Follow Studio handoff setup to configure the Workflow, verified customer identity, context and Return/Fail paths.

Open Integrations to connect the handoff service your developer has deployed. Photo:

Code

Complete the API configuration sequence to save the service credentials, create the escalation Workflow and register it with the agent. Configure your customer client using the Chat handoff reference. The exact Custom Handoff setting names this interface; it is not a separate tier of provider integration.

3

Test with a support teammate

Use the actual customer channel. Escalate once, exchange a customer message and a human reply, then end support and check the configured return behavior. Test service failure separately. A saved connection or created ticket does not prove that replies reach the customer.

Verify the integration

  • Data: the agent reads the correct customer’s record. For a write, confirm the intended change in the external system and read it back before reporting success.
  • Knowledge: the answer uses the approved imported source, rather than relying only on a successful import status.
  • Human support: messages arrive once in both directions, private notes remain private, and the final reply arrives before the connection closes.
  • Published use: prepare credentials for the target Published version, publish the tested Environment and repeat the check in a fresh customer session. Draft execution alone does not verify the published agent.

Troubleshoot a connection that saves but does not work

Check authorization, execution and delivery at the stage that failed.
  1. Request fails: check the provider host, permission scopes, required inputs and the credential value used by the selected Environment.
  2. Tool is not called: confirm it is attached to the agent or Playbook, its trigger describes the request, and the customer inputs are populated before execution.
  3. Knowledge is missing: check processing status and test retrieval from the approved document.
  4. Human replies are missing: inspect the provider receiver, stored conversation mapping, signed callback response and customer-client handling using the handoff troubleshooting guide.

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