> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zapier integration

> Connect Voiceflow to Zapier to call approved app actions through MCP or start an existing Zap through a webhook.

## Overview

Voiceflow integrates with Zapier through two distinct jobs: call a configured app action through Zapier MCP and use its returned result, or send a webhook to start an existing Zap. Zapier owns the connected accounts and workflow execution. An MCP tool result and a webhook acknowledgment have different completion meanings.

### Examples of when to use Zapier

- **[Use connected app actions](#app-actions)** — look up approved support information or perform a configured operation.
- **[Start a Zap](#start-a-zap)** — submit a confirmed request to a background workflow.
- **[Maintain the connection](#maintaining-the-connection)** — rotate access, refresh tool definitions and reconcile failed runs.

The MCP setup below uses a server connection token with managed mode. Only configured, authorized tools are in scope; Voiceflow does not automatically gain every Zapier action or manage the server's app connections.

<a id="app-actions"></a>

## Use connected app actions

Connect a managed MCP server and give the agent a scoped action.

Invoke the approved return-policy search when the customer asks to find the approved return policy. Zapier fixes the connected account and approved source; the agent collects only the search fields exposed by that action's actual schema. Use the current successful result to answer. If it is missing, pending or an error, explain that state without claiming completion or reusing an earlier result.

#### Studio

### 1. Prepare the provider tools

At [Zapier MCP](https://mcp.zapier.com), select **Add MCP server → Other**. Use **managed mode**, which exposes one tool per action, and configure only the approved actions and app connections. New servers can default to agentic mode, whose discovery/management meta-tools are a different interface. In the server's **Settings → API token**, select **Generate token** and store the token immediately. Use the separate Token value with the endpoint `https://mcp.zapier.com/api/v1/connect`; keep it out of the URL. This token can execute the server's tools, not just read its catalog. See [connection-token setup](https://docs.zapier.com/mcp/get-started/connect/other) and [server modes](https://docs.zapier.com/mcp/overview/how-tools-work).

### 2. Store the connection credential

In your test project in [Agent studio](https://creator.voiceflow.com), open **More → Secrets** and create `zapier_mcp_token`. Set its default to the provider token: design-time MCP discovery uses the project default. Creating it also sets Main's Published value, so perform initial setup in a test project. If the selected Environment has its own Draft override, fill that too.

### 3. Connect the MCP server

Open **Agent → Global tools → + → MCP → Create MCP tool**. Name it **Zapier**, use `https://mcp.zapier.com/api/v1/connect`, and add `Authorization` with `Bearer {zapier_mcp_token}` as a Secret reference. Select **Add MCP server**, then select only the approved business tool. A tool catalog is not proof that the connected account may execute every listed operation.

Native Add MCP server dialog for the Zapier connection — Connect the hosted Zapier server with its authorization header.

### 4. Configure invocation and inputs

Open the attached tool and write a **Trigger** for **Find the approved return policy**. In Zapier, fix the approved app connection and destination in the action configuration. In Voiceflow, describe only the remaining customer-supplied search inputs from the discovered schema. Do not let the model choose a credential, destination account or another customer identity.

### 5. Test a real conversation path

In the isolated project's **Run**, ask **Find the approved return policy**. Use a known question whose approved answer exists in the configured source. Confirm the intended tool runs, inspect its current result and compare it with the provider's execution history. Tell the agent to answer only from the current successful result. For missing data, an error or a pending response, it must explain that state without inventing completion. Test that failure case as well.

#### Developer

Set `VF_TOKEN` to your [Voiceflow API credential](/docs/api-reference/authentication), `PROJECT_ID` to the test project and `ENVIRONMENT` to its test alias. Set `PROVIDER_TOKEN` to the token prepared below. The [current CLI](/docs/cli/install) reads `VF_TOKEN`.

At [Zapier MCP](https://mcp.zapier.com), select **Add MCP server → Other**. Use **managed mode**, which exposes one tool per action, and configure only the approved actions and app connections. New servers can default to agentic mode, whose discovery/management meta-tools are a different interface. In the server's **Settings → API token**, select **Generate token** and store the token immediately. Use the separate Token value with the endpoint `https://mcp.zapier.com/api/v1/connect`; keep it out of the URL. This token can execute the server's tools, not just read its catalog. See [connection-token setup](https://docs.zapier.com/mcp/get-started/connect/other) and [server modes](https://docs.zapier.com/mcp/overview/how-tools-work).

Save this as `zapier-server.json`:

```json
{
  "name": "Zapier",
  "url": "https://mcp.zapier.com/api/v1/connect",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {zapier_mcp_token}"
    }
  ]
}
```

#### API

```sh
jq -n --arg value "$PROVIDER_TOKEN" \
  '{name:"zapier_mcp_token",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/mcp-server?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zapier-server.json
```

#### CLI

```sh
jq -n --arg value "$PROVIDER_TOKEN" \
  '{name:"zapier_mcp_token",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json

vf mcp-server create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < zapier-server.json
```

The Secret default supplies design-time discovery and also writes Main's Published value. Use a test project and set the selected Environment's Draft override when different. Keep `mcpServer.id` as `SERVER_ID`. Registration does not attach an action. Discover its actual tools and input contract:

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&serverID=$SERVER_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Select the approved tool from `mcpTools` and save its `id` as `MCP_TOOL_ID`:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$MCP_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf mcp-tool list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --server-id "$SERVER_ID" --output-format json
```

Select the approved tool from `mcpTools` and save its `id` as `MCP_TOOL_ID`:

```sh
vf mcp-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$MCP_TOOL_ID" --output-format json
```

Use `inputSchema` to prepare `inputs`; names, nesting and required fields come from this server, not a universal provider action schema. Choose a read-only search action against approved support content for the first test. Fix its account and destination in Zapier before exposing it.

Save a test execution body as `zapier-inputs.json`. Its shape is `{"inputs":{...}}`, where `...` is replaced by the actual schema-valid test values. This is a schema-first placeholder, not a copyable Zapier action signature. For this first test, use the fixed search phrase `approved return policy` in the schema's search field. Standalone execution interprets Secret-name tokens in top-level strings; a backslash does not escape them. Do not use arbitrary customer text containing braces for this test, and do not change a string to an object unless the discovered schema permits that type.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$MCP_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zapier-inputs.json
```

#### CLI

```sh
vf mcp-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$MCP_TOOL_ID" --output-format json < zapier-inputs.json
```

Require `success: true`, inspect `output` and reject provider `isError` results. Output can contain text blocks and/or structured content; use the tool's actual business response rather than assuming an app record always appears at a fixed path. A successful MCP call can still return "not found" or pending work. Do not treat `truncated: true` as a complete result.

Create the agent attachment after the standalone test. Save the following as `zapier-attachment.json` and substitute the discovered tool ID:

```json
{
  "type": "mcp",
  "mcpToolID": "YOUR_MCP_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Use for: Find the approved return policy. Use only the current successful result; explain missing data, failure or pending work without claiming completion. Never automatically repeat a write after an ambiguous outcome.",
  "inputVariables": {}
}
```

For Zapier, add each exposed input that needs a fixed default under `inputVariables`: use its exact schema name, `mcpIntegrationVariableName` with that same name, `required: false` and the verified `defaultValue`. Leave only approved customer-supplied search fields model-collected. The provider action configuration must already fix its account and destination.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zapier-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < zapier-attachment.json
```

Test from a client bound to this project's Draft: ask **Find the approved return policy**, inspect the tool call with the intended inputs, and compare its current result and the agent's answer with the provider history. Test a missing result/provider error; the agent must not claim success or reuse an older response. Creating a server or executing a tool alone does not prove this conversation path.

<a id="start-a-zap"></a>

## Start a Zap

Send a confirmed request while keeping background completion separate.

Invoke **Start support follow-up** after the customer confirms the follow-up request. The authenticated application supplies the verified customer and confirmed reason as the prepared `zapier_request` variable; the webhook URL comes from its Secret default. Use the current successful acknowledgment to say **submitted for processing**. A failure or unconfirmed response must not become a completed-task claim or an automatic repeat submission.

Use this for an existing multi-step Zap that records work or sends a later notification. **Catch Hook** returns an acknowledgment that cannot be customized; it is not the downstream action's final response. An off/deleted Zap can briefly still acknowledge requests before its disabled state propagates. See [Zapier webhook triggers](https://help.zapier.com/hc/en-us/articles/8496288690317-Trigger-Zaps-from-webhooks).

### Prepare the receiving Zap

Ask the Zap owner to create **Webhooks by Zapier → Catch Hook**, copy its webhook URL, provide a test request and map the parsed fields to the existing approved workflow. The owner must deduplicate a stable request ID before writes, validate customer access and confirm the final result in Zap History and the destination system. Publish/turn on the Zap before using it beyond the trigger test. The webhook URL is the credential for this path; it is separate from the MCP token.

The developer supplies a literal-safe JSON string with `request_id`, verified `customer_id` and confirmed `reason`. Use [encode-request.mjs](/docs/examples/automation/encode-request.mjs), populate `zapier_request` on the next authenticated runtime action and bind it to the request tool. The Zap owns its downstream notification; sending the webhook does not automatically resume a Voiceflow conversation.

### Configure and invoke the webhook tool

#### Studio

### 1. Store the webhook and prepared input

In the test project, create restricted Secret `zapier_webhook_url` in **More → Secrets** with the full Catch Hook URL. Create `zapier_request` in **More → Variables** with an empty default. For **Run**, temporarily use the developer's prepared fictional test payload as the variable default; clear it afterward.

### 2. Create the API tool

Open **Agent → Global tools → + → API**, name it **Start support follow-up**, choose **POST** and set URL input `{webhook_url}`. Add `Content-Type: application/json` and raw JSON body `{payload}`. Bind `webhook_url` to Secret `zapier_webhook_url` and `payload` to variable `zapier_request`; neither should be model-collected. Keep **Async execution** off to inspect the acknowledgment.

Native API request for the Zapier webhook with prepared payload input — Keep the Catch Hook URL and prepared request bound to trusted values.

### 3. Set the trigger and test the outcome

Set **Trigger** to run after the customer confirms a follow-up request. In **Run**, ask **"Please send this issue for follow-up"**, confirm its reason and inspect the call. The agent should say the request was submitted for processing, then the Zap owner checks the matched History run and final destination. Test a disabled/malformed request: an HTTP response alone must not become a completed-task claim.

#### Developer

Set `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT` for the test project. Set `PROVIDER_CREDENTIAL` to the Catch Hook URL supplied by the Zap owner. Keep that full URL in the Secret, not the tool definition.

Save this definition as `zapier-webhook.json`. Braced names declare inputs on this API tool; they are bound to Secrets/variables on its attachment later.

```json
{
  "name": "Start support follow-up",
  "httpMethod": "post",
  "url": "{webhook_url}",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "body": {
    "type": "raw-input",
    "contentType": "json",
    "content": "{payload}"
  }
}
```

#### API

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"zapier_webhook_url",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"zapier_request","color":"#515A63","defaultValue":""}'

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zapier-webhook.json
```

Save `apiTool.id` as `API_TOOL_ID`, then discover input IDs:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$API_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"zapier_webhook_url",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json

vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name zapier_request --color-param '#515A63' --default-value '""' --output-format json

vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < zapier-webhook.json
```

Save `apiTool.id` as `API_TOOL_ID`, then discover input IDs:

```sh
vf api-tool variable list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --api-tool-id "$API_TOOL_ID" --output-format json

vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json
```

Creating the Secret default also writes Main's Published value. If your selected Environment uses a different credential, set its [Draft override](/docs/documentation/build/data/secrets#publishing-reverting-and-discarding-changes) before testing. Match each `variables[].name` to its `id` for the attachment; resolve `unresolvedReferences` before continuing.

Save the confirmed test request as `zapier-request.json` and download [encode-request.mjs](/docs/examples/automation/encode-request.mjs):

```json
{
  "request_id": "req-test-001",
  "customer_id": "verified-customer-123",
  "reason": "Please send this issue for follow-up."
}
```

Read the confirmed body, encode it, and build standalone inputs. This tests the saved request against the selected Environment's Draft; it does not attach the tool or publish the agent.

```sh
node encode-request.mjs zapier-request.json > zapier-payload.txt
jq -n --rawfile payload zapier-payload.txt \
  '{inputs:{webhook_url:"{zapier_webhook_url}",payload:$payload}}' > zapier-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zapier-inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < zapier-inputs.json
```

Require `success: true`, a current 2xx `output.status` and no truncation. `output.body` is Zapier's acknowledgment; verify the matched Zap run and its final destination separately.

Save this as `zapier-attachment.json`. Replace `YOUR_API_TOOL_ID` and each input ID with the values discovered above. The payload and credential are defaults, not model-collected inputs.

```json
{
  "type": "api",
  "apiToolID": "YOUR_API_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Submit the confirmed follow-up request. Explain that it was submitted for processing. The webhook acknowledgment does not confirm downstream completion. Inspect the original request before repeating an unconfirmed write.",
  "asyncExecution": false,
  "inputVariables": {
    "webhook_url": {
      "apiToolInputVariableID": "WEBHOOK_URL_INPUT_ID",
      "required": false,
      "defaultValue": "{zapier_webhook_url}"
    },
    "payload": {
      "apiToolInputVariableID": "PAYLOAD_INPUT_ID",
      "required": false,
      "defaultValue": "{zapier_request}"
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zapier-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < zapier-attachment.json
```

Your authenticated backend supplies the encoded string as `variables.zapier_request` on the next [runtime action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). Test **Please send this issue for follow-up** from a Draft client. Inspect the emitted tool call, current acknowledgment and agent response, then reconcile Zap History with the destination record. Test a rejected request/provider failure: the agent must not claim downstream completion or reuse an earlier result.

<a id="maintaining-the-connection"></a>

## Maintaining the connection

Refresh the right credential and inspect the original provider run.

### 1. Repair the correct connection

For MCP, inspect the server's **History** and its connected app authorization. A valid server token does not repair an expired app connection. For Catch Hook, inspect Zap History and whether the Zap is on. Fix the failing app action before replaying work.

### 2. Rotate and refresh deliberately

In **Zapier MCP → Settings → API token**, rotating a token immediately invalidates the old one. Update `zapier_mcp_token` in the Voiceflow project's **More → Secrets**, including the relevant Environment's Draft/Published values. For changed MCP actions, refresh the server in **Settings → MCP servers** or use `vf mcp-server sync --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --server-id "$SERVER_ID"`; inspect the refreshed tool schema and update existing attachments. A new action is not automatically an approved agent capability.

#### Developer

Retain the created Secret's `secret.id` as `SECRET_ID`. Use `PROVIDER_CREDENTIAL` for the replacement token or full Catch Hook URL. Choose `zapier_mcp_token` for MCP token rotation and `zapier_webhook_url` only when the Zap owner supplies a replacement hook. Updating one does not change the other.

#### Developer

Save the Draft update body as `credential-value.json`:

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' > credential-value.json
```

#### API

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @credential-value.json
```

#### CLI

```sh
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" \
  --output-format json < credential-value.json
```

For the selected Environment's Published credential, change `versionVariant` to `published` after the Draft test. To replace the project default used for MCP discovery, omit `environmentAlias` and `versionVariant`; this also writes Main's Published value. Test the intended connection before changing a live default.

### 3. Reconcile before retrying and launching

Check the original request/record before retrying a write after a timeout or partial Zap failure. Keep the same deduplication key for the same request. Set the target Environment's Published Secret values, [publish the tested agent](/docs/documentation/deploy/environments/publishing) and repeat the successful/failure conversation checks from its published client. Removing the Voiceflow tool does not revoke Zapier's app connections or stop a running Zap.
