Voiceflow

https://docs.voiceflow.com/docs
Admin
Voiceflow is a platform to build, manage, and deliver chat and voice agents for customer support and...
Tokens:102,855
Snippets:944
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Configure Complete Customer Onboarding Agent

Source: https://docs.voiceflow.com/docs/agent-to-agent-examples

Sets up a Voiceflow agent to manage a multi-step customer onboarding process. This configuration details the agent's goal of guiding new users through account setup, identity verification, and initial transactions, along with collecting comprehensive user information.

```yaml
name: Complete Customer Onboarding
description: Test agent's ability to guide new customers through full onboarding

agent:
  goal: "Complete account setup, verify identity, and make first transaction"
  persona: "A cautious new customer who wants to understand each step thoroughly"
  maxSteps: 25
  userInformation:
    - name: 'full_name'
      value: 'Sarah Johnson'
    - name: 'email'
      value: 'sarah.johnson@email.com'
    - name: 'phone'
      value: '555-456-7890'
    - name: 'ssn_last_four'
      value: '1234'
    - name: 'address'
      value: '789 Pine Ave, Cityville, State 12345'
    - name: 'employment'
      value: 'Marketing Manager at Tech Corp'
    - name: 'initial_deposit'
      value: '1000'
```

--------------------------------

### Execute Voiceflow Tests with JavaScript Fetch API

Source: https://docs.voiceflow.com/docs/usage-examples

Demonstrates how to start a test execution and poll for its status using the JavaScript `fetch` API. It includes examples for using custom subdomains and iterating through multiple environments.

```javascript
// Execute a test suite with custom subdomain
const response = await fetch('http://localhost:8080/api/v1/tests/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: "VF.DM.YOUR_API_KEY",
    voiceflow_subdomain: "staging-env", // Optional: use custom subdomain
    suite: {
      name: "Example Suite",
      description: "Suite used as an example",
      environment_name: "production",
      tests: [
        {
          id: "test_1",
          test: {
            name: "Example test",
            description: "These are some tests",
            interactions: [
              {
                id: "test_1_1",
                user: {
                  type: "text",
                  text: "hi"
                },
                agent: {
                  validate: [
                    {
                      type: "contains",
                      value: "hello"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  })
});

const execution = await response.json();
console.log('Execution ID:', execution.id);

// Poll for status
const statusResponse = await fetch(`http://localhost:8080/api/v1/tests/status/${execution.id}`);
const status = await statusResponse.json();
console.log('Status:', status.status);
console.log('Logs:', status.logs);

// Example with multiple environments
const environments = [
  { name: "production", subdomain: "" }, // Use global subdomain
  { name: "staging", subdomain: "staging-env" },
  { name: "development", subdomain: "dev-env" }
];

for (const env of environments) {
  const envResponse = await fetch('http://localhost:8080/api/v1/tests/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      api_key: "VF.DM.YOUR_API_KEY",
      voiceflow_subdomain: env.subdomain,
      suite: {
        name: `${env.name} Test Suite`,
        description: `Testing against ${env.name} environment`,
        environment_name: "production",
        tests: [/* your tests here */]
      }
    })
  });
  
  const envExecution = await envResponse.json();
  console.log(`${env.name} execution started:`, envExecution.id);
}
```

--------------------------------

### Configure Software Installation Help Agent

Source: https://docs.voiceflow.com/docs/agent-to-agent-examples

Sets up a Voiceflow agent to assist users with software installation issues. The configuration outlines the agent's goal, the user's persona, maximum interaction steps, and collects technical details like operating system, software name, error messages, and computer specifications.

```yaml
name: Software Installation Issue
description: Test agent's ability to provide technical support

agent:
  goal: "Get help installing software that keeps failing"
  persona: "A non-technical user who's frustrated with repeated installation failures"
  maxSteps: 20
  userInformation:
    - name: 'operating_system'
      value: 'Windows 11'
    - name: 'software_name'
      value: 'Adobe Creative Suite'
    - name: 'error_message'
      value: 'Installation failed: Error code 1603'
    - name: 'computer_specs'
      value: '16GB RAM, Intel i7 processor'
