> ## 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.

# Microsoft Power Automate integration

> Connect Voiceflow to Microsoft Power Automate to submit an employee request to a protected cloud flow and return its pending approval reference.

## Overview

Voiceflow integrates with Microsoft Power Automate so your AI agent can submit an employee request to a protected cloud flow and return its pending approval reference. Microsoft Power Automate runs the external workflow; Voiceflow calls its approved endpoint and uses the response in the conversation.

### Examples of when to use Microsoft Power Automate

- **[Connect the business service](#connecting-power-automate)** — prepare its authorization, schema and test resources.
- **[Request an employee approval](#run-request)** — invoke the configured service and interpret its current result.
- **[Recover a failed request](#maintaining-the-connection)** — inspect execution and downstream state before retrying.

#### Studio

Use an editable test project in [Agent studio](https://creator.voiceflow.com). Your integration developer or administrator prepares the service below, supplies its endpoint and credentials, and gives you a verified test request plus its expected result. Keep provider-side deployment with that owner.

#### Developer

Use a [Voiceflow personal or service key](/docs/api-reference/authentication) with project access, a current [Voiceflow CLI](/docs/cli/install) and the selected test [Environment](/docs/documentation/deploy/environments/overview). You prepare the provider service and create, execute and attach the Voiceflow request separately. The examples use a test project; they can read or change connected systems.

<a id="connecting-power-automate"></a>

## Connecting Microsoft Power Automate

Prepare a deployed endpoint and the credentials for its approved operation.

### Prepare the provider service

#### Studio

Ask your Microsoft Power Automate administrator or integration developer to complete the service setup linked below. Obtain all four handoff items before creating the Voiceflow tool:

- The deployed HTTPS endpoint and its exact authentication headers.
- The credential value for the Voiceflow Secret.
- A request schema, response schema and verified test employee/item.
- A successful test response and a rejected unauthorized request, confirmed in the provider's execution history.

The sample request fields on this page are a recipe contract for your existing workflow. Have the owner map them to that workflow; a provider account alone does not create this endpoint.

#### Developer

### 1. Create and restrict the HTTP-triggered flow

A Power Automate administrator creates a cloud flow with **When an HTTP request is received**. In **Who can trigger the flow?**, choose **Specific users in my tenant** and enter the calling service principal's object ID. Do not leave that list empty: an empty list permits users across the tenant. Define required string fields `request_id`, `employee_id`, `item` and `justification` in the trigger's JSON schema. Save the flow and copy its current HTTP POST URL.

### 2. Create an approval and return a receipt

Validate that the employee may request the item, choose the approver from your approved business rules and deduplicate `request_id` in a durable request store before creating work. Use **Create an approval**, retain the returned Approval ID and save its mapping to `request_id`. Add **Response** with status **202** and JSON `request_id`, `approval_id` and `status: "pending"`. For a repeated request, return the saved receipt instead of creating another approval.

Use **Wait for an approval** with the saved Approval ID for later processing, then update the request record and notify the verified employee through your existing notification route. Do not put **Start and wait for an approval** before the receipt: it blocks until someone responds. The receipt confirms a request is waiting, not that it has been approved.

### 3. Deploy the token relay

Register a confidential application in Microsoft Entra ID and obtain its tenant ID, application/client ID and credential. The flow's allowlist must use this application's service principal object ID. For this public-cloud example, acquire a client-credentials token for audience `https://service.flow.microsoft.com/`; the v2 scope is `https://service.flow.microsoft.com//.default`, preserving the trailing slash.

Download [power-automate-relay.mjs](/docs/examples/automation/power-automate-relay.mjs) and [serve-power-automate.mjs](/docs/examples/automation/serve-power-automate.mjs). Use Node.js 22 for this example and keep both files in one directory. Configure `TENANT_ID`, `CLIENT_ID`, `CLIENT_SECRET`, `FLOW_URL` and a generated `RELAY_TOKEN` in your hosting service's secret store. Start `node serve-power-automate.mjs` behind your HTTPS reverse proxy, forwarding `/approval` to its configured `PORT` (8080 by default). The relay obtains a fresh Entra token for each request, calls one fixed flow and returns only the validated receipt. It uses a 15-second total upstream deadline, with up to 4 seconds for the token and 10 seconds for the flow call, to leave room inside Voiceflow's standalone endpoint wait. It never automatically retries the flow POST. A timeout still requires reconciliation because the flow may have created the approval.

The relay authenticates Voiceflow to the flow; your application and flow still own employee authorization, durable deduplication and final notification. Deploy those controls before exposing the action. Keep the Microsoft credential on your backend; Voiceflow stores only the separate relay token.

### 4. Verify the deployed handoff

Test a known employee/item through the relay. Require a matching 202 receipt, an approval visible to the intended approver and a request-store record linking the request ID to that approval. Repeat the same request ID and confirm there is still one approval. Verify an invalid relay token is rejected before a flow call, and an unauthorized employee is rejected before approval creation. Complete the approval once and verify your final notification reaches the intended employee.

Provider setup: [HTTP trigger authentication](https://learn.microsoft.com/power-automate/oauth-authentication), [approval action behavior](https://learn.microsoft.com/troubleshoot/power-platform/power-automate/approvals/differences-between-flow-approval-actions) and [client-credentials tokens](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow).

### Create the Voiceflow request

#### Studio

### 1. Store the service credential

Open your test project in [Agent studio](https://creator.voiceflow.com), then **More → Secrets**. Create `power_automate_relay_token` with the credential supplied by the service owner. Creating its default also writes Main's Published value, so keep initial setup in a test project. If the selected Environment has a different Draft credential, set its Draft override too.

### 2. Create a request variable

Open **More → Variables**, create `power_automate_request` with an empty default and ask your application developer to populate it with the [prepared request](#run-request). For a Studio Run test, temporarily set its default to the developer's prepared test string in this isolated test project; backend runtime variables do not automatically populate Studio Run. Clear the default after that test.

### 3. Configure the API request

Open **Agent → Global tools → + → API** and name the tool **Request equipment approval**. Choose **POST**, set the owner-supplied endpoint and add the headers below. Set the raw JSON body to `{payload}`.

| Field | Value |
| --- | --- |
| Name | `Request equipment approval` |
| Method | `POST` |
| URL | `https://YOUR_BACKEND/approval` |
| Header: Authorization | `Bearer {authorization}` |
| Header: Content-Type | `application/json` |
| Raw JSON body | `{payload}` |

Native API request editor for the Power Automate relay with headers and raw request body — Configure the relay endpoint your developer hosts and its request fields.

### 4. Bind inputs before running

Open the attached tool's inputs. Open `authorization` and set its **Default value** to the Secret `power_automate_relay_token`, and set `payload`'s **Default value** to `power_automate_request`. Keep **Async execution** off so the agent receives this call's response. The provider workflow may still return a pending receipt.

#### Developer

Set `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT` for the test project. Set `PROVIDER_CREDENTIAL` to the separate relay token. The service owner supplies `PROVIDER_URL` and the verified test request.

Save this definition as `power-automate-tool.json`, replacing the illustrative URL with `PROVIDER_URL`. Braced names declare inputs on this API tool; they are bound to Secrets/variables on its attachment later.

```json
{
  "name": "Request equipment approval",
  "description": "Run the approved Microsoft Power Automate request for the employee verified by the application.",
  "httpMethod": "post",
  "url": "https://YOUR_BACKEND/approval",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {authorization}"
    },
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "body": {
    "type": "raw-input",
    "contentType": "json",
    "content": "{payload}"
  }
}
```

#### API

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"power_automate_relay_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/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"power_automate_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 @power-automate-tool.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:"power_automate_relay_token",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 power_automate_request --color-param '#515A63' --default-value '""' --output-format json

vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < power-automate-tool.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.

<a id="run-request"></a>

## Request equipment approval

Provide a verified request and use the result from the current call.

Invoke **Request equipment approval** when the employee asks for equipment approval and confirms the item and justification. The authenticated application supplies the verified identity and prepared request variable before the call; keep those inputs bound to trusted defaults. A matching approval reference with pending status means the request is waiting for approval. It does not mean the equipment was approved. For a pending result, explain that work is waiting. For a current failure or missing required fields, say the result could not be confirmed; never reuse an earlier result or automatically repeat an uncertain write.

### Prepare the request

#### Developer

The application developer builds the request from an authenticated employee/item and the confirmed task. Save this illustrative body as `power-automate-request.json`, replacing test identities with values the application has verified:

```json
{
  "request_id": "req-test-001",
  "employee_id": "verified-employee-123",
  "item": "Replacement headset",
  "justification": "Current headset microphone has failed."
}
```

Serialize it with the [literal-safe request encoder](/docs/examples/automation/encode-request.mjs): `node encode-request.mjs power-automate-request.json > power-automate-payload.txt`. It preserves quotes, newlines and literal text such as `{employee_name}` without treating that text as a Voiceflow variable or Secret. Do not concatenate employee text into quoted JSON placeholders.

#### Studio

Have your developer deliver the encoded string and populate `power_automate_request` in the authenticated client's next action **before** this tool runs. They send `variables` on the [runtime action](/docs/api-reference/v4interact/interact-non-stream#streaming-action); creating the variable or session alone does not fill it. For Studio Run, use the temporary test default described above, then clear it. The provider service must enforce employee access and validate the request; tool descriptions do not enforce either.

#### Developer

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 power-automate-request.json > power-automate-payload.txt
jq -n --rawfile payload power-automate-payload.txt \
  '{inputs:{authorization:"{power_automate_relay_token}",payload:$payload}}' > power-automate-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 @power-automate-inputs.json
```

#### CLI

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

Require `success: true`, inspect `output.status` and `output.body`, and check the business fields against the service owner's response schema. `truncated: true` means the returned body is incomplete. On timeout or error, inspect provider execution before retrying a write.

### Let the agent use the request

#### Studio

### 1. Describe the trigger and result use

Open the attached **Request equipment approval** tool and set **Trigger** to the condition below. Its input defaults must already point to the Secret and prepared request variable; the model must not collect credentials or choose another employee's identifier.

```markdown
Use Request equipment approval when the employee asks for this service and the application has supplied the verified request. Confirm the item and justification before submission.
Read the current tool result. A pending receipt means an approval request was created. It does not mean the item was approved.
If the response is pending, say the request is pending. If the call fails or the required fields are missing, explain that the result could not be confirmed. Never reuse an earlier result or automatically repeat a write.
```

### 2. Test the conversation

In **Run**, use the verified test request. Ask "Please request a replacement headset." and confirm the intended tool runs with the fixed identity and prepared payload. Inspect the current tool result in Run and compare it with the pending approval and request-store record. Also test the rejected-resource case: the agent must not claim success or expose another employee's data.

#### Developer

Save this as `power-automate-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": "Use when the employee requests equipment approval and confirms the item and justification, after the application supplies the prepared request. A matching pending receipt means waiting for approval. Use only the current result; never claim approval or repeat an uncertain write.",
  "asyncExecution": false,
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTHORIZATION_INPUT_ID",
      "required": false,
      "defaultValue": "{power_automate_relay_token}"
    },
    "payload": {
      "apiToolInputVariableID": "PAYLOAD_INPUT_ID",
      "required": false,
      "defaultValue": "{power_automate_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 @power-automate-attachment.json
```

#### CLI

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

Your authenticated backend supplies the encoded payload as `variables.power_automate_request` on the next [runtime action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). Use a test client bound to this project's Draft, ask for equipment approval and inspect the emitted tool call, current response and agent answer. Verify both the successful and rejected-resource cases. The backend/provider enforces access; the description is model guidance, not an authorization gate.

The attached API tool returns the provider body to the agent. For a Workflow's **Capture response**, paths start at that body: for example `status` rather than standalone `output.body.status`. A missing capture can leave an earlier variable value unchanged; clear result variables before a Workflow call and branch on the current HTTP/business outcome. These Global tool examples use the current result directly.

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

## Maintaining the connection

Inspect provider execution, update credentials and test the intended deployment.

| Symptom | Check |
| --- | --- |
| Relay 401 | Update the Voiceflow relay Secret to the deployed relay's token. |
| Flow authentication fails | Check the Entra credential, token audience including its trailing slash, tenant and allowlisted service principal object ID. A Power Platform management token has a different audience. |
| Invalid or unrecognized receipt | Inspect flow history and the durable request store. The relay requires a matching request ID, approval ID and pending status. |
| Timeout or 502/504 | Reconcile by `request_id` before retrying. A flow may have created the approval before its response was lost. |
| Pending approval | Continue through the existing approval and notification process; do not resubmit to make it finish. |

### Replace a credential

### 1. Inspect the original provider execution

Use the request ID and execution time to find the provider run and its downstream record. A timeout can follow a completed side effect; reconcile that state before repeating a write.

### 2. Update the intended credential version

#### Studio

Open the same project and **More → Secrets**, select the provider Secret and update the target Environment's **Draft value** for testing. After validation, explicitly set the Published value for the intended Environment; this changes the credential serving live traffic.

#### Developer

Retain `secret.id` from creation as `SECRET_ID`, set `PROVIDER_CREDENTIAL` to the replacement and use the value operation below. After validation, explicitly set the Published value for the intended Environment; this changes the credential serving live traffic.

#### 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, omit `environmentAlias` and `versionVariant`; this also writes Main's Published value. Test the intended connection before changing a live default.

Before launch, select the target Environment and supply the provider Secret's **Default value** for its published agent; a Draft override alone does not supply Published. [Publish the tested configuration](/docs/documentation/deploy/environments/publishing), then repeat the conversation test against that Environment's published client and verify the provider account/resource it reaches.

Rotate the credential with the provider owner, update the relevant Secret default/Environment overrides, and retest the existing tool. Removing a tool from Voiceflow does not remove the provider deployment or revoke its credential. Disable/revoke access in Microsoft Power Automate when retiring the integration, then remove the unused attachment and API resource.