```

--------------------------------

### Starting Voiceflow Dialog in Bash

Source: https://docs.voiceflow.com/docs/start

The 'voiceflow dialog start' command initiates an interactive conversation with a Voiceflow project to test dialog flows. It requires the Voiceflow CLI to be installed and an active project set up. Options allow specifying environment, user ID, recording file, and test saving, producing outputs as conversational responses in the terminal, with limitations such as dependency on project configuration and environment availability.

```bash
voiceflow dialog start
```

```bash
voiceflow dialog start --user-id user123
```

```bash
voiceflow dialog start --record-file my-conversation.json
```

```bash
voiceflow dialog start --save-test
```

```bash
voiceflow dialog start -e production
```

--------------------------------

### Voiceflow Dialog Basic Usage Examples (Bash)

Source: https://docs.voiceflow.com/docs/dialog

Demonstrates basic command-line interactions for starting and replaying conversations with Voiceflow. Supports environment and file input options.

```bash
# Start a new conversation in the development environment
voiceflow dialog start

# Replay a recorded conversation
voiceflow dialog replay -f conversation.json

# Start a conversation in the production environment
voiceflow dialog start -e production
```

--------------------------------

### Install Voiceflow CLI via Snapcraft

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using the Snapcraft package manager. Requires sudo privileges.

```sh
sudo snap install voiceflow
```

--------------------------------

### Start Voiceflow Test Execution with Curl

Source: https://docs.voiceflow.com/docs/usage-examples

Initiates a test execution against the Voiceflow API. It accepts an optional API key and custom subdomain, along with a test suite definition. The output is a JSON object containing the execution ID.

```bash
curl -X POST http://localhost:8080/api/v1/tests/execute \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key (optional)","voiceflow_subdomain": "your_custom_subdomain (optional)","suite": {"name": "Example Suite","description": "Suite used as an example","environment_name": "production","tests": [{"id": "test_1","test": {"name": "Example test","description": "These are some tests","interactions": [{"id": "test_1_1","user": {"type": "text","text": "hi"},"agent": {"validate": [{"type": "contains","value": "hello"}]}}]}}]}}'
```

```bash
curl -X POST http://localhost:8080/api/v1/tests/execute \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "VF.DM.YOUR_API_KEY",
    "voiceflow_subdomain": "staging-env",
    "suite": {
      "name": "Staging Environment Test",
      "description": "Testing against staging environment",
      "environment_name": "production",
      "tests": [
        {
          "id": "staging_test_1",
          "test": {
            "name": "Basic staging test",
            "description": "Test against staging subdomain",
            "interactions": [
              {
                "id": "staging_interaction_1",
                "user": {
                  "type": "launch"
                },
                "agent": {
                  "validate": [
                    {
                      "type": "contains",
                      "value": "welcome"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }'
```

--------------------------------

### Install Voiceflow CLI via Go

Source: https://docs.voiceflow.com/docs/cli-install

Installs the latest version of the Voiceflow CLI using the Go programming language's install command.

```sh
go install github.com/xavidop/voiceflow-cli@latest
```

--------------------------------

### Test Multiple Environments and Monitor Executions (Python)

Source: https://docs.voiceflow.com/docs/usage-examples

This example shows how to iterate through a list of environments, execute a test suite against each, and then monitor the status of all initiated executions. It utilizes the 'requests' library.

```python
import requests
import time

environments = [
    {"name": "production", "subdomain": ""},  # Use global subdomain
    {"name": "staging", "subdomain": "staging-env"},
    {"name": "development", "subdomain": "dev-env"}
]

execution_ids = []

for env in environments:
    print(f"\nStarting test for {env['name']} environment...")
    
    response = requests.post('http://localhost:8080/api/v1/tests/execute', json={
        'api_key': 'VF.DM.YOUR_API_KEY',
        'voiceflow_subdomain': env['subdomain'],
        'suite': {
            'name': f"{env['name']} Test Suite",
            'description': f"Testing against {env['name']} environment",
            'environment_name': 'production',
            'tests': [
                # Your test definitions here
            ]
        }
    })
    
    execution = response.json()
    execution_ids.append((env['name'], execution['id']))
    print(f"{env['name']} execution started: {execution['id']}")

# Monitor all executions
print("\nMonitoring all executions...")
for env_name, execution_id in execution_ids:
    print(f"\nChecking {env_name} ({execution_id})...")
    status_response = requests.get(f"http://localhost:8080/api/v1/tests/status/{execution_id}")
    status = status_response.json()
    print(f"Status: {status['status']}")
```

--------------------------------

### Install Voiceflow CLI via Apt

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using the Apt package manager. Requires adding a custom repository and updating package lists.

```sh
echo 'deb [trusted=yes] https://apt.fury.io/xavidop/ /' | sudo tee /etc/apt/sources.list.d/voiceflow.list
sudo apt update
sudo apt install voiceflow
```

--------------------------------

### Install Voiceflow CLI via Nix (nixpkgs)

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using Nix package manager from the main nixpkgs channel. Note that this package might be outdated.

```sh
nix-env -iA voiceflow
```

--------------------------------

### Execute a Basic Test Suite and Poll for Completion (Python)

Source: https://docs.voiceflow.com/docs/usage-examples

This basic example shows how to execute a Voiceflow test suite without a custom subdomain and then poll for its completion status. It depends on the 'requests' and 'time' libraries.

```python
import requests
import time

# Execute a test suite
response = requests.post('http://localhost:8080/api/v1/tests/execute', json={
    'api_key': 'your_api_key (optional)',
    'suite': {
        'name': 'Example Suite',
        'description': 'Suite used as an example',
        'environment_name': 'production',
        'tests': [
            {
                'id': 'test_1',
                'test': {
                    'name': 'Example test',
                    'description': 'These are some tests',
                    'interactions': [
                        {
                            'id': 'test_1_1',
                            'user': {
                                'type': 'text',
                                'text': 'hi'
                            },
                            'agent': {
                                'validate': [
                                    {
                                        'type': 'contains',
                                        'value': 'hello'
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    }
})
execution = response.json()
print(f"Execution ID: {execution['id']}")

# Poll for completion
while True:
    status_response = requests.get(f"http://localhost:8080/api/v1/tests/status/{execution['id']}")
    status = status_response.json()
    
    print(f"Status: {status['status']}")
    
    if status['status'] in ['completed', 'failed']:
        print("Logs:")
        for log in status['logs']:
            print(f"  {log}")
        break
    
    time.sleep(1)
```

--------------------------------

### E-commerce Agent: Order Tracking (YAML)

Source: https://docs.voiceflow.com/docs/agent-to-agent-examples

This example defines an agent to help customers track their orders, particularly when experiencing delays. It includes the customer's objective, persona, and necessary details for order identification and delivery.

```yaml
name: Order Status Inquiry
description: Test agent's ability to provide order updates

agent:
  goal: "Find out when my delayed order will arrive"
  persona: "An impatient customer whose order is late for a special occasion"
  maxSteps: 10
  userInformation:
    - name: 'order_number'
      value: 'ORD-555123'
    - name: 'phone'
      value: '555-987-6543'
    - name: 'delivery_address'
      value: '123 Main St, City, State'
    - name: 'expected_date'
      value: 'January 10, 2025'
```

--------------------------------

### Make GET Request in Voiceflow (JavaScript)

Source: https://docs.voiceflow.com/docs/developing-functions

Voiceflow provides a modified fetch API for network requests. This example demonstrates a GET request to an external API.

```javascript
export default async function main(args) {  	  
  const response = await fetch(`https://cat-fact.herokuapp.com/facts`);  
  const responseBody = response.json; // Accessing the response body

  // ... (process responseBody)  
}
```

--------------------------------

### GET /api/v1/tests/status/{executionId}

Source: https://docs.voiceflow.com/docs/usage-examples

Polls for the status of a previously executed test suite. Returns the current status and logs.

```APIDOC
## GET /api/v1/tests/status/{executionId}

### Description
Polls for the status of a test execution.

### Method
GET

### Endpoint
`/api/v1/tests/status/{executionId}`

### Parameters
#### Path Parameters
- **executionId** (string) - Required - The ID of the test execution to poll for.

#### Response
#### Success Response (200)
- **status** (string) - The current status of the execution (e.g., 'running', 'completed', 'failed').
- **logs** (array) - An array of log messages related to the execution.
```

--------------------------------

### Configure Test Suite YAML

Source: https://docs.voiceflow.com/docs/contains

Defines test suite configuration with environment settings and test file references. The suite uses production environment and references individual test files for execution. Required fields include name, description, environmentName, and tests array.

```yaml
# suite.yaml

name: Example Suite
description: Suite used as an example
environmentName: production
tests:
  - id: test_id
    file: ./test.yaml
```

--------------------------------

### GET /health

Source: https://docs.voiceflow.com/docs/usage-examples

Health check endpoint to verify the service is running and responsive. Returns a simple status indicating the health of the API service.

```APIDOC
## GET /health

### Description
Health check endpoint to verify the service is running and responsive. Returns a simple status indicating the health of the API service.

### Method
GET

### Endpoint
/health

### Parameters
None

### Request Example
GET http://localhost:8080/health

### Response
#### Success Response (200)
- **status** (string) - Service health status, typically "healthy" or "ok"

#### Response Example
{
  "status": "healthy"
}
```

--------------------------------

### Basic PDF file upload example

Source: https://docs.voiceflow.com/docs/upload-files

Simple example demonstrating how to upload a PDF document to the knowledge base. Takes a local file path as input and uploads it without additional processing options. Useful for quick document additions to the knowledge base.

```bash
voiceflow document upload-file \
  --file ./docs/api.pdf
```

--------------------------------

### Configure Hotel Booking Agent

Source: https://docs.voiceflow.com/docs/agent-to-agent-examples

Sets up a Voiceflow agent to handle hotel reservation requests. It specifies the agent's goal, persona, maximum steps, and collects essential user information like loyalty number, dates, destination, room preference, and budget.

```yaml
name: Hotel Reservation
description: Test agent's ability to handle hotel bookings

agent:
  goal: "Book a hotel room for a business trip next week"
  persona: "A busy business traveler who needs accommodation quickly"
  maxSteps: 16
  userInformation:
    - name: 'loyalty_number'
      value: 'REWARDS123456'
    - name: 'dates'
      value: 'January 20-22, 2025'
    - name: 'destination'
      value: 'Chicago, IL'
    - name: 'room_preference'
      value: 'non-smoking, king bed'
    - name: 'budget'
      value: 'under $200 per night'
```

--------------------------------

### GET /api/v1/tests/status/:execution_id

Source: https://docs.voiceflow.com/docs/usage-examples

Retrieves the current status and logs of a test execution. Use the execution ID returned from the test execution endpoint to poll for completion and results.

```APIDOC
## GET /api/v1/tests/status/:execution_id

### Description
Retrieves the current status and logs of a test execution. Use the execution ID returned from the test execution endpoint to poll for completion and results.

### Method
GET

### Endpoint
/api/v1/tests/status/{execution_id}

### Parameters
#### Path Parameters
- **execution_id** (string) - Required - The execution ID returned from the POST /api/v1/tests/execute endpoint

### Request Example
GET http://localhost:8080/api/v1/tests/status/550e8400-e29b-41d4-a716-446655440000

### Response
#### Success Response (200)
- **status** (string) - Current execution status (e.g., "running", "completed", "failed")
- **logs** (array/object) - Execution logs containing detailed test results

#### Response Example
{
  "status": "completed",
  "logs": [
    {
      "test_id": "staging_test_1",
      "interaction_id": "staging_interaction_1",
      "status": "passed",
      "message": "Agent response contains expected value: welcome"
    }
  ]
}
```

--------------------------------

### Check Voiceflow Test Execution Status with Curl

Source: https://docs.voiceflow.com/docs/usage-examples

Retrieves the status and logs for a previously started test execution using its unique ID. This is useful for monitoring the progress and results of automated tests.

```bash
curl http://localhost:8080/api/v1/tests/status/YOUR_EXECUTION_ID
```

--------------------------------

### Retrieve System Information via GET API

Source: https://docs.voiceflow.com/docs/api-endpoints

Fetches runtime details about the server instance, including version, Go runtime, OS, and architecture. No inputs required; useful for debugging or compatibility checks. Returns static system properties without dependencies or notable limitations.

```http
GET /api/v1/system/info
```

```json
{
  "version": "1.0.0",
  "go_version": "go1.20.0",
  "os": "linux",
  "arch": "amd64"
}
```

--------------------------------

### Request Object Examples and Conditional Matching (CoffeeScript/JavaScript)

Source: https://docs.voiceflow.com/docs/functions-listen

Examples demonstrating request object structure and conditional transfer matching logic. Shows how incoming user input is evaluated against on queries and how path selection works. Includes both matching and non-matching scenarios with detailed comments explaining the routing behavior.

```CoffeeScript/JavaScript
// request object from button B
{
  type: 'event_B',
  payload: { label: 'another-example' }
}
```

```CoffeeScript/JavaScript
{
  on: { 'event.type': 'event_A' }, // Does not match - 'event_A' != 'event-B'
  dest: 'path-A'
}
```

```CoffeeScript/JavaScript
{
  on: { 'event.type': 'event_B' }, // Matches! - 'event_B' == 'event-B'
  dest: 'path-B'                   // Therefore, follow 'path-B'
}
```

--------------------------------

### Advanced file upload with processing options

Source: https://docs.voiceflow.com/docs/upload-files

Comprehensive example showing advanced upload with multiple processing options including chunk size limits, markdown conversion, LLM-generated questions, and content summarization. Accepts markdown files and applies extensive AI-based processing for enhanced knowledge base integration.

```bash
voiceflow document upload-file \
  --file ./docs/guide.md \
  --max-chunk-size 1000 \
  --markdown-conversion \
  --llm-generated-q \
  --llm-content-summarization \
  --tags guide,user
```

--------------------------------

### Install Voiceflow CLI via Scoop

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using the Scoop package manager. This involves adding a custom bucket and then installing the CLI.

```powershell
scoop bucket add voiceflow https://github.com/xavidop/scoop-bucket.git
scoop install voiceflow
```

--------------------------------

### Install Voiceflow CLI via Chocolatey

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using the Chocolatey package manager for Windows.

```powershell
choco install voiceflow
```

--------------------------------

### POST /api/v1/tests/execute

Source: https://docs.voiceflow.com/docs/usage-examples

Initiates a test execution with a configured test suite. Supports optional API key authentication and custom subdomain targeting for different environments.

```APIDOC
## POST /api/v1/tests/execute

### Description
Initiates a test execution with a configured test suite. This endpoint allows you to run automated tests against Voiceflow agents with customizable interactions and validation rules. Supports optional API key authentication and custom subdomain targeting for different environments.

### Method
POST

### Endpoint
/api/v1/tests/execute

### Parameters
#### Request Body
- **api_key** (string) - Optional - API key for Voiceflow authentication. Format: `VF.DM.YOUR_API_KEY`
- **voiceflow_subdomain** (string) - Optional - Custom subdomain for targeting specific environments (e.g., "staging-env", "dev-env")
- **suite** (object) - Required - Complete test suite configuration
  - **name** (string) - Required - Name of the test suite
  - **description** (string) - Required - Description of the test suite
  - **environment_name** (string) - Required - Target environment name (typically "production")
  - **tests** (array) - Required - Array of test objects
    - **id** (string) - Required - Unique identifier for the test
    - **test** (object) - Required - Test configuration object
      - **name** (string) - Required - Name of the test
      - **description** (string) - Required - Description of the test
      - **interactions** (array) - Required - Array of interaction steps
        - **id** (string) - Required - Interaction step ID
        - **user** (object) - Required - User input definition
          - **type** (string) - Required - Input type: "text" or "launch"
          - **text** (string) - Optional - Text input (required when type is "text")
        - **agent** (object) - Required - Agent response validation
          - **validate** (array) - Required - Array of validation rules
            - **type** (string) - Required - Validation type (e.g., "contains")
            - **value** (string) - Required - Value to validate against

### Request Example
{
  "api_key": "VF.DM.YOUR_API_KEY",
  "voiceflow_subdomain": "staging-env",
  "suite": {
    "name": "Staging Environment Test",
    "description": "Testing against staging environment",
    "environment_name": "production",
    "tests": [
      {
        "id": "staging_test_1",
        "test": {
          "name": "Basic staging test",
          "description": "Test against staging subdomain",
          "interactions": [
            {
              "id": "staging_interaction_1",
              "user": {
                "type": "launch"
              },
              "agent": {
                "validate": [
                  {
                    "type": "contains",
                    "value": "welcome"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

### Response
#### Success Response (200)
- **id** (string) - Execution ID for tracking the test run

#### Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Install Voiceflow CLI via Homebrew

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using the Homebrew package manager by tapping a custom repository.

```sh
brew install xavidop/tap/voiceflow
```

--------------------------------

### Initialize Telegraf Bot in JavaScript

Source: https://docs.voiceflow.com/docs/deploy-telegram

Imports Telegraf library and sets up a basic Telegram bot instance using an environment token. Defines simple handlers for start command and 'hi' message, then launches the bot. Requires telegraf package and BOT_TOKEN in .env; inputs are user messages, outputs are replies.

```javascript
const Telegraf = require('telegraf') // import telegram lib

const bot = new Telegraf(process.env.BOT_TOKEN) // get the token from envirenment variable
bot.start((ctx) => ctx.reply('Welcome')) // display Welcome text when we start bot
bot.hears('hi', (ctx) => ctx.reply('Hey there')) // listen and handle when user type hi text
bot.launch() // start
```

--------------------------------

### Install Voiceflow CLI via AUR (yay)

Source: https://docs.voiceflow.com/docs/cli-install

Installs the Voiceflow CLI using the `yay` helper for the Arch User Repository (AUR).

```sh
yay -S cxcli-bin
```
Tokens:
Raw