# Analytics API
Source: https://docs.voiceflow.com/api-reference/analytics-api/overview
Query usage metrics, access transcripts, and evaluate conversation quality.
The Analytics API gives you programmatic access to data about how your agent is performing. You can use it to [query aggregate usage metrics](/api-reference/usage/query-usage), [retrieve conversation transcripts](/api-reference/transcript/search-transcripts), and [run automated evaluations](/api-reference/transcript-evaluation/run-transcript-evaluation) to assess conversation quality at scale.
## Endpoints
| Endpoint | Description | |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Usage** | | |
| POST [Query usage](/api-reference/usage/query-usage) | Query aggregate usage metrics for a project. Supports interactions, sessions, unique users, top intents, credit consumption, function usage, API calls, knowledge base documents, integrations, transcripts, and per-agent activity. | |
| **Transcript** | | |
| POST [Search transcripts](/api-reference/transcript/search-transcripts) | Search for transcripts matching a set of filters. Supports filtering by date range, environment, session ID, custom properties, and evaluation results. | |
| GET [Get transcript](/api-reference/transcript/get-transcript) | Fetch a single transcript with its full conversation logs, properties, and evaluation results. | |
| DELETE [Delete transcript](/api-reference/transcript/delete-transcript) | Permanently remove a transcript along with its logs and all evaluation results. | |
| POST [End transcript](/api-reference/transcript/end-transcript) | Mark a transcript as complete. Triggers any enabled evaluations to run automatically. | |
| **Transcript property** | | |
| GET [Get all transcript properties](/api-reference/transcript-property/get-all-transcript-properties) | List all custom property definitions for a project. | |
| GET [Get transcript property](/api-reference/transcript-property/get-transcript-property) | Fetch the definition of a single transcript property. | |
| POST [Create transcript property](/api-reference/transcript-property/create-transcript-property) | Define a new custom property for tagging transcripts in a project. | |
| PATCH [Update transcript property](/api-reference/transcript-property/update-transcript-property) | Update the name or type of an existing transcript property definition. | |
| DELETE [Delete transcript property](/api-reference/transcript-property/delete-transcript-property) | Remove a property definition and its values from all transcripts in the project. | |
| **Transcript property value** | | |
| GET [Get all transcript property values](/api-reference/transcript-property-value/get-all-transcript-property-values) | Retrieve all property values set on a specific transcript. | |
| POST [Set transcript property value](/api-reference/transcript-property-value/set-transcript-property-value) | Attach a value to a property on a specific transcript. | |
| DELETE [Delete transcript property value](/api-reference/transcript-property-value/delete-transcript-property-value) | Remove a single property value from a transcript without affecting the property definition. | |
| **Transcript evaluation** | | |
| GET [Get all evaluations](/api-reference/transcript-evaluation/get-all-evaluations) | List all evaluation definitions for a project, including result counts per evaluation. | |
| GET [Get transcript evaluation](/api-reference/transcript-evaluation/get-transcript-evaluation) | Fetch the definition of a single evaluation. | |
| POST [Create transcript evaluation](/api-reference/transcript-evaluation/create-transcript-evaluation) | Define a new LLM-based evaluation. Supports boolean, numeric rating, free-text, and option types. | |
| PATCH [Update transcript evaluation](/api-reference/transcript-evaluation/update-transcript-evaluation) | Update the definition of an existing evaluation, including its prompt, model settings, and type-specific fields. | |
| DELETE [Delete transcript evaluation](/api-reference/transcript-evaluation/delete-transcript-evaluation) | Remove an evaluation definition along with all its results across every transcript. | |
| POST [Run transcript evaluation](/api-reference/transcript-evaluation/run-transcript-evaluation) | Run a single evaluation against a specific transcript and return the result immediately. | |
| POST [Batch run transcript evaluations](/api-reference/transcript-evaluation/batch-run-transcript-evaluations) | Queue up to 10 evaluations across up to 100 transcripts in a single request. | |
| POST [Estimate transcript evaluation](/api-reference/transcript-evaluation/estimate-transcript-evaluation) | Calculate the expected cost of running evaluations against transcripts matching a set of filters before committing to a batch run. | ## Concepts |
### Transcripts
[Transcripts](/documentation/measure/transcripts) are full records of each conversation. You can [search](/api-reference/transcript/search-transcripts), [retrieve](/api-reference/transcript/get-transcript), and [delete](/api-reference/transcript/delete-transcript) them, or [mark them as ended](/api-reference/transcript/end-transcript). Ending a transcript signals that the conversation is complete and triggers any enabled evaluations to run automatically.
Transcript properties are custom metadata fields you define at the project level and attach to individual transcripts. They're useful for tagging conversations with context that isn't captured automatically, such as a support ticket ID or a user segment. Once defined, you can filter transcript searches by property values.
### Evaluations
[Evaluations](/documentation/measure/evaluations) are automated, LLM-based quality assessments that run against your transcripts. You define an evaluation with a prompt describing what you're measuring and an output type - a pass/fail boolean, a numeric rating, a free-text response, or a selection from a predefined set of options. Evaluations can run automatically whenever a transcript ends, or you can [trigger them manually against individual transcripts](/api-reference/transcript-evaluation/run-transcript-evaluation) or [in batches](/api-reference/transcript-evaluation/batch-run-transcript-evaluations).
# Overview
Source: https://docs.voiceflow.com/api-reference/api-overview
Build custom integrations and manage your agents programmatically.
Voiceflow's APIs let you build custom interfaces, manage your knowledge base programmatically, access transcripts and analytics, and integrate Voiceflow into your existing systems.
To get started, you'll need a Voiceflow API key. Open **Settings** → **API keys** in your project to generate one.
## APIs
Interact with your AI Agents via API.
Pull your usage data, transcripts, evaluations, and more.
Manage and query your Knowledge Base.
Manage your Voiceflow projects and environments.
## Webhooks
Receive events whenever phone calls start or end.
Receive events when projects are created, published, or deleted.
# Authentication
Source: https://docs.voiceflow.com/api-reference/authentication
Connecting to your agent via Voiceflow's APIs.
All requests to Voiceflow's APIs require an API key, a project ID, and in most cases an environment alias. These three values tell the API who you are, which agent you're targeting, and which environment of it to run.
## Finding your API key
API keys are managed in **Settings** → **API keys**. Each project has its own API key, and all Voiceflow API keys begin with `VF.DM.`.
![Clean Shot 2026 03 13 At 12 43 30@2x]()
You can have a primary key and a secondary key active at the same time. This is useful for rotating keys without downtime - generate a secondary key, update your integration to use it, then promote it to primary and delete the old one. To create a secondary key, click the **...** menu next to your primary key and select **Create secondary key**. Once you're ready to rotate, click **Promote** next to the secondary key to make it primary.
Pass your API key in the `Authorization` header of every request:
```bash theme={null}
Authorization: VF.DM.your_api_key
```
Never share your API key or commit it to source control.
## Project ID and environment alias
Your project ID is available in **Settings** → **General** under the **Metadata** section.
![Clean Shot 2026 03 13 At 12 45 30@2x]()
The **Project ID** identifies your agent and is required for most API requests.
To identify which environment to target, pass its **alias**. Every environment in a project has a short, URL-safe alias you can copy from the **Alias** column in **Settings** → **Environments**. By default, a new project has a single environment called **Main** with alias `main`. Aliases are static, so you can rename an environment without breaking any integrations that point at it.
Using an alias (rather than a specific version ID) means your integration always targets whichever version is currently live for that environment, so your users pick up changes as soon as you publish them. See [Environments](/documentation/deploy/environments) for the full model.
If your project was created before environments launched and has not yet been migrated, you can continue to use the legacy `development`, `staging`, and `production` aliases. After migrating, switch your integrations to use your new environment aliases.
# Interact - legacy (stream)
Source: https://docs.voiceflow.com/api-reference/conversation/interact--legacy-stream
/specs/general-runtime/openapi.public.json post /v2/project/{projectID}/user/{userID}/interact/stream
This endpoint is deprecated. Use the [Interact (stream)](/api-reference/conversation/interact-stream) endpoint instead. This legacy endpoint will continue to work for now, and we'll communicate a timeline for removal when one is available. We recommend migrating as soon as possible.
Returns a stream of trace events followed by an end event using [SSE](https://en.wikipedia.org/wiki/Server-sent_events).
# Completion Events
Source: https://docs.voiceflow.com/api-reference/conversations-api/completion-events
When conversing with LLMs such as ChatGPT or Claude, you notice that unlike human communications, where we send complete message by complete message, it "streams" in the text one piece at a time, and not even necessarily in complete words. LLMs work by generating their responses token by token.
![]()
It can take quite long for an LLM to write a complete paragraph - even for the fastest models.
With the **Response AI / Prompt** step, by default the API will wait for the entire response to be generated before sending the text back. This can often take a few seconds and mean users have to wait a long time and then suddenly get a very long message.
By setting the `?completion_events=true` query parameter in the [Interact Stream](/api-reference/v4interact/interact-stream) API, Voiceflow will return output from the **Response AI / Prompt** steps as a text stream as it's generated, which can be shown to the user on an interface capable of handling partial responses.
> 📘 Only the **Response AI / Prompt** step produces completion events
## Example Response `completion_events=false`
```json Response theme={null}
event: trace
id: 1
data: {
"type": "text",
"payload": {
"message": "Welcome to our service. How can I help you today? Perhaps you're interested in our latest offers or need assistance with an existing order? Let me know if you have any other questions!",
},
"time": 1725899197143
}
event: end
id: 2
```
This is what a response might look like normally. The user might have to wait a bit before seeing the message.
## Example Response `completion_events=true`
```json Response theme={null}
event: trace
id: 1
data: {
"type": "completion",
"payload": {
"state": "start"
},
"time": 1725899197143
}
event: trace
id: 2
data: {
"type": "completion",
"payload": {
"state": "content",
"content": "Welcome to our service. How can I help you today? Perh",
},
"time": 1725899197144
}
event: trace
id: 3
data: {
"type": "completion",
"payload": {
"state": "content",
"content": "aps you're interested in our latest offers or need ",
},
"time": 1725899197145
}
event: trace
id: 4
data: {
"type": "completion",
"payload": {
"state": "content",
"content": "assistance with an existing order? Let",
},
"time": 1725899197146
}
event: trace
id: 5
data: {
"type": "completion",
"payload": {
"state": "content",
"content": " me know if you have any other questions!",
},
"time": 1725899197147
}
event: trace
id: 6
data: {
"type": "completion",
"payload": {
"state": "end",
},
"time": 1725899197148
}
event: end
id: 7
```
With `completion_events` turned on, it still takes the same total time to get the entire message, but the user will be able to see the first chunk of text within milliseconds: *Welcome to our servi..."*
Enabling `completion_events` means the API will return a `completion` trace instead of a `text` (or `speak`) trace. There is a `payload.state` property which is one of three values:
* `state: "start"` to signal the start of a completion stream.
* `state: "content"` to stream in additional text to the same text block, under the `content` property
* `state: "end"` to signal that the completion is now finished, and the final LLM token usage
These trace types facilitate the delivery of text streaming as the large language model (LLM) generates the response message. Note, the `content` data may not always be in complete sentences or words.
It is the responsibility of the API caller to stitch the data together and have it reflect live on the conversation interface.
## Examples
See our [`streaming-wizard`](https://github.com/voiceflow/streaming-wizard) demo (NodeJS). Note the use of the `"end"` state as a marker to start a new line in the conversation.
## Deterministic and Streamed Messages
It may be jarring to pair this with existing deterministic messages that come out fully completed. Some messages stream in, while others are sent as whole. To mitigate this, you can either:
* create a fake streaming effect for deterministic messages that matches what messages streamed through completion events look like
* accumulate enough completion traces to form a complete sentence, and send group streamed responses into sentences before displaying them. Look for delimiters such as `.` `?` `!` `;` `\n` (newline). You can then send the completion as a group of smaller complete messages.
# Interact (socket)
Source: https://docs.voiceflow.com/api-reference/conversations-api/interact-socket
The Voiceflow WebSocket runtime uses [socket.io](https://socket.io/) to establish persistent, bidirectional connections for real-time conversational AI interactions.
Find the [socket.io client](https://github.com/socketio) in your respective development language. This documentation will use javascript, but the fundamentals remain the same.
## Connection configuration
```js theme={null}
import { io } from 'socket.io-client';
const socket = io('https://general-runtime.voiceflow.com', {
path: '/v4/interact/socket',
timeout: 10000,
transports: ['websocket', 'polling', 'webtransport'], // optional fallbacks
reconnection: true,
tryAllTransports: true,
reconnectionDelay: 1000,
reconnectionAttempts: 5,
reconnectionDelayMax: 5000,
});
```
[socket.io](http://socket.io) allows for fallback transports if the end-client does not allow the websocket protocol (wss\://), common in many firewalls and enterprise settings.
## Lifecycle
A session is not the same as the socket.io connection. You can disconnect/reconnect multiple times and still continue the same conversation session.
For more information on socket.io lifecycle management, reference [documentation](https://socket.io/docs/v4/client-api/).
### Initialization sequence
1. Wait for `connect`. This is a socket.io level connection established.
2. Send `client.start`. Send voiceflow project metadata/config + optional `sessionKey`.
3. Wait for `client.started`. Client handshake, confirms configuration.
4. If `client.started` specifies `newSessionRequired`:
1. Send `session.create`.
2. Wait for `session.created`. Save returned `sessionKey` for future use.
5. Agent is now ready for interactions
```ts theme={null}
// save sessionKey on client side for future reconnections
let sessionKey: string | undefined;
// socket.io level connection
socket.on('connect', () => {
// voiceflow client handshake
socket.emit('client.start', { sessionKey, ...metadata });
socket.once('client.started', (payload: { newSessionRequired: boolean }) => {
if (payload.newSessionRequired === false) {
return ready();
}
// session create handshake
socket.emit('session.create', {});
socket.once('session.created', (payload: { sessionKey: string }) => {
sessionKey = payload.sessionKey;
ready();
});
});
})
```
### Action Lifecycle
Once the session is ready, you can now send actions to the agent and get responses back.
1. send new action with `action.send`, i.e. `{ type: 'text', payload: 'hello' }`
2. get back a status `action.status` either `status: 'accepted' | 'rejected'`
3. if `status: accepted`:
1. get back agent responses with `action.trace`, display to user
2. get `action.status` with `status: 'completed'`
This represents the back and forth conversation with the agent.
Try to not send a new action while an existing action is running. While this is supported, it can make it harder to debug user state and lead to certain race conditions.
Instead wait for `status: 'completed'` or `status: 'rejected'` after sending an action.
### Conversation Lifecycle
#### Start
To start the conversation from the beginning, your first action should be:
```ts theme={null}
socket.emit('action.send', {
action: { type: 'launch', payload: {} }
});
```
It is also possible to launch from specific points in the conversation with [events](https://docs.voiceflow.com/docs/introduction-to-events):
```ts theme={null}
socket.emit('action.send', {
action: { type: 'event', payload: { event: { name: 'event_name' } } }
});
```
#### End
The session ending also signals that the conversation has ended. This can also occur because of timeouts.
```ts theme={null}
socket.on('session.ended', () => {
// cleanup code
})
```
## Client events
### `client.start`
Initial Voiceflow metadata and configuration to validate and set up the client. This is aways the first message that the client should send to the server after socket.io successfully connects. Server will respond with `client.started`.
#### Payload
`?:` denotes optional properties.
```ts theme={null}
interface ClientStartPayload {
userID: string; // primary user identifier
projectID: string; // voiceflow projectID
// alias of the environment to use. Omit to route the session via the project's
// traffic split (hashed by userID, so a given userID routes consistently).
environmentID?: string;
// session to reconnect to, ignore if new session
sessionKey?: string | null;
// voiceflow project API Key (under settings), do not set for public facing clients
authorization?: string;
config?: {
// break up LLM responses into live chunks [default: false]
completionEvents: boolean;
// timezone in IANA (tz database) for the vf_user_timezone variable
userTimezone?: string;
audioEvents: boolean; // enable TTS audio chunk responses
audioEncoding?: 'audio/x-mulaw' | 'audio/pcm'; // audio response format
};
}
```
#### Example Call
```ts theme={null}
socket.emit('client.start', {
userID: 'test@test.com',
projectID: '6939bedf69c7ce5ee7a108ed',
authorization: 'VF.DM...',
config: {
completionEvents: true
};
});
```
### `session.create`
Creates a new session for the user. Should be sent after `client.started` indicates `newSessionRequired: true`. Server will respond with `session.created`.
#### Example Call
```ts theme={null}
socket.emit('session.create', {});
```
### `action.send`
Sends a user action to the server. A valid session must already exist. Server will respond with `action.status` and `action.trace` events.
[See possible action types in the `action` body of interaction requests.](/api-reference/v4interact/interact-stream).
#### Payload
```ts theme={null}
interface ActionSendPayload {
action: {
// request type: "text" | "intent" | "launch" | "event" | "action" | etc.
type: string;
// action-specific payload
payload?: string | object;
};
}
```
#### Example Call
```ts theme={null}
socket.emit('action.send', {
action: {
type: 'text',
payload: 'Hello, how are you?'
}
});
```
## Server events
### `client.started`
Server ack to `client.start`, informs if a new session needs to be created
#### Payload
```ts theme={null}
interface ClientStartedPayload {
newSessionRequired: boolean
}
```
#### Example
```ts theme={null}
socket.on('client.started', (payload: ClientStartedPayload) => {
if (payload.newSessionRequired) {
socket.emit('session.create', {});
} else {
// session is now ready for interactions
}
});
```
### `session.created`
Confirms that a new session has been created. Client should store the `sessionKey` for future reconnections.
#### Payload
```ts theme={null}
interface SessionCreatedPayload {
sessionKey: string; // JWT session key to store and use for reconnections
}
```
#### Example
```ts theme={null}
socket.on('session.created', (payload: SessionCreatedPayload) => {
localStorage.setItem('sessionKey', payload.sessionKey);
// session is now ready for interactions
});
```
### `session.ended`
Indicates that the conversation session has ended. Client should close the session and optionally display a workflow to create a new one.
#### Payload
```ts theme={null}
interface SessionEndedPayload {
// reason for session ending (e.g., "end_of_diagram", "inactivity_timeout", etc.)
reason: string;
}
```
### `action.trace`
Represents agent responses and debugging information for an action. [See possible trace types](/api-reference/trace-types).
#### Payload
```ts theme={null}
type ActionTracePayload = {
// trace object containing agent response data (speak, text, audio, etc.)
trace: Trace;
// message identifier matching the action.send messageID
messageID: string;
}
```
#### Example
```ts theme={null}
socket.on('action.trace', (payload: ActionTracePayload) => {
// Handle trace data (speech, text, audio chunks, etc.)
console.log('Trace received:', payload.trace);
});
```
### `action.status`
Indicates the status of an action that was sent via `action.send`. This event is sent when an action is accepted, rejected, or completed.
#### Payload
```ts theme={null}
interface ActionStatusPayload {
status: 'accepted' | 'rejected' | 'completed'; // action status
messageID: string; // message identifier matching the action.send messageID
reason?: string; // optional reason for rejection or completion
}
```
### `server.restart`
Server is gracefully shutting down and informing the client to reconnect to a different server instance.
#### Payload
```ts theme={null}
interface ServerRestartPayload {
action?: {
type: string;
payload?: string | object;
diagramID?: string;
time?: number;
}; // optional action to replay after reconnection
}
```
### `error`
General error message from the server. May occur at any point during the connection.
#### Payload
```ts theme={null}
interface ErrorPayload {
code?: string; // optional error code
error: string; // error message
}
```
# Conversations API
Source: https://docs.voiceflow.com/api-reference/conversations-api/overview
Use the Conversations API to run turns, manage session state, inject variables, and control your Voiceflow agent's runtime over HTTP.
Voiceflow's Conversations API allows you to programmatically interact with a Voiceflow agent. This allows you to build custom interfaces for users to access your agent through, or to pull information about active sessions into your tooling.
You can use the Conversations API to run [conversation turns](/api-reference/v4interact/interact-non-stream), [send events](/api-reference/session/emit-session-event), [read](/api-reference/state/get-conversation-state) and [modify session state](/api-reference/state/update-conversation-state), and [inject variables](/api-reference/state/update-conversation-variables) - giving you full control over how your agent runs inside your own application.
## Available endpoints
| Endpoint | Description |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conversation** | |
| POST [Interact (non-stream)](/api-reference/v4interact/interact-non-stream) | Returns an array of traces in response to a user interaction. Accepts state variables, request, action, and config in the body. |
| POST [Interact (stream)](/api-reference/v4interact/interact-stream) | SSE endpoint that returns a stream of `trace` events followed by an `end` event. Supports audio, completion streaming, modality selection, and state return. |
| POST [Interact - legacy (non-stream)](/api-reference/state/interact--legacy-non-stream) | **Deprecated** Returns an array of traces in response to a user interaction. Accepts state variables, request, action, and config in the body. |
| POST [Interact - legacy (stream)](/api-reference/conversation/interact--legacy-stream) | **Deprecated** SSE endpoint that returns a stream of `trace` events followed by an `end` event. Supports audio, completion streaming, modality selection, and state return. |
| **State** | |
| GET [Get conversation state](/api-reference/state/get-conversation-state) | Fetches the current state of a user's conversation, including stack, variables, and storage. |
| PUT [Update conversation state](/api-reference/state/update-conversation-state) | Replaces the full state of a user's conversation (stack, variables, storage). |
| DEL [Delete conversation state](/api-reference/state/delete-conversation-state) | Deletes all state and session data for a user's conversation. |
| PATCH [Update conversation variables](/api-reference/state/update-conversation-variables) | Merges the provided variables into the user's current conversation state. |
| **Session** | |
| POST [Start session](/api-reference/v4interact/start-session-specific-environment) | Starts a new voiceflow conversation session. Used for v4 session management. |
| POST [Emit session event](/api-reference/session/emit-session-event) | Sends an event to an active session. Useful for injecting actions mid-conversation. |
## Actions and traces
When a user [interacts](/api-reference/v4interact/interact-non-stream) with your agent, the request goes to Voiceflow's runtime - the engine that processes each conversation turn, runs your agent's logic, and produces a response. The Conversations API is your interface to that runtime.
Each turn follows a request-response pattern. Your application sends an **action** describing what happened on the user's side, and the runtime processes it and returns a set of **traces** describing how the agent responds.
An action can be a user's message, a launch request to start a new conversation, a button selection, a system event, a no-reply signal, or a handoff continuation. The most common is `text`:
```json theme={null}
{
"action": {
"type": "text",
"payload": "I need help with my order"
}
}
```
Traces are the agent's output. Each turn returns an array of trace objects - a single response often contains several in sequence. For example, a `text` trace with a message, then a `choice` trace presenting reply options. Your application is responsible for rendering each trace type appropriately.
See [Trace types](/api-reference/trace-types) for a complete reference.
## Session state
Voiceflow maintains state for each user across turns using the `userID` you provide. In most cases this is automatic, but the state endpoints give you direct access when you need it. You can [fetch a user's current state](/api-reference/state/get-conversation-state), [update it](/api-reference/state/update-conversation-state), or [delete it to reset the session](/api-reference/state/delete-conversation-state) - useful for testing, debugging, or building custom session management into your integration.
## Variables
Variables let you pass context into an agent's session that it can reference during a conversation. You can [update a user's variables at any point](/api-reference/state/update-conversation-variables) without replacing the full session state. This is useful for pre-loading information before a conversation begins (eg: the user's name, account tier, or current page) so the agent can personalize its responses from the first turn. Note that variables are not automatically reset when a conversation's state is reset.
## Environments
Each request runs against a specific environment in your project. Pass the environment's alias in the `environment` parameter to target it. By default, new projects have a single environment called **Main** with alias `main`; see [Environments](/documentation/deploy/environments) for how to create more.
If your project was created before environments launched and has not yet been migrated, the legacy `development`, `staging`, and `production` aliases continue to work.
# Overview
Source: https://docs.voiceflow.com/api-reference/conversations-api/state-overview
In Voiceflow, a dialog state is assigned to a unique `userID`.
This `userID` can be any string and is typically something unique that easily references the person on the session - such as an username, email, device ID, or phone number. (e.g. `user54646`, `user@gmail.com`, `1-647-424-4242`, etc.).
If you're not sure what to call it just for testing purposes, you can just pick a random `userID`.
The response schema consists of two main properties:
1. Stack
2. Variables
We will cover each property below, as well as an overview of the Voiceflow context model.
## Stack
The stack is an array of flows that are currently active in the conversation. Each flow contains:
* `programID`: the ID of the flow, which can be found in the URL of the address bar `https://creator.voiceflow.com/project/{versionID}/canvas/{programID}`
* `nodeID`: current block this flow is on
* `variables`: flow-scoped variables
* `storage`: internal flow parameters for runtime
* `commands`
In the example below, you can see that there are three flows available on the stack (`620e669eac2f70001cf9d85a`, `620e669eac2f70001cf9d85b` and `620e669eac2f70001cf9d85c`) and we are currently sitting on flow `620e669eac2f70001cf9d85c`, as denoted by the `nodeID` pointing to a block within this flow.
Note: the `programID` of the first flow in the stack is always the `versionID` of the Agent.
Example stack:
```json theme={null}
{
"stack": [
{
"nodeID": null,
"programID": "620e669eac2f70001cf9d85a", //<-- versionID of the agent
"storage": {},
"commands": [],
"variables": {}
},
{
"nodeID": null,
"programID": "620e669eac2f70001cf9d85b", //<-- starting flow
"storage": {
"output": [
{
"children": [
{
"text": "What size?"
}
]
}
]
},
"commands": [],
"variables": {}
},
{
"nodeID": "61f40992f0e4e70a1f2328d1",
"programID": "620e669eac2f70001cf9d85c",//<-- top-level flow
"storage": {
"outputMap": null,
"output": [
{
"children": [
{
"text": "You can get an additional pizza for half the price today. Would you like to do that?"
}
]
}
]
},
"commands": [],
"variables": {
"discount_code": "DEAL4TWO"
}
}
]
}
```
## Variables
The two ways you can create variable keys in your Interaction Model is through:
1. Entities
2. Variables
The difference between Entities and Variables is how they are assigned values at runtime.
An entity value is assigned through a user interaction (e.g. utterance) whereas a variable is dynamically assigned a value from the design itself based on a user action (e.g. through an API call or custom code).
Variable examples
```json theme={null}
{
"variables": {
"type": "pepperoni",
"size": "large",
"amount": 6,
"sessions": 0,
"user_id": "1234",
"timestamp": 1645112935,
"platform": 0,
"locale": 0,
"side": 0,
"intent_confidence": 100,
"last_utterance": "large"
}
}
```
## Voiceflow Context Model
In this video, we'll explain Voiceflow's entire Context Model in more detail.
# Create environment
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/create-environment
/specs/realtime/openapi.public.json post /v1alpha1/project/{projectID}/environment
Create a new environment by cloning another environment. When `alias` is omitted, one is generated from `name`. When `cloneFromEnvironmentID` is omitted, the assistant's main environment is used.
# Delete a project environment
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/delete-a-project-environment
/specs/realtime/openapi.public.json delete /v1alpha1/project/{projectID}/environment/{projectEnvironmentID}
# Export environment JSON
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/export-environment-json
/specs/realtime/openapi.public.json get /v1alpha1/project/{projectID}/environment/{projectEnvironmentAlias}/export-json
Export a specific environment by ID or alias for the target assistant.
# Get environment
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/get-environment
/specs/realtime/openapi.public.json get /v1alpha1/project/{projectID}/environment/{projectEnvironmentIDorAlias}
Get a specific environment by ID or alias for the target assistant.
# Get traffic split
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/get-traffic-split
/specs/realtime/openapi.public.json get /v1alpha1/project/{projectID}/environment/traffic
Get the current traffic split configuration for all environments on the target assistant.
# List environments
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/list-environments
/specs/realtime/openapi.public.json get /v1alpha1/project/{projectID}/environments
List all environments for the target assistant.
# List phone numbers attached to the assistant
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/list-phone-numbers-attached-to-the-assistant
/specs/realtime/openapi.public.json get /v1alpha1/project/{projectID}/phone-numbers
List all phone numbers attached to the target assistant. Optionally filter to a single environment by passing `environmentIDorAlias`.
# Publish environment
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/publish-environment
/specs/realtime/openapi.public.json post /v1alpha1/project/{projectID}/environment/{projectEnvironmentIDorAlias}/publish
Publish the target environment's draft as its new published version. The environment can be targeted by ID or alias.
# Update traffic split
Source: https://docs.voiceflow.com/api-reference/environmentpublicapi/update-traffic-split
/specs/realtime/openapi.public.json patch /v1alpha1/project/{projectID}/environment/traffic
Update the traffic split configuration for all environments on the target assistant. The request can be keyed by environment ID or alias. Percentages must sum to 100.
# Create document
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/create-document
/specs/realtime/openapi.public.json post /v1alpha1/public/knowledge-base/document
Upload or provide a URL to scrape and import as a knowledge base document. Supports both `application/json` and `multipart/form-data` content types.
# Delete document
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/delete-document
/specs/realtime/openapi.public.json delete /v1alpha1/public/knowledge-base/document/{documentID}
Remove a document from the knowledge base.
# Get document
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/get-document
/specs/realtime/openapi.public.json get /v1alpha1/public/knowledge-base/document/{documentID}
Fetch all chunks and metadata for the specified document.
# Replace document
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/replace-document
/specs/realtime/openapi.public.json put /v1alpha1/public/knowledge-base/document/{documentID}
Replaces the target document with the provided content. Supports both `application/json` and `multipart/form-data` content types.
# Search documents
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/search-documents
/specs/realtime/openapi.public.json get /v1alpha1/public/knowledge-base/document
Find all documents that match the specified criteria.
# Update chunk metadata by chunk ID
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/update-chunk-metadata-by-chunk-id
/specs/realtime/openapi.public.json patch /v1alpha1/public/knowledge-base/document/{documentID}/chunk/{chunkID}
Update the metadata associated with the specified document chunk.
# Update document metadata
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/update-document-metadata
/specs/realtime/openapi.public.json patch /v1alpha1/public/knowledge-base/document/{documentID}
Update the metadata associated with the specified document.
The `documentMetadata` field can be used in agent KB metadata filter conditions. The `metadata` field is chunk-level and cannot be used for agent-level filtering. [Learn more about metadata filtering](/documentation/build/querying-the-knowledge-base#meta-data-filtering).
# Upload table document
Source: https://docs.voiceflow.com/api-reference/kbpublicapidocument/upload-table-document
/specs/realtime/openapi.public.json post /v1alpha1/public/knowledge-base/document/upload/table
Upload a structured document to the knowledge base.
# Knowledge base API
Source: https://docs.voiceflow.com/api-reference/knowledge-base-api/overview
Manage your agent's knowledge base documents programmatically
The Knowledge base API gives you programmatic access to the documents that power your agent's knowledge base. YYou can use it to [create](/api-reference/kbpublicapidocument/create-document), [retrieve](/api-reference/kbpublicapidocument/get-document), [update](/api-reference/kbpublicapidocument/update-chunks-metadata), and [delete](/api-reference/kbpublicapidocument/delete-document) documents, as well as manage their metadata and individual chunks.
## Endpoints
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Document** | |
| GET [Search documents](/api-reference/kbpublicapidocument/search-documents) | Retrieve all documents in a project, or filter by type, page, and limit. |
| GET [Get document](/api-reference/kbpublicapidocument/get-document) | Fetch a single document by ID, including its chunks and metadata. |
| POST [Create document](/api-reference/kbpublicapidocument/create-document) | Add a new document to the knowledge base from a URL or integration source. |
| POST [Upload table document](/api-reference/kbpublicapidocument/upload-table-document) | Upload structured table data as a knowledge base document, with optional chunking and LLM processing settings. |
| PUT [Replace document](/api-reference/kbpublicapidocument/replace-document) | Replace an existing document's source and metadata entirely. |
| PATCH [Update chunk metadata](/api-reference/kbpublicapidocument/update-chunks-metadata) | Update the metadata on a specific chunk within a document. |
| PATCH [Update chunk metadata by chunk ID](/api-reference/kbpublicapidocument/update-chunk-metadata-by-chunk-id) | Update the metadata associated with the specified document chunk |
| DEL [Delete document](/api-reference/kbpublicapidocument/delete-document) | Permanently remove a document from the knowledge base by ID. |
## Documents
Documents are the content sources your agent draws from when answering questions. Each document has a type - URL, PDF, DOCX, plain text, CSV, XLSX, or table - and is processed into chunks that get indexed for retrieval. You can [create documents](/api-reference/kbpublicapidocument/create-document) from a URL or external integration, [upload structured table data](/api-reference/kbpublicapidocument/upload-table-document) directly, or [replace](/api-reference/kbpublicapidocument/replace-document) an existing document entirely when its source changes. URL documents support a `refreshRate` setting (`daily`, `weekly`, `monthly`, or `never`) that controls how often Voiceflow re-fetches and re-indexes the content.
## Chunks and metadata
When a document is processed, it's split into chunks, smaller segments of content that are individually indexed and retrieved during conversations. You can [update the metadata on a specific chunk](/api-reference/kbpublicapidocument/update-chunks-metadata) to add context that improves retrieval accuracy without modifying the document itself.
## Knowledge base and environments
The knowledge base is project-wide: every [environment](/documentation/deploy/environments) in the project points at the same set of documents, and editing a document's content affects all of them. Individual environments hold their own pointers into that shared set, so you can add a document from a non-Main environment and only that environment will see it until the environment is merged into Main.
Knowledge base API endpoints accept an optional environment alias parameter. When provided, the request targets the document pointers for that environment.
# Query
Source: https://docs.voiceflow.com/api-reference/knowledgebase/query
/specs/general-runtime/openapi.public.json post /knowledge-base/query
Query the knowledge base and retrieve answers to user questions. Send a question and receive a synthesized answer or relevant document chunks from the knowledge base.
# Project API
Source: https://docs.voiceflow.com/api-reference/project-api/overview
Retrieve project files, manage assistant environments, and update secrets.
The Project API lets you export your Voiceflow project as a file you can use for programmatic analysis or integration with third-party tooling. It also includes endpoints for listing, creating, publishing, and routing traffic across assistant environments, as well as managing environment-specific secret values.
## Available endpoints
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Environment** | |
| GET [List environments](/api-reference/environmentpublicapi/list-environments) | List all environments for the target assistant. |
| GET [Get traffic split](/api-reference/environmentpublicapi/get-traffic-split) | Get the current traffic split configuration for all environments. |
| GET [Get environment](/api-reference/environmentpublicapi/get-environment) | Get a specific environment by ID or alias. |
| GET [Export environment JSON](/api-reference/environmentpublicapi/export-environment-json) | Export a specific environment by ID or alias as a JSON file. |
| POST [Create environment](/api-reference/environmentpublicapi/create-environment) | Create a new environment by cloning another environment. |
| POST [Publish environment](/api-reference/environmentpublicapi/publish-environment) | Publish an environment's draft as its new published version. |
| PATCH [Update traffic split](/api-reference/environmentpublicapi/update-traffic-split) | Update the traffic split configuration. Percentages must sum to 100. |
| DELETE [Delete environment](/api-reference/environmentpublicapi/delete-a-project-environment) | Delete a specific environment by ID or alias. |
| **Secret** | |
| PATCH [Update secret default value](/api-reference/secretsmanagementpublicapi/update-secret-default-value) | Update the default value of a secret across all environments. |
| PATCH [Update secret environment override value](/api-reference/secretsmanagementpublicapi/update-secret-environment-override-value) | Set or remove an environment-specific override for a secret. |
# Update secret default value
Source: https://docs.voiceflow.com/api-reference/secretsmanagementpublicapi/update-secret-default-value
/specs/realtime/openapi.public.json patch /v1/secrets-management/projects/{projectID}/secrets/{secretName}
Updates the default (project-level) value and/or visibility of a secret by name.
# Update secret environment override value
Source: https://docs.voiceflow.com/api-reference/secretsmanagementpublicapi/update-secret-environment-override-value
/specs/realtime/openapi.public.json patch /v1/secrets-management/projects/{projectID}/environments/{projectEnvironmentIDOrAlias}/secrets/{secretName}
Sets or removes an environment-specific override for a secret. Pass `null` as the value to delete the override. Use `versionVariant` to target the draft or published version of the environment.
# Emit session event
Source: https://docs.voiceflow.com/api-reference/session/emit-session-event
/specs/general-runtime/openapi.public.json post /v2/project/{projectID}/session/{sessionKey}/event
Emits an event to an ongoing conversation session.
This endpoint only works when the target session has an open websocket connection, such as through the [web chat widget](/documentation/deploy/widget/embedding-the-chat-widget) or a custom websocket integration. If no active connection exists, the event will have no effect.
Send an action to an active websocket session. This is useful for injecting events mid-conversation, such as signaling a user disconnection or pushing an external trigger while the agent is waiting for input.
You need the 'projectID' and 'sessionKey' to target the correct session. The sessionKey is returned when the websocket connection is established.
# Delete conversation state
Source: https://docs.voiceflow.com/api-reference/state/delete-conversation-state
/specs/general-runtime/openapi.public.json delete /state/user/{userID}
Deletes all state and session data from user's conversation.
# Get conversation state
Source: https://docs.voiceflow.com/api-reference/state/get-conversation-state
/specs/general-runtime/openapi.public.json get /state/user/{userID}
Fetch the current state of the user's conversation.
# Interact - legacy (non-stream)
Source: https://docs.voiceflow.com/api-reference/state/interact--legacy-non-stream
/specs/general-runtime/openapi.public.json post /state/user/{userID}/interact
This endpoint is deprecated. Use the [Interact (non-stream)](/api-reference/conversation/interact-non-stream) endpoint instead. This legacy endpoint will continue to work for now, and we'll communicate a timeline for removal when one is available. We recommend migrating as soon as possible.
Returns an array of traces in response to a user interaction.
# Update conversation state
Source: https://docs.voiceflow.com/api-reference/state/update-conversation-state
/specs/general-runtime/openapi.public.json put /state/user/{userID}
Replace the current state of the user's conversation.
# Update conversation variables
Source: https://docs.voiceflow.com/api-reference/state/update-conversation-variables
/specs/general-runtime/openapi.public.json patch /state/user/{userID}/variables
Updates variables in the user's state by merging with the properties in the request body.
# Traces
Source: https://docs.voiceflow.com/api-reference/trace-types
Reference for every trace type returned by the Conversations API.
Traces are the output of a Voiceflow agent. Each time your application sends an action to the [Conversations API](/api-reference/conversations-api/overview), the runtime returns an array of trace objects describing how the agent responded. A single turn often produces multiple traces in sequence - for example, a message followed by a set of buttons.
Every trace has a `type` field that identifies what it contains, a `payload` with the relevant data, and a `time` value recording when that trace was generated as a Unix timestamp. The `time` field can be useful for debugging: steps like message generation may take noticeably longer than simple text steps, and the timestamps make that visible.
## Trace types
### text
Returned by the [Message step](/documentation/build/steps/message), [Playbooks](/documentation/build/steps/playbook), and no-match and no-reply reprompts.
```json theme={null}
{
"type": "text",
"time": 1720552033,
"payload": {
"slate": {
"id": "unique-id",
"content": [
{
"children": [{ "text": "Hello there!" }]
},
{
"children": [{ "text": "Select an option or ask me a question" }]
}
],
"messageDelayMilliseconds": 1000
},
"message": "Hello there!\n\nSelect an option or ask me a question",
"delay": 1000
}
}
```
The `message` field contains the plain text content. The `slate` field contains the same content in a structured rich-text format. `delay` controls the pause in milliseconds before the next trace is rendered, defaulting to 1000ms.
### cardV2
Returned by the [Card step](/documentation/build/steps/card). When a card contains buttons, each button's `request.type` is a Voiceflow-generated path ID. Pass that value as the `action.type` in your next request to advance the conversation along the corresponding path.
```json theme={null}
{
"type": "cardV2",
"time": 1720552033,
"payload": {
"title": "This is a Card title",
"description": {
"text": "This is a Card description",
"slate": [
{
"children": [{ "text": "This is a Card description" }]
}
]
},
"imageUrl": "https://assets-global.website-files.com/example-file.png",
"buttons": [
{
"name": "Click for next step",
"request": {
"type": "path-generated-by-voiceflow",
"payload": {
"actions": [],
"label": "Click for next step"
}
}
}
]
}
}
```
### carousel
Returned by the [Carousel step](/documentation/build/steps/card). The same button handling applies as with `cardV2` - pass the button's `request.type` as the `action.type` in your next request.
```json theme={null}
{
"type": "carousel",
"time": 1720552033,
"payload": {
"layout": "Carousel",
"cards": [
{
"id": "unique-id",
"title": "This is a Carousel card title",
"description": {
"text": "This is a Carousel card description",
"slate": [
{
"children": [{ "text": "This is a Carousel card description" }]
}
]
},
"imageUrl": "https://assets-global.website-files.com/example-file.png",
"buttons": [
{
"name": "Click for next step",
"request": {
"type": "path-generated-by-voiceflow",
"payload": {
"label": "Click for next step",
"actions": []
}
}
}
]
}
]
}
}
```
### choice
Returned by the [Condition step](/documentation/build/steps/condition) and [Playbooks](/documentation/build/playbooks) or the Agent when the [buttons system tool](/documentation/build/tools/system-tools) is enabled. How you handle a choice trace depends on what's in each button's `request.type`.
#### Path buttons
When buttons are connected to specific paths in your workflow, `request.type` is a Voiceflow-generated path ID. Pass it directly as `action.type` in your next request. The `label` field is optional - if included, its value is set as the `last_utterance` variable.
```json theme={null}
{
"type": "choice",
"time": 1753108390491,
"payload": {
"buttons": [
{
"name": "Order coffee",
"request": {
"type": "path-cmd906pp400433b7ujbsbiotm",
"payload": {
"label": "Order coffee"
}
}
}
]
}
}
```
To handle this button click, send:
```json theme={null}
{
"action": {
"type": "path-cmd906pp400433b7ujbsbiotm",
"payload": {
"label": "Order coffee"
}
}
}
```
#### Agent-generated buttons
When the [buttons system tool](/documentation/build/tools/system-tools) is enabled on Playbook or on the Agent, the agent may dynamically generate buttons. These use `request.type: "text"` and simulate raw user input rather than triggering a specific path:
```json theme={null}
{
"type": "choice",
"time": 1753110520157,
"payload": {
"buttons": [
{
"name": "Check account balance",
"request": {
"type": "text",
"payload": "Check account balance"
}
}
]
}
}
```
### no-reply
Returned when a No Reply timeout is active. The `timeout` value is in seconds.
```json theme={null}
{
"type": "no-reply",
"time": 1720552033,
"payload": {
"timeout": 10
}
}
```
If the user doesn't respond within the timeout window, send a `no-reply` action to retrieve the configured reprompt:
```json theme={null}
{
"action": {
"type": "no-reply"
}
}
```
### Custom actions
Custom action traces can be returned by functions and use the string you defined in Voiceflow as the `type` value. The `defaultPath` field indicates which path is set as the default: `0` for the first path, `1` for the second, and so on. Their payload is provided as JSON, as shown:
```json theme={null}
{
"type": "calendar",
"time": 1720552033,
"payload": {
"today": 1700096585398
},
"defaultPath": 0,
"paths": [
{ "event": { "type": "done" } },
{ "event": { "type": "cancel" } }
]
}
```
### end
Returned when the conversation reaches an End step. On receiving this trace, your application should treat the session as closed.
```json theme={null}
{
"type": "end",
"time": 1720552033,
"payload": null
}
```
## Completion event traces
When using the streaming endpoint, you may also encounter `completion-start`, `completion-continue`, and `completion-end` traces. These mark the lifecycle of an AI generation event within a stream.
# Batch run transcript evaluations
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/batch-run-transcript-evaluations
/specs/analytics/openapi.public.json post /v1/transcript-evaluation/queue
Queue a batch of evaluations to run for the specified transcripts.
# Create transcript evaluation
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/create-transcript-evaluation
/specs/analytics/openapi.public.json post /v1/transcript-evaluation
Create a new transcript evaluation definition.
# Delete transcript evaluation
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/delete-transcript-evaluation
/specs/analytics/openapi.public.json delete /v1/transcript-evaluation/{evaluationID}
Remove the specified evaluation along with results for all transcripts.
# Estimate transcript evaluation
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/estimate-transcript-evaluation
/specs/analytics/openapi.public.json post /v1/transcript-evaluation/estimate
Estimate the cost of running the specified evaluation for transcript matching the provided filters.
# Get all evaluations
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/get-all-evaluations
/specs/analytics/openapi.public.json get /v1/transcript-evaluation/project/{projectID}
Get all project evaluations including the number of results per evaluation
# Get transcript evaluation
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/get-transcript-evaluation
/specs/analytics/openapi.public.json get /v1/transcript-evaluation/{evaluationID}
Get the definition of the specified transcript evaluation.
# Run transcript evaluation
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/run-transcript-evaluation
/specs/analytics/openapi.public.json post /v1/transcript-evaluation/{evaluationID}/transcript/{transcriptID}
Run a single evaluation for the specified transcript.
# Update transcript evaluation
Source: https://docs.voiceflow.com/api-reference/transcript-evaluation/update-transcript-evaluation
/specs/analytics/openapi.public.json patch /v1/transcript-evaluation/{evaluationID}
Update the definition of the specified transcript evaluation.
# Delete transcript property value
Source: https://docs.voiceflow.com/api-reference/transcript-property-value/delete-transcript-property-value
/specs/analytics/openapi.public.json delete /v1/transcript-property-value/transcript/{transcriptID}/property/{propertyID}
Remove the value of a property from the specified transcript.
# Get all transcript property values
Source: https://docs.voiceflow.com/api-reference/transcript-property-value/get-all-transcript-property-values
/specs/analytics/openapi.public.json get /v1/transcript-property-value/transcript/{transcriptID}
Get all property values associated with the specified transcript.
# Set transcript property value
Source: https://docs.voiceflow.com/api-reference/transcript-property-value/set-transcript-property-value
/specs/analytics/openapi.public.json post /v1/transcript-property-value
Associate a value with the specified property and transcript.
# Create transcript property
Source: https://docs.voiceflow.com/api-reference/transcript-property/create-transcript-property
/specs/analytics/openapi.public.json post /v1/transcript-property
Create a new transcript property definition.
# Delete transcript property
Source: https://docs.voiceflow.com/api-reference/transcript-property/delete-transcript-property
/specs/analytics/openapi.public.json delete /v1/transcript-property/{propertyID}
Remove the specified property from all transcripts along with their values.
# Get all transcript properties
Source: https://docs.voiceflow.com/api-reference/transcript-property/get-all-transcript-properties
/specs/analytics/openapi.public.json get /v1/transcript-property/project/{projectID}
Get all transcript properties for the specified project.
# Get transcript property
Source: https://docs.voiceflow.com/api-reference/transcript-property/get-transcript-property
/specs/analytics/openapi.public.json get /v1/transcript-property/{propertyID}
Get the definition of the specified transcript property.
# Update transcript property
Source: https://docs.voiceflow.com/api-reference/transcript-property/update-transcript-property
/specs/analytics/openapi.public.json patch /v1/transcript-property/{propertyID}
Update the definition of the specified transcript property.
# Delete transcript
Source: https://docs.voiceflow.com/api-reference/transcript/delete-transcript
/specs/analytics/openapi.public.json delete /v1/transcript/{transcriptID}
Remove this transcript, its logs and all evaluation results.
# End transcript
Source: https://docs.voiceflow.com/api-reference/transcript/end-transcript
/specs/analytics/openapi.public.json post /v1/transcript/{transcriptID}/project/{projectID}/end
Mark a transcript as complete. Once ended, enabled evaluations will be triggered.
# Get transcript
Source: https://docs.voiceflow.com/api-reference/transcript/get-transcript
/specs/analytics/openapi.public.json get /v1/transcript/{transcriptID}
Fetch a transcript with its logs, properties and evaluation results.
# Search transcripts
Source: https://docs.voiceflow.com/api-reference/transcript/search-transcripts
/specs/analytics/openapi.public.json post /v1/transcript/project/{projectID}
Search for transcripts matching the specified criteria with pagination.
# Query usage
Source: https://docs.voiceflow.com/api-reference/usage/query-usage
/specs/analytics/openapi.public.json post /v2/query/usage
Query usage for a project
# Interact (non-stream)
Source: https://docs.voiceflow.com/api-reference/v4interact/interact-non-stream
/specs/general-runtime/openapi.public.json post /v4/interact
Send an action and receive an array of traces in response.
Call [Start session](/api-reference/session/start-session) to begin a new conversation and receive a `sessionKey`. Then, pass the session key as the `authorization` header on this endpoint to send actions and receive [traces](/trace-types) from your agent.
Each request sends an action describing what happened on the user's side. Actions include sending a text message, selecting a button, signaling a no-reply, or continuing after a handoff. The most common are `launch` (to start a conversation) and `text` (to send a user message).
For streaming responses, use [Interact (stream)](/api-reference/conversation/interact-stream) instead.
# Interact (stream)
Source: https://docs.voiceflow.com/api-reference/v4interact/interact-stream
/specs/general-runtime/openapi.public.json post /v4/interact/stream
Returns a stream of trace events followed by an end event using [SSE](https://en.wikipedia.org/wiki/Server-sent_events).
Call [Start session](/api-reference/session/start-session) to begin a new conversation and receive a `sessionKey`. Then, pass the session key as the `authorization` header on this endpoint to send actions and receive [traces](/trace-types) from your agent.
Each request sends an action describing what happened on the user's side. Actions include sending a text message, selecting a button, signaling a no-reply, or continuing after a handoff. The most common are `launch` (to start a conversation) and `text` (to send a user message).
For streaming responses, use [Interact (non-stream)](/api-reference/conversation/interact-non-stream) instead.
# Start session (specific environment)
Source: https://docs.voiceflow.com/api-reference/v4interact/start-session-specific-environment
/specs/general-runtime/openapi.public.json post /v4/project/{projectID}/environment/{environmentID}/session
Start a new conversation and get a session key for interacting with an agent in a specified environment.
The start session endpoint creates a new conversation session and returns a `sessionKey`. Use this key as your authentication credential when calling the [Interact (stream)](/api-reference/conversation/interact-stream) and [Interact (non-stream)](/api-reference/conversation/interact-non-stream) endpoints. Unlike the legacy interact endpoints, the new interact endpoints use a session key instead of an API key for authentication.
# Start session (with traffic split)
Source: https://docs.voiceflow.com/api-reference/v4interact/start-session-with-traffic-split
/specs/general-runtime/openapi.public.json post /v4/project/{projectID}/session
Start a new conversation and get a session key for interacting with an agent, routing traffic based on its [traffic split](/documentation/deploy/environments/traffic-split).
The start session endpoint creates a new conversation session and returns a sessionKey. Use this key as your authentication credential when calling the [Interact](/api-reference/conversation/interact-stream) and [Interact (non-stream)](/api-reference/conversation/interact-non-stream) endpoints. This start session endpoint respects the [traffic split](/documentation/deploy/environments/traffic-split) setup in your project. If you'd like to send traffic to a specific environment, use [Start session (specific environment)](/api-reference/session/start-session-specific-environment) instead.
# Organization events webhooks
Source: https://docs.voiceflow.com/api-reference/webhooks/org-events
Receive organization level events to your webhooks.
If you're using Voiceflow within a larger organization, you might want to integrate with your existing observability or testing tools. Organization events webhooks let you automatically receive updates whenever something happens in your organization - for example, when a new project is created. Just provide a webhook URL, and Voiceflow will send event data there in real time.
## Configuring your webhook settings
If you're less technical, we recommend using a tool like Make to generate a webhook URL and run automations. If you're a developer, you can hook into your existing infrastructure using any tool that can receive and process JSON payloads.
To enable sending data to a webhook whenever key events happen within an organization, head to your [Voiceflow dashboard](https://creator.voiceflow.com), click the **Settings** button in the bottom left corner, then select **Organization**. You can then add the URL that you'd like to send events to in the box provided.
Once you've set a webhook URL, all future events will be automatically sent to it.
## Supported events
The following organization-level events will be sent to the provided URL:
| Human-readable name | Name |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| New project created | [`organization.project.created`](#organization-project-created) |
| Project deleted | [`organization.project.deleted`](#organization-project-deleted) |
| Project environment created | [`organization.project.environment.created`](#organization-project-environment-created) |
| Project environment published | [`organization.project.environment.published`](#organization-project-environment-published) |
| Project environment merged | [`organization.project.environment.merged`](#organization-project-environment-merged) |
| Project environment deleted | [`organization.project.environment.deleted`](#organization-project-environment-deleted) |
### `organization.project.created`
Sent when a new project is created in the organization.
```typescript theme={null}
{
"type": "organization.project.created",
"data": {
"createdBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json theme={null}
{
"data": {
"createdBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"organizationID": "LVkmPy8AE2",
"projectID": "6a16f4549e4196323d8a49b9",
"projectMetadata": {
"name": "My new project"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889237608,
"type": "organization.project.created"
}
```
### `organization.project.deleted`
Sent when a project is deleted from the organization.
```typescript theme={null}
{
"type": "organization.project.deleted",
"data": {
"deletedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json theme={null}
{
"data": {
"deletedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"organizationID": "LVkmPy8AE2",
"projectID": "6a16f4789e4196323d8a49c3",
"projectMetadata": {
"name": "Legacy support agent"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889287387,
"type": "organization.project.deleted"
}
```
### `organization.project.environment.created`
Sent when a new environment is created within a project. The `source` describes the environment the new one was branched from.
```typescript theme={null}
{
"type": "organization.project.environment.created",
"data": {
"createdBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"createdProjectEnvironmentID": string,
"createdProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"source": {
"environmentID": string,
"environmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"type": string // e.g. "environment"
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json theme={null}
{
"data": {
"createdBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"createdProjectEnvironmentID": "6a16f4dc9e4196323d8a49e5",
"createdProjectEnvironmentMetadata": {
"alias": "optimizeglobalprompt",
"isLive": false,
"name": "Optimize global prompt",
"trafficPercentage": 0
},
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"source": {
"environmentID": "69e8b60a99c9a35e1a5e8875",
"environmentMetadata": {
"alias": "main",
"isLive": true,
"name": "Main",
"trafficPercentage": 70
},
"type": "environment"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889372749,
"type": "organization.project.environment.created"
}
```
### `organization.project.environment.published`
Sent when an environment within a project is published. `publishedVersionIDBefore` and `publishedVersionIDAfter` let you track what changed.
```typescript theme={null}
{
"type": "organization.project.environment.published",
"data": {
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"publishedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"publishedProjectEnvironmentID": string,
"publishedProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"publishedVersionIDAfter": string,
"publishedVersionIDBefore": string,
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json theme={null}
{
"data": {
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"publishedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"publishedProjectEnvironmentID": "69e8b60a99c9a35e1a5e8875",
"publishedProjectEnvironmentMetadata": {
"alias": "main",
"isLive": true,
"name": "Main",
"trafficPercentage": 70
},
"publishedVersionIDAfter": "6a16f4b29e4196323d8a49db",
"publishedVersionIDBefore": "69e8e543ce546b913fc2c965",
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889330124,
"type": "organization.project.environment.published"
}
```
```json theme={null}
{
"data": {
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"publishedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"publishedProjectEnvironmentID": "6a16f4dc9e4196323d8a49e5",
"publishedProjectEnvironmentMetadata": {
"alias": "optimizeglobalprompt",
"isLive": false,
"name": "Optimize global prompt",
"trafficPercentage": 0
},
"publishedVersionIDAfter": "6a16f5129e4196323d8a49f1",
"publishedVersionIDBefore": "6a16f4dc9e4196323d8a49e3",
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889426435,
"type": "organization.project.environment.published"
}
```
### `organization.project.environment.merged`
Sent when one environment is merged into another. `sourceProjectEnvironmentRemoved` indicates whether the source environment was deleted as part of the merge.
```typescript theme={null}
{
"type": "organization.project.environment.merged",
"data": {
"mergedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"sourceProjectEnvironmentID": string,
"sourceProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"sourceProjectEnvironmentRemoved": boolean,
"targetProjectEnvironmentID": string,
"targetProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json theme={null}
{
"data": {
"mergedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"sourceProjectEnvironmentID": "6a16f4dc9e4196323d8a49e5",
"sourceProjectEnvironmentMetadata": {
"alias": "optimizeglobalprompt",
"isLive": false,
"name": "Optimize global prompt",
"trafficPercentage": 0
},
"sourceProjectEnvironmentRemoved": true,
"targetProjectEnvironmentID": "69e8b60a99c9a35e1a5e8875",
"targetProjectEnvironmentMetadata": {
"alias": "main",
"isLive": true,
"name": "Main",
"trafficPercentage": 70
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889488361,
"type": "organization.project.environment.merged"
}
```
### `organization.project.environment.deleted`
Sent when an environment is deleted from a project.
```typescript theme={null}
{
"type": "organization.project.environment.deleted",
"data": {
"deletedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"deletedProjectEnvironmentID": string,
"deletedProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json theme={null}
{
"data": {
"deletedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"deletedProjectEnvironmentID": "69e8b64d99c9a35e1a5e888b",
"deletedProjectEnvironmentMetadata": {
"alias": "feature-upselling",
"isLive": false,
"name": "Old unused environment",
"trafficPercentage": 0
},
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889527687,
"type": "organization.project.environment.deleted"
}
```
## Verifying requests come from Voiceflow
Once you enter a webhook URL into the settings page, you'll automatically be provided with a webhook secret. This can be used to verify that events received by the webhook were really sent by Voiceflow. [Follow these instructions to learn how to verify events using the webhook secret](https://docs.svix.com/receiving/verifying-payloads/how-manual).
If you accidentally leak your webhook secret, you can regenerate it using the 🔄 button on the settings page. Note that your previous webhook secret will remain valid for 24 hours after you regenerate it.
If you're receiving data from behind a restrictive firewall, you should know that events will come from one of [Svix's IP addresses](https://docs.svix.com/receiving/source-ips), rather than Voiceflow's.
# Session lifecycle webhook
Source: https://docs.voiceflow.com/api-reference/webhooks/session-lifecycle
Subscribe to session and call lifecycle webhook events so external systems get notified when Voiceflow conversations start and end.
The session lifecycle webhook notifies your systems in real time whenever a conversation starts or ends, letting you run automations around each conversation without polling for changes.
A common use is running automations once a conversation ends, without adding latency to the conversation itself. For example, you can sync conversation data to your CRM, kick off a downstream workflow in your own systems, or notify another service that a conversation has wrapped up. Because this work runs on your side in response to the webhook, none of it slows down the live conversation.
Add your webhook URL to your project under **Settings → Webhooks**.
![Clean Shot 2026 07 13 At 10 50 29@2x]()
## Events
Voiceflow will send POST requests to your webhook URL on the following events.
| Human-readable name | Name | Category |
| ------------------- | ------------------------------------------------- | --------------------------------- |
| Session started | [`runtime.session.start`](#runtime-session-start) | [Session events](#session-events) |
| Session ended | [`runtime.session.end`](#runtime-session-end) | [Session events](#session-events) |
| Call started | [`runtime.call.start`](#runtime-call-start) | [Call events](#call-events) |
| Call ended | [`runtime.call.end`](#runtime-call-end) | [Call events](#call-events) |
## Session events
Session events fire whenever a conversation starts or ends, across all projects and channels. These are the events most integrations listen for.
### `runtime.session.start`
This event is sent when a new session is started for a user.
```typescript theme={null}
{
"type": "runtime.session.start",
"data": {
"userID": string,
"projectID": string,
"environmentID": string,
"sessionID": string,
"startTime": number // unix timestamp MS
}
"time": number // unix timestamp MS, event time
"resource": string // project-{projectID}
}
```
```json theme={null}
{
"type": "runtime.session.start",
"data": {
"environmentID": "6a15b5f6a85b1b570a8773cf",
"projectID": "69f9fa36eeb8f50e7cfd2d5f",
"sessionID": "6a15b6093f95e60007ec4e04",
"startTime": 1779807753396,
"userID": "g4dq75wr6asov6z571860xg0"
},
"resource": "project-69f9fa36eeb8f50e7cfd2d5f",
"time": 1779807753433
}
```
### `runtime.session.end`
This event is sent when a session ends.
```typescript theme={null}
{
"type": "runtime.session.end",
"data": {
"userID": string,
"projectID": string,
"environmentID": string,
"sessionID": string,
"startTime": number, // unix timestamp MS
"endTime": number // unix timestamp MS
}
"time": number // unix timestamp MS, event time
"resource": string // project-{projectID}
}
```
```json theme={null}
{
"type": "runtime.session.end",
"data": {
"endTime": 1779807762998,
"environmentID": "6a15b5f6a85b1b570a8773cf",
"projectID": "69f9fa36eeb8f50e7cfd2d5f",
"sessionID": "6a15b6093f95e60007ec4e04",
"startTime": 1779807753396,
"userID": "g4dq75wr6asov6z571860xg0"
},
"resource": "project-69f9fa36eeb8f50e7cfd2d5f",
"time": 1779807763081
}
```
## Call events
Call events are specific to voice channels (phone and web voice), and carry call-level details such as the phone numbers involved and why a call ended.
Phone calls will receive **both** the `runtime.call.*` events and the corresponding `runtime.session.*` events. Use `type` to differentiate which event you're handling.
### `runtime.call.start`
This event is sent when the following call types are made:
* Twilio inbound / outbound / prototype-outbound call
* web widget voice call is made (including during testing on `creator.voiceflow.com`)
```typescript theme={null}
{
"type": "runtime.call.start",
"data": {
"userID": string,
"projectID": string,
"environmentID": string, // alias of the environment the call ran against
"startTime": number, // unix timestamp MS
"platform": "twilio" | "web-voice",
"metadata": object // depends on "platform"
}
"time": number // unix timestamp MS, event time
"resource": string // project-{projectID}
}
```
```json theme={null}
{
"type": "runtime.call.start",
"data": {
"userID": "+19876543210",
"environmentID": "69f3df348d8088f34a622739",
"projectID": "6772da2e485189279fa5b9da",
"startTime": 1743563467788,
"platform": "twilio",
"metadata": {
"callSid": "CA01ed76f14fee29c50f5de59400474006",
"callType": "inbound",
"userNumber": "+19876543210",
"agentNumber": "+17782006110"
}
},
"time": 1743563467874,
"resource": "project-6772da2e485189279fa5b9da",
}
```
### `runtime.call.end`
This event is sent when a call is completed.
```typescript theme={null}
{
"type": "runtime.call.end",
"data": {
"userID": string,
"projectID": string,
"environmentID": string, // alias of the environment the call ran against
"startTime": number, // unix timestamp MS
"endTime": number, // unix timestamp MS
"endReason"?: string | undefined, // why the call ended, arbitrary string, common reasons include "hangup" "end trace" "twiml" "answering machine"
"platform": "twilio" | "web-voice",
"metadata": object // depends on "platform"
}
"time": number // unix timestamp MS
"resource": string // project-{projectID}
}
```
```json theme={null}
{
"type": "runtime.call.end",
"data": {
"userID": "+19876543210",
"environmentID": "69f3df348d8088f34a622739",
"projectID": "6772da2e485189279fa5b9da",
"startTime": 1743563467788,
"endTime": 1743563467834,
"endReason": "hangup",
"platform": "twilio",
"metadata": {
"callSid": "CA01ed76f14fee29c50f5de59400474006",
"callType": "inbound",
"userNumber": "+19876543210",
"agentNumber": "+17782006110"
},
},
"time": 1743563467874,
"resource": "project-6772da2e485189279fa5b9da",
}
```
## Best practices
* Check `type` when evaluating a response. There may be additional types of events in the future with a different shaped request body, as well as new properties and metadata.
* `data.metadata` is only included on call events. Check `data.platform` before reading it, as the available fields vary by platform (eg: `data.metadata.callSid` isn't present on a `"web-voice"` call).
* If you're using the same webhook URL across multiple projects, check `data.projectID` to tell them apart.
# Changelog
Source: https://docs.voiceflow.com/changelog/changelog
Stay up to date with Voiceflow product updates, new features, bug fixes, and platform improvements shipped across the agent builder and APIs.
## Environment Protection
You can now lock down individual environments so only admins or owners can publish or merge into them. Turn on **Environment protection** from the environment's ••• menu in **Settings → Environments**. Everyone else keeps their normal access to build and test - they just can't merge changes into that environment.
This is most useful on Main and on any environment carrying live traffic. Anyone can still create a new environment, this protects production environments from accidental or unauthorized changes.
![Clean Shot 2026 07 31 At 10 04 09@2x]()
## Cost limit
You can now set a maximum spend per conversation. Define a dollar amount, and once a session's cost exceeds it, Voiceflow ends the session automatically - a hard ceiling on any single conversation, no matter how long it runs or how many tools it calls.
For voice calls, this pairs with Max conversation duration: duration caps how long a conversation lasts, while cost limit caps what it spends. A short conversation that hammers an expensive model can cost more than a long, quiet one, so the two guardrails catch different failure modes.
As with duration, you can set an optional **End message** that's sent before the session closes.
This setting is off by default. Find it in **Settings → Behaviour.**
![Clean Shot 2026 07 31 At 10 02 39@2x]()
## Max conversation duration for phone calls
You can now cap how long a single conversation is allowed to run. Set a limit in seconds, and once a conversation hits it, Voiceflow ends it automatically - so a caller who stays on the line indefinitely, or an agent stuck in a loop, can't quietly burn through credits.
You can also define an optional **End message** that plays before the conversation closes, so the user gets a graceful sign-off instead of a dropped call.
This setting is off by default. Find it in **Settings → Behaviour**.
![Clean Shot 2026 07 31 At 10 03 07@2x]()
## File upload in chat widget
The chat widget now natively supports file and image uploads for both AI agent and human handoff conversations. To turn file uploads on, open **Widget → Modality & Interface** and enable **Allow file attachments**.
Users can upload up to 10 files during a conversation. Supported file types include PDF, JPEG, JPG, PNG and WEBP.
Files are stored in a secure Voiceflow storage repository and are never publicly accessible. [Learn more](https://docs.voiceflow.com/documentation/deploy/widget/custom-web-chat-styling#enabling-file-uploads)
![Clean Shot 2026 07 31 At 10 09 37@2x]()
## Improvements to tool call sounds
Tool call sounds now:
1. Have manual volume control
2. Include more sound options
3. Automatically decrease volume when agent it talking over it
4. Fade in and out to create a more natural dialog
![Clean Shot 2026 07 15 At 12 27 34@2x]()
## Background audio for all telephony providers
All Telephony providers (Voiceflow, Twilio, Vonage, Telnyx) now support background audio. Background audio configuration can be found in the behaviour tab of your project.
![Clean Shot 2026 07 15 At 12 18 46@2x]()
## Secrets conflict resolution
When merging an environment into Main, Voiceflow detects secrets whose values differ between the two environments. Before the merge completes, you choose how to resolve them: keep Main's existing values (default), or enable **Override Main secrets** to replace them with the incoming environment's values. This prevents merges from silently overwriting production credentials - like API keys pointed at staging systems - without an explicit decision.
![Clean Shot 2026 07 09 At 09 49 15@2x]()
## Evaluations with log visibility
Evaluations just got a lot more observant. With the new **Log visibility** setting, you control exactly what your evaluating model can see when it scores a transcript - going beyond the conversation itself and into what your agent actually *did* behind the scenes.
Choose which logs to include in each evaluation:
* **Playbook logs** - see which playbooks fired and how they reasoned toward their goal
* **Workflow logs** - trace the deterministic steps a conversation passed through
* **Tool logs** - inspect every tool call, input, and response
Each log type is opt-in, so you stay in control of the trade-off: more logs give the evaluating model richer context, while fewer logs keep credit usage lean. Enable all three, mix and match, or include none - whatever fits the question you're trying to answer.
![Clean Shot 2026 07 03 At 17 09 43@2x]()
## Variable persistence control
You can now control whether individual variables persists across user sessions. Define what should carry across sessions (name, preferences, tier) for returning users, and ignore what shouldn't. [Learn more](https://docs.voiceflow.com/documentation/build/data/variables#persisting-variables-across-sessions)
![Clean Shot 2026 07 03 At 12 10 12@2x]()
## Required variables for workflows & playbooks
Specify variables that must be filled before a playbook or workflow can be routed to. Until every required variable has a value, the agent won't hand off to it.
![Clean Shot 2026 06 24 At 09 10 52@2x]()
## Entry conditions
You can now gate playbooks and workflows behind entry conditions - deterministic checks that must evaluate to true before the agent can access that playbook or workflow. If the conditions aren't met, the playbook/workflow stays unavailable for routing, giving you precise, rule-based control over when each one becomes reachable.
![Clean Shot 2026 06 24 At 08 58 30@2x]()
## Organization level usage breakdown
You can now see exactly where your spend is going from a birds eye view. Usage breakdowns now include spend across workspaces and projects, broken down by Runtime, Measure, Development, and Generation features. Drill into a specific workspace, project, or date range to track costs over time and understand what's driving them.
![Clean Shot 2026 06 17 At 18 12 18@2x]()
## Transcript filtering by workflow, playbook and tool usage
You can now filter transcripts by a specific workflow, playbook, or tool and see only the conversations where it was used.
![Clean Shot 2026 06 17 At 18 32 22@2x]()
## Caller ID passthrough
When using the Call forward system tool, the forwarded destination can now see the original caller's number. This can be helpful to ensure your contact center platform receives accurate caller information for routing, logging, and CRM matching.
![Clean Shot 2026 06 17 At 17 24 40@2x]()
## Save tool responses to properties
Tool outputs can now be saved to [properties](https://docs.voiceflow.com/documentation/measure/transcripts#attaching-custom-properties), not just variables. Previously, when an agent called a tool, you could capture the response to a Voiceflow variable - now you can map it to a property as well, which is useful for tracking and transcript tagging.
![Clean Shot 2026 06 17 At 18 33 06@2x]()
## Merge conflict awareness
When merging an environment back into main, you can now see whether main has changed since you branched off it. This makes it clear when your branch is working from an outdated version of main, so you can review and reconcile those changes before merging.
![Clean Shot 2026 06 15 At 17 39 57@2x]()
## Personas
Personas let you test conversations with specific variable values already in place. They’re useful for testing how your agent handles different customer types or account states without setting things up by hand each time. [Learn more](/documentation/build/data/personas)
## Tests
Tests let you verify your agent’s behaviour before real users see it. Each test simulates a conversation between a user and your agent, then checks that things like the agent’s responses, where it routed, and which tools it called match what you expected. [Learn more](/documentation/measure/tests)
![Tests Cover]()
## Project converter
You can convert a chat project to voice (or voice to chat) right from your workspace dashboard. Select the project, click the ellipsis (•••) button, and choose **Convert to voice** or **Convert to chat**.
## Query re-writing
When enabled, the model rewrites the user’s last message before searching based on your instructions - improving retrieval for conversational or ambiguous inputs. Useful when users don’t phrase questions the way your content is written. [Learn more](https://docs.voiceflow.com/documentation/build/querying-the-knowledge-base#query-re-writing)
![Query Re Writing Docs 1]()
## New model: Voiceflow Core
Voiceflow Core is our first model, optimized for the kinds of tasks agents actually do - tool calling, multi-turn reasoning, instruction following inside playbooks. We benchmarked it on Voiceflow's agentic framework against the models we currently support (Anthropic, OpenAI, Gemini) and saw stronger quality, at a lower per-token cost. Core is rolling out as a selectable model across all plans.
![Voiceflow Core Docs]()
## Pronunciation dictionaries
The pronunciation dictionary rewrites words or phrases in your agent’s responses before they’re sent to text-to-speech. This ensures correct pronunciation of names, places, or technical terms. You can find this setting in Behaviour/Voice Output/Pronunciation dictionary. [Learn more](https://docs.voiceflow.com/documentation/build/behaviour#pronunciation-dictionary)
![Pronunciation Dic]()
## Environments
Work on multiple versions of your agent in parallel, conduct A/B tests with traffic splits, and roll changes back with confidence. [Learn more](/documentation/deploy/environments/overview)
![Traffic Splitting]()
## Tool call sounds
You can now play an audio snippets while a tool call is running, so users aren't sitting in dead air during longer-running tools. Pick from sounds like keyboard typing, elevator music, and others directly in the tool call configuration.
This is a voice specific feature, so it's only available on voice projects.
![Tool Call Sounds Docs]()
## Evaluation preview cards
Evaluation results now open with summary cards at the top of the page, so you can see the key numbers at a glance without digging into the details.
![Eval Preview Chips]()
## Flux multilingual
Flux Multilingual extends Flux to 10 languages. We highly recommend switching to Flux as it's the most performant STT model in market.
![Flux Multi]()
## Skip turn system tool
The skip turn tool lets the agent stay quiet and wait for the user instead of replying. Use it when the user asks for a moment - things like "hold on," "give me a sec," "let me think," or "one moment" - so the agent doesn't talk over them or fill the pause with something unnecessary.
![Skip Turn]()
## New default properties for chat transcripts
Chat transcripts now include OS, Device, Browser & Country properties by default. You can also filter your transcripts or evaluation results by any of these properties.
![Meta Data Filters]()
## Shopify tools
Connect your Shopify store to Voiceflow in a couple of clicks and give your agent instant access to real order and product data - no custom API wiring required.
What your agent can now do out of the box:
* **Answer product questions with live data** - stock levels, sizing, variants, and specs pulled straight from your catalog, so customers get accurate answers instead of hallucinated ones
* **Resolve "where's my order?" without a human** - customers self-serve status, tracking, and history just by asking
* **Turn support chats into revenue** - recommend the right next product based on what the customer is already looking at or buying
* **Handle cancellations end-to-end** - refund-ready cancellations happen inside the conversation instead of in a support queue
![Shopify Tool Docs]()
## Native fail path on Function and API steps
You can now enable a native failure path on Function and API tool steps. When a tool responds with an error code, or times out, the failure path triggers if enabled.
* If the Failure path is disabled and the tool errors or times out, the step exits through the first available port.
* This does not apply to API or Function tools used in the global agent or playbooks - the agent handles all cases.
* If the Failure path is disabled and the tool errors or times out, the step exits through the first available port.
* This does not apply to API or Function tools used in the global agent or playbooks - the agent handles all cases.
* If the Failure path is disabled and the tool errors or times out, the step exits through the first available port.
* This does not apply to API or Function tools used in the global agent or playbooks - the agent handles all cases.
## Workflow usage
You can now see workflow usage, alongside playbook usage in analytics. If you're not immediately seeing it in your analytics view, try adding it by editing the view from the page header.
![Workflow Usage Docs]()
## Global tools
You can now add [API](/documentation/build/tools/api-tool), [MCP](/documentation/build/tools/mcp-tool), [integration](/documentation/build/tools/overview) and [function](/documentation/build/tools/function-tool) tools directly at the agent level, making them available across your agent.
[Global tools are available](https://docs.voiceflow.com/documentation/build/tools/global-tools#when-are-global-tools-are-available-for-my-agent-to-use) any time the user is in an agentic context.
![Global Tools Docs 1]()
## Custom timeouts for API and function tools
You can now configure a custom timeout on [API](/documentation/build/tools/api-tool) and [function](/documentation/build/tools/function-tool) tools. If a tool doesn't respond within the set limit, it times out and triggers the fail path - so any fail tool messages or fallback paths you've configured will fire on timeout as well. The default timeout is 20 seconds.
Maximum timeout limits by plan:
| Plan | Maximum timeout |
| ---------- | --------------- |
| Enterprise | 600s (10 min) |
| Business | 150s (2.5 min) |
| Pro | 150s (2.5 min) |
| Trial | 60s (1 min) |
![Request Timeout Docs 1]()
## Live conversations indication in transcripts
Your Transcripts table just got a heartbeat. Active conversations now appear have an indicator, alongside current cost - giving you a live pulse on every session as it happens. Refresh the table to pull in the latest updates without leaving the page.
![Live Conversations Docs]()
## Interact with responses while they stream
Links are now clickable and text is copyable while the agent is still generating a response - so you can act on information the moment it appears, not after the last word lands.
## Resizable conversation editor in run mode
The conversation editor in run mode can now be resized, giving you more space when you need it.
![Ezgif 62f101d76f530fd5]()
## Run mode & transcript improvements
Run mode and historical transcripts now surface three new layers of detail to make testing and reviewing your AI agents more informative:
**Agent navigation** - When routing occurs, the transcript shows the path inline (eg: *Agent → Reservations specialist)*, giving you a clear trace of how conversations are routed throughout your AI agent.
**Latency indicators** - Each agent response shows its response time in milliseconds or seconds, making it easy to spot slow steps in your flow. Hover a latency chip to see more detail.
**Input types** - User turns are tagged with how the input was received (eg: *Voice input*, *Keypad input*, *Button input*, *Text input*), so you can better understand how your customers are interacting with your agent.
![Run Updates Docs]()
## Improved evaluation filters
You can now apply more granular filters to your evaluations - making it easier to track performance trends, compare results across specific time ranges, and pinpoint where your agent is improving or regressing.
![Eval Filters Docs]()
## Customize widget loader
You can now choose how your agent looks while it's thinking. Pick between a spinner with text or a minimal dots loader, and customize the loading message to match your brand. Find it under Interface → Widget. This is a chat only feature.
![Loader Type Docs]()
## Async tool response capture
API and Function tools running asynchronously can now save their response to a Voiceflow variable. Previously, async was fire-and-forget - useful for logging and side effects, but the response was lost. Now you can fire an async call, continue the conversation, and reference the result as soon as it arrives.
This unlocks predictive experiences. Fetch a customer's recent orders during authentication, pull account data while the agent greets the user, or query a slow third-party service while the conversation moves forward.
![Async Docs 1]()
## ElevenLabs Scribe v2 Realtime STT
We’ve added support for ElevenLabs' newest and most accurate speech-to-speech model, Scribe v2 Realtime. Supporting 90+ languages.
![Scribe Changelog]()
## Eleven v3 TTS
We’ve added support for ElevenLabs' newest and most expressive text-to-speech model, Eleven v3. Supporting 70+ languages.
![Eleven3 Changelog]()
## Show source URLs in responses
When enabled, the agent includes the source URL (If public URL) alongside its response so users can verify or learn more. Recommended for help centers and documentation.
This feature is available for both the knowledge base and web search system tools.
You can set the maximum number of sources you want to show per agent message (defaulted to 1).
![Show Source Url Kb Docs 1]()
## Async functions and API tools
You can now run Function and API tool steps asynchronously.
Async execution allows the conversation to continue immediately without waiting for the tools to complete. No outputs or variables from the step will be returned or updated.
This is ideal for non-blocking tasks such as logging, analytics, telemetry, or background reporting that don’t affect the conversation.
Note: This setting applies to the reference of the Function or API tool - either where the tool is attached to an agent or where it’s used as a step on the canvas. It is not part of the underlying API or function definition, which allows the same tool to be reused with different async behaviour throughout your project.
![Async functions and API tools]()
## Tool messages
Tool messages let you define static messages that are surfaced to the user as a tool progresses through its lifecycle:
1. Start - Message delivered when the tool is initiated
2. Complete - Message delivered when the tool finishes successfully
3. Failed - Message delivered if the tool encounters an error
4. Delayed - Message delivered if the tool takes longer than a specified duration (default: 3000ms, configurable)
This provides clear, predictable feedback during tool execution, improving transparency and user trust - especially for long-running or failure-prone tools.
![Tool messages]()
## GPT 5.2
Added global support for GPT 5.2
![GPT 5.2]()
## Voice mode in web widget
Your web widget now supports hands-free, real-time voice conversations. Enable it from the Widget tab for existing projects - it’s on by default for new ones.
Users can talk naturally, see transcripts stream in instantly, and get a frictionless voice-first experience. It also doubles as the perfect in-browser way to test your phone conversations - no dialing in, just open the widget and run the full voice flow instantly.
![Voice mode in web widget]()
![Voice mode in web widget]()
![Voice mode in web widget]()
## Native web search tool
We’ve shipped a native Web Search tool so your agents can look up real-time information on the web mid-conversation - no custom integrations required.
* Toggle on the web search tool in any agent to answer questions that need live data (news, prices, schedules, etc.).
* Configure search prompts and guardrails so the agent only pulls what you want it to.
* Results are summarized and grounded back into the conversation for more accurate, up-to-date answers.
* Toggle on the web search tool in any agent to answer questions that need live data (news, prices, schedules, etc.).
* Configure search prompts and guardrails so the agent only pulls what you want it to.
* Results are summarized and grounded back into the conversation for more accurate, up-to-date answers.
* Toggle on the web search tool in any agent to answer questions that need live data (news, prices, schedules, etc.).
* Configure search prompts and guardrails so the agent only pulls what you want it to.
* Results are summarized and grounded back into the conversation for more accurate, up-to-date answers.
![Native web search tool]()
## Telnyx telephony integration
You can now connect your Telnyx account to import and manage phone numbers directly in Voiceflow, enabling Telnyx as your telephony provider for both inbound and outbound calls..
![Telnyx telephony integration]()
## Native support for keypad input (DTMF)
Added native support for DTMF keypad input in phone conversations. Users can now enter digits via their phone keypad, sending a DTMF trace to the runtime. Configure timeout and delimiters (#, \*) to control when input is processed. See [documentation here](/docs/dtmf#/).
* Keypad input is off by default and can be turned on from Settings/Behaviour/Voice.
* When on in project settings, keypad input can be turned off at the step level via the "Listen for other triggers" toggle.
* [View full documentation here](/docs/dtmf#/)
* Keypad input is off by default and can be turned on from Settings/Behaviour/Voice.
* When on in project settings, keypad input can be turned off at the step level via the "Listen for other triggers" toggle.
* [View full documentation here](/docs/dtmf#/)
* Keypad input is off by default and can be turned on from Settings/Behaviour/Voice.
* When on in project settings, keypad input can be turned off at the step level via the "Listen for other triggers" toggle.
* [View full documentation here](/docs/dtmf#/)
![Native support for keypad input (DTMF)]()
## Knowledge base metadata
Add metadata to your Knowledge Base sources to deliver more relevant, localized, and precise answers, helping customers find what they need faster and improving overall resolution speed.
1. Adding metadata on knowledge import
When uploading files, URLs, or tabular data to the Knowledge Base, you can attach metadata at import time. This metadata is stored with each document or data chunk, enabling structured filtering and contextual retrieval later. For example, when importing car rental policies, you might tag each file with metadata like "locale": "US, CA, EU", or "serviceType": "car\_rental, equipment\_rental". This ensures that when the agent queries using metadata filters (static or dynamic), it only retrieves content relevant to the user’s local region or service context.
2. Dynamically, or statically apply metadata at runtime
From the Knowledge Base tool in your agent, define the metadata your agent should use when querying the tool. You can specify a static value (or variable) to consistently filter results, or let the agent dynamically assign metadata at runtime - allowing it to query the Knowledge Base contextually based on each unique conversation.
Example - Car Booking Service
If your Knowledge Base includes information for multiple locales (eg: US, CA, EU), you can set a metadata field like locale. Instead of hardcoding a single locale, the agent can dynamically apply the user’s locale at runtime - for example:
If a user says “I want to book a car in New York,” the agent automatically filters Knowledge Base results with locale: US, ensuring responses only reference policies, pricing, and availability relevant to that locale.
![Knowledge base metadata]()
![Knowledge base metadata]()
## Built-in time variables
We’ve added a set of built-in time variables that make it easier to access and use time within your agents - no external API calls or workarounds required. Perfect for agents that depend on current or relative time inputs.
Project timezone can be set in project/behaviour settings:
![Built-in time variables]()
## Deepgram Flux ASR model
We've added [Deepgram Flux](https://flux.deepgram.com/), their ASR newest model built specifically for Voice AI.
Flux is the first conversational speech recognition model built specifically for voice agents. Unlike traditional STT that just transcribes words, Flux understands conversational flow and automatically handles turn-taking.
Flux tackles the most critical challenges for voice agents today: knowing when to listen, when to think, and when to speak. The model features first-of-its-kind model-integrated end-of-turn detection, configurable turn-taking dynamics, and ultra-low latency optimized for voice agent pipelines, all with Nova-3 level accuracy.
Flux is Perfect for: turn-based voice agents, customer service bots, phone assistants, and real-time conversation tools.
Key Benefits:
* Smart turn detection - Knows when speakers finish talking
* Ultra-low latency - \~260ms end-of-turn detection
* Early LLM responses - EagerEndOfTurn events for faster replies
* Turn-based transcripts - Clean conversation structure
* Natural interruptions - Built-in barge-in handling
* Nova-3 accuracy - Best-in-class transcription quality
![Deepgram Flux ASR model]()
## Sync audio and text output
Converts text to speech in real time and keeps the spoken audio perfectly aligned with the displayed text. This ensures call transcripts are an accurate, word-for-word representation of what was actually said.
![Sync audio and text output]()
## Transcript inactivity timeout
This setting lets you define how long a conversation can stay inactive before the transcript automatically ends.
This is different from session timeout - the session stays open, but the transcript closes after the set inactivity period, enabling more accurate reporting and evaluations.
Important: ending the transcript does not end the user’s ability to re-engage. If the user responds again, a new transcript will begin within the same session.
![Transcript inactivity timeout]()
## Priority processing for Open AI models
We’ve added a new [Priority Processing](https://openai.com/api-priority-processing/) setting for OAI-supported models. When enabled, your requests will be given higher processing priority for faster response times and reduced latency. Note: this will consume more credits.
![Priority processing for Open AI models]()
## MCP tools
Supercharge your agents by connecting directly to MCP servers.
* 🔌 Connect to MCP servers in just a few clicks
* 📥 Add MCP server tools to your agents
* 🔄 Sync MCP servers to stay up-to-date
Bring in any tool, expand what your agents can do, and take your workflows to the next level.
[Documentation](/docs/mcp-tool#/)
![MCP tools]()
## Call forwarding tool in agents
You can now enable your agents to forward calls to a different number, SIP address, or extension.
* 📞 Seamlessly transfer callers to the right person or agent
* 🔀 Supports phone numbers, SIP addresses, and extensions
* 🛠️ Configure forwarding directly in your agent’s tools
This makes it easier to connect customers with the right destination without breaking the flow of the conversation.
![Call forwarding tool in agents]()
## Control reasoning effort for supporting GPT models
We've added a reasoning effort slider for all supporting GPT models (GPT-5, GPT-5 mini, GPT-5 nano, GPT-o3 and GPT-o4-mini).
![Control reasoning effort for supporting GPT models]()
## Shareable links now match your AI agent
Shareable links have been upgraded to better reflect the agent you’re building. Each link now points to a hosted version of your AI agent that mirrors your selected environment (dev, staging, production) and interface, so what you share is exactly what others will experience. Password protection is also available for secure access.
* 🔗 Sharable links now mirror your actual AI agent
* 🛠️ Environment-specific links (dev, staging, production)
* 🎨 Customize the look and feel via the Interfaces tab
* 🔒 Optional password protection for secure sharing
![Shareable links now match your AI agent]()
## Staging environment added
We’ve introduced a new staging environment to help you manage deployments more effectively. You can now publish between development, staging, and production to test changes before going live.
* New staging environment for pre-production testing
* Publish across dev → staging → production
* More control and confidence in deployment flows
* Override secrets per environment for greater flexibility
![Staging environment added]()
## Duplicating projects now clones knowledge base
You can now duplicate projects along with their entire knowledge base. When cloning a project, all connected documents and data sources are copied as well - so your new project starts with the same knowledge setup as the original.
This enhancement only applies to project duplication. Knowledge bases are not yet cloned when using project import.
## Control saving of empty transcripts
You can now choose whether to save transcripts where the bot spoke but the user never replied. Use this toggle to keep your transcript logs cleaner and focused on real interactions. By default, all new projects will save all conversations to transcripts.
![Control saving of empty transcripts]()
## Save input variables in tool calls
Previous to this release, you could only capture the output of a tool call (eg: the response from an API). Now, you can also persist the inputs (the parameters sent to the tool) as Voiceflow variables. This means both sides of the transaction - request and response - can be tracked, reused, or referenced later in the conversation.
![Save input variables in tool calls]()
## GPT-5 models
GPT-5 models are now available in Voiceflow.
![GPT-5 models]()
## Double-click to open agent step
You can now double-click an agent step to jump straight into its editor - saving yourself an extra click.
![Double-click to open agent step]()
## Tool step
You can now run tools outside of the agent step using the new Tool Step.
This lets you trigger any tool in your agent - like sending an email or making an API call - anywhere in your workflows.
🛠️ You’ll find the call forwarding Step in the ‘Dev’ section of the step menu for now.
Tools can also be used as actions:
![Tool step]()
![Tool step]()
## New analytics API
A few months ago, we released a new analytics view - giving you deeper insights into agent performance, tool usage, credit consumption, and more.
Today, we're releasing an updated [Analytics API](/reference/querypubliccontroller_queryusagev2#/) to match. This new version gives you programmatic access to the same powerful data, so you can:
Track agent performance over time
Monitor tool and credit usage
Build custom dashboards and reports
Use the new API to integrate analytics directly into your workflows and get the insights you need - where you need them.
## Custom query control & chunk limit for knowledge base tool
You now have more control over how your agents retrieve knowledge. Customize the query your agent uses to search the knowledge base, and fine-tune the chunk size limit to better match your content. This gives you more precision, better answers, and smarter agents.
![Custom query control & chunk limit for knowledge base tool]()
## Better transcripts. Custom evaluations. Better AI agents.
Your AI agents just got a massive upgrade:
[**🔥 What’s new**](#-whats-new)
* Transcripts, reimagined - Replay calls, debug step-by-step, filter with precision, and visualize user actions like button clicks - all in a faster, cleaner UI.
* Evaluations, your way - Define what “good” looks like with customizable evaluation templates, multiple scoring types (rating, binary, text), auto-run support, and performance tracking over time.
[**📝 Transcripts**](#-transcripts)
A full overhaul of the transcripts experience, built to help teams analyze, debug, and improve agents faster.
1. Call recordings - Replay conversations to hear how your agent performs in the real world
2. Robust debug logs - Trace agent decisions step-by-step
3. Granular filtering - Slice data by time, user ID, evaluation result, and more
4. Button click visualization - See exactly where users clicked in the conversation
5. Cleaner UI - Faster load times, more usable data
[**📊 Evaluations**](#-evaluations)
Define what “good” looks like - and measure it, your way. Build (or generate) your own evaluation criteria, tailor analysis to your business goals, and iterate with confidence.
Eval types - support for:
1. ⭐ Rating evals (eg: 1-5)
2. ✅ Binary evals (Pass/Fail)
3. 📝 Text evals (open-ended notes)
Also includes:
* Batch or auto-run - Evaluate hundreds of transcripts in a few clicks, or automatically as they come in
* Analytics & logs - See detailed results per message or overall trends over time
[**APIs**](#apis)
* We've release a brand new [Evaluations API](https://link.voiceflow.com/evals-api)
* We've release a new [Transcripts API](https://link.voiceflow.com/transcript-api) The legacy Transcripts API is still supported and currently has no deprecation timeline
🕓 Transition Period: Until September 28, 2025, all transcripts will be available in the legacy view, for existing projects. On September 28th, 2025 the old view will be hidden and the new transcripts view will be the default. Transcripts older than 60 days will still be accessible via API for the foreseeable future.
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
![Better transcripts. Custom evaluations. Better AI agents.]()
## Gmail tools: let your AI agents send emails
Agents can now send emails seamlessly as part of any conversation. Whether it’s a confirmation, follow-up, or lead nurture message - the new Send Email tool makes it easy to automate communication right from your agent. Just connect your Gmail account and you’re ready to go.
Make sure to instruct your agent on how to use this tool properly. Give it a try in the agent step!
![Gmail tools: let your AI agents send emails]()
![Gmail tools: let your AI agents send emails]()
## Call forwarding step
Seamlessly connect your voice AI agent to the real world with call forwarding.
The new call forwarding step lets your AI agent hand off calls to a real person (or another AI agent) - instantly and smoothly.
* ✅ Route to phone numbers
* ✅ Include optional extensions
* ✅ Support for SIP addresses
Build smarter, more human-ready voice agents - without sacrificing automation.
🛠️ You’ll find the call forwarding Step in the ‘Dev’ section of the step menu for now. We’re planning to introduce a dedicated voice section soon - stay tuned!
![Call forwarding step]()
## Hubspot tools
Connect your agents to Hubspot to create contacts, leads and tickets.
![Hubspot tools]()
![Hubspot tools]()
## SMS messaging with Twilio tools
Enable your agents to send SMS messages with an effortless connection to Twilio. Try it now in the agent step.
![SMS messaging with Twilio tools]()
## Create AI agents instantly - from just a prompt
We’ve made building AI agents dramatically faster.
You can now generate a fully-functional agent by simply describing what you want it to do. No setup. No manual flow-building. Just write a detailed prompt - and Voiceflow will generate everything for you:
✅ Agent instructions
✅ Tools and workflows
✅ Conversation logic and components
This means less time configuring, more time testing and refining your agent behavior.
Today, we’re launching:
1. Prompt-to-project generation - go from idea to working prototype in seconds
2. Prompt-to-workflow generation - describe a capability, get a complete workflow
3. Prompt-to-component generation - create specific tools and logic on the fly
This is a foundational leap in how AI agents get built on Voiceflow - we can’t wait to see what you create.
![Create AI agents instantly - from just a prompt]()
## Vonage integration for telephony
Voiceflow now supports importing phone numbers from Vonage as an alternative to Twilio. Vonage offers a minor latency improvement (\~200-400ms) over Twilio, for more responsive calls.
For more information: [https://dashboard.nexmo.com/](https://dashboard.nexmo.com/) [https://www.vonage.ca/en/communications-apis/voice/](https://www.vonage.ca/en/communications-apis/voice/)
![Vonage integration for telephony]()
## Smarter knowledge base building with LLM chunking strategies
Your Knowledge Base just got a major upgrade. With our new LLM chunking strategies, you can now prep your data for AI like a pro - no manual formatting needed.
We’ve introduced 5 powerful strategies to help structure and optimize your content for maximum retrieval performance:
🧠 Smart chunking Automatically breaks content into logical, topic-based sections. Ideal for complex documents with multiple subjects.
❓ FAQ optimization Generates sample questions per section, perfect for creating high-impact FAQs.
🧹HTML & noise removal Cleans up messy website markup and boilerplate. Best used on content pulled from the web or markdown.
📝Add topic headers Inserts short, helpful summaries above each section. Great for longform content that needs context.
🔍 Summarize Distills each section to its key points, removing fluff. Perfect for dense reports or research.
These chunking strategies help you get more accurate, more relevant answers from your AI - especially for data sources not originally built for Retrieval-Augmented Generation (RAG).
Ready to make your Knowledge Base smarter? Try out some LLM chunking strategies and watch the results speak for themselves.
Note - LLM chunking strategies use credits. Before processing, we’ll show you a clear estimate of how many credits will be used - so you’re always in control.
![Smarter knowledge base building with LLM chunking strategies]()
![Smarter knowledge base building with LLM chunking strategies]()
## Make.com tool
Connect your agents to Make.com with a couple clicks to run your automations from your Voiceflow AI agents.
![Make.com tool]()
![Make.com tool]()
## Airtable tools
Connect your agents to Airtable with a couple clicks. Supported tools include: Create records, Delete records, Get record, List records, Update records.
![Airtable tools]()
![Airtable tools]()
## Agents can now automatically use buttons, cards, and carousels to enrich conversations
By enabling these options and providing guidance on when to use (or avoid) each special tool, your agent will intelligently enhance interactions with visual tools like buttons, cards, and carousels.
Note: these configurations are ignored during phone-based conversations, meaning it will not prohibit your ability to create multi-modal AI agents with Voiceflow.
![Agents can now automatically use buttons, cards, and carousels to enrich conversations]()
## \[Deprecation] Dialog Manager API Logs
Legacy `log` traces are no longer supported, which are sent when with the query parameter `?log=true`. This system has not been updated for a significant period and is out of date, especially with new steps.
`log` traces will no longer be returned, after Friday, July 4th, 2025.
This affects a small subset of users and should not impact the output or performance of an agent.
Going forward, it will be unified with a more robust `debug` trace system, along with a new debugger UI.
## New Speech-to-Text Providers
* Added Cartesia's [Ink-Whisper](https://cartesia.ai/blog/introducing-ink-speech-to-text) STT model This leverages OpenAI's whisper model, upgraded for realtime call performance Expanded language support and selection
* Added AssemblyAI [Universal](https://www.assemblyai.com/products/speech-to-text) STT model Advanced tuning options
* Added specific model selection for Deepgram STT Nova-2, Nova-3, and Nova-3 Medical
![New Speech-to-Text Providers]()
## Google Sheets tools
Connect your agents to Google Sheets with a couple clicks. Supported tools include: Add to sheet, Create new sheet, Get rows, Get sheet, Update sheet.
![Google Sheets tools]()
## Cartesia voices
We've added Cartesia to Voiceflow. You can select from over 100 new voices across two Cartesia models (Sonic 2 & Sonic Turbo).
![Cartesia voices]()
## Added tool usage to project analytics
We've added all tool types to your projects analytics dashboard:
* Integration tools
* API tools
* Function tools
You can now see the number of times each tool has been used, along with the average latency and success/failure rate if you hover a specific tool.
![Added tool usage to project analytics]()
## New workspace dashboard
* We've made updates to the workspace dashboard to make it easier to organize your projects, and manage your workspace.
* We've added folders, to further organize your projects. Note, if you previously used the Kanban view (deprecated), we've automatically converted swim-lanes into folders.
* Home tab (coming soon)
* Community tab (coming soon)
* Tutorials tab (coming soon)
![New workspace dashboard]()
## New navigation
We've listened to your feedback and made Voiceflow easier to navigate. It's the same Voiceflow, just faster to get around!
![New navigation]()
## Claude Opus 4 & Sonnet 4
We've added Claude Opus 4 & Claude Sonnet 4 to Voiceflow.
![Claude Opus 4 & Sonnet 4]()
## Gemini 2.5 Pro & 2.5 Flash
We've added Gemini 2.5 Pro & 2.5 Flash to Voiceflow.
![Gemini 2.5 Pro & 2.5 Flash]()
## Security Settings for Widget
* Ability to whitelist domains
* Ability to have a custom privacy message before users engage with your AI agent
* Ability to not save transcripts
![Security Settings for Widget]()
## Generative No Reply
Use generative no-reply to dynamically re-engage users that haven't responded in a while. Responses will be contextual to the conversation.
![Generative No Reply]()
## API Raw Content-Type select
The API (agent) tool and step now have a content-type option on POST requests with a "Raw" body. This will automatically apply the `Content-Type` header, for a quality-of-life convenience.
![API Raw Content-Type select]()
## Rimelabs Arcana Voices
Rimelabs recently released a new set of [Arcana](https://www.rime.ai/blog/introducing-arcana/) voices, that sound far more natural with intonations and speech patterns such as breathing, pauses.
Arcana is still under development and we are working with the Rimelabs team to improve it, we're aware of some issues with consistency and slurring of speech.
Arcana adds \~250ms of latency to the voice pipeline, roughly the same as 11labs.
In the future it may be possible to define your own voices by description, eg: "old man with hoarse southern accent"
![Rimelabs Arcana Voices]()
## Krisp Noise Cancellation
[**Krisp Noise Cancellation**](#krisp-noise-cancellation)
Latency is one piece of the puzzle - but quality matters too. That’s why we’ve added [Krisp](https://krisp.ai/noise-cancellation/).
Background noise, especially speech or music, can seriously throw off voice agents. STT systems transcribe everything they hear, so voices in a coffee shop or lyrics from background music can easily get mistaken for the user’s input, leading to weird or incorrect responses. It can also confuse the agent into thinking the user isn’t done talking, delaying responses or interrupting playback. In short: noise kills both quality and speed.
All voice projects (web-voice widget and Twilio) automatically have Krisp noise cancellation applied.
[**Before Krisp:**](#before-krisp)
[**After Krisp:**](#after-krisp)
Here are two spectrograms, the upper one visualizing the audio that would be heard by STT without Krisp, and the lower one showing the audio after having been processed with Krisp.
Through our testing:
We've determined that this significantly boosts the accuracy of speech detection and transcription in noisy environments: cafes, offices, on the street, background broadcasts, etc.
Krisp noise cancellation adds \~20ms of latency to the audio pipeline, while drastically improving speech detection and transcription accuracy. This ultimately leads to faster final transcriptions, reducing overall speech-to-speech latency by \~100ms.
![Krisp Noise Cancellation]()
## Salesforce tools
We've added Salesforce tools to the agent step. You can now authenticate with Salesforce and add tools to enable your agent to get work done in Salesforce.
![Salesforce tools]()
![Salesforce tools]()
## Zendesk tools
We've added Zendesk tools to the agent step. You can now authenticate with Zendesk and add tools to enable your agent to get work done in Zendesk.
![Zendesk tools]()
![Zendesk tools]()
## Voice Keywords / Multilingual Speech-to-text
[**Keywords**](#keywords)
For voice calls we're introducing keywords. This allows your agent to understand hard to pronounce proper nouns (like product and company names), industry jargon, phrases and more. This is an optional field.
[**Multilingual**](#multilingual)
We're exposing Deepgram's latest [Nova-3](https://deepgram.com/learn/introducing-nova-3-speech-to-text-api) multilingual model as an STT option, capable of understanding and transcribing 8 different languages.
In addition, the standard English STT is being updated from Nova-2 to Nova-3, for a boost in performance.
![Voice Keywords / Multilingual Speech-to-text]()
![Voice Keywords / Multilingual Speech-to-text]()
## Introducing Voiceflow Credits: A simpler way to track usage
Today marks a significant milestone in Voiceflow's journey as we officially launch our new credit-based billing system. This update represents a fundamental shift in how you'll track, manage, and optimize your Voiceflow usage - all designed to bring greater simplicity, transparency, and predictability to your experience.
[**What's New**](#whats-new)
[**🎉 Voiceflow Credits**](#-voiceflow-credits)
We've completely overhauled our billing system, moving away from the complex token-based approach to a streamlined credit system that unifies tracking across all platform features:
* Simplified Measurement: One unified credit system for all actions (calls, messages, LLM responses, TTS)
* Predictable Costs: Clear pricing tiers that make budget planning straightforward
* Transparent Usage: Detailed visibility into exactly how your credits are being consumed
* Developer-Friendly: Messages only count toward credits when your agent is used in production - not when developing in-app or using shareable prototypes
[**📊 New Usage Dashboard**](#-new-usage-dashboard)
We've launched a brand-new Usage Dashboard that gives you comprehensive insights into your credit consumption. The dashboard allows you to:
* View your total available and used credits
* Track usage across all agents or drill down into specific ones
* Monitor editor and agent allocation
* Analyze usage patterns over time
[**💼 Enhanced Team Management**](#-enhanced-team-management)
Additional editor seats are now just \$50 per month with no complicated caps or restrictions. Add as many team members as needed, whenever you need them.
[**🏢 Business Plans (formerly Teams)**](#-business-plans-formerly-teams)
As part of this update, we're renaming our Teams plans to Business plans, with enhanced features and capabilities for enterprise customers.
[**Resources to Help You Transition**](#resources-to-help-you-transition)
We've created dedicated resources to help you understand and make the most of the new credit system:
* [What are Voiceflow Credits?](https://www.voiceflow.com/lessons/what-are-credits) - A comprehensive guide to understanding how credits work
* [Introducing Voiceflow Credits](https://www.voiceflow.com/pathways/introducing-voiceflow-credits) - Learn about the philosophy behind the change and how it benefits you
* [Credit Calculator](https://www.voiceflow.com/pathways/introducing-voiceflow-credits#calculator) - Estimate your credit needs based on your specific usage patterns
[**Frequently Asked Questions**](#frequently-asked-questions)
What do I need to do? Use our [Credit Calculator](https://www.voiceflow.com/pathways/introducing-voiceflow-credits#calculator) to understand your usage. For most users, no action is required.
Will my monthly bill increase? Most organizations will see a decrease in costs, particularly those with multiple editor seats. There are three changes to be aware of:
* Annual plans now offer a 10% discount (previously 20%)
* Editor seats now cost \$50/month with no restrictions (a price reduction)
* Business plan (formerly Teams) base tier increases from \$125 to \$150
Do credits roll over? Credits expire at the end of your subscription period. For monthly plans, unused credits don't roll over month-to-month. Annual subscribers receive all credits at once to use throughout the year.
What happens if I exceed my credit allocation? You'll receive a notification as you approach your limit. There's no automatic charging - you can choose whether to upgrade to a higher credit package.
Do messages in development count toward my credit usage? No, messages only count toward credits when your agent is used in production. Messages sent while developing in-app or when using shareable prototypes don't consume credits, giving you the freedom to build and test without worrying about credit usage.
We're committed to making this transition as smooth as possible. If you have any questions or need assistance, please reach out to [support@voiceflow.com](mailto:support@voiceflow.com).
![Introducing Voiceflow Credits: A simpler way to track usage]()
## Support for OpenAI o3 and o4 mini
[**Added:**](#added)
* Support for OpenAI o3 and o4 mini
![Support for OpenAI o3 and o4 mini]()
## Support for GPT 4.1 models
[**Added:**](#added)
* Support for GPT 4.1, GPT 4.1 mini and GPT 4.1 nano
![Support for GPT 4.1 models]()
## Minor Updates / Fixes
[**Improvements:**](#improvements)
* Voice Widget latency decreased by up to 750ms
* Voice Widget now streams with more consistent linear16\@16kHz encoding
[**Fixes:**](#fixes)
* Reset memory when a new conversation is launched (launch request)
* Global no reply not working on Agent steps
* The maximum allowed length for `{userID}` in the [Dialog API](/reference/interact-stream) will be set to 128 characters, effective April 18th
* Unable to remove webhook URLs
* Analytics visualization UI bug
* Voice Widget always setting userID to test on transcripts
* Chat Widget no audio output after page reload
* Export variables fails when project has large number of variables
## Call Events Webhook
[**Changes:**](#changes)
* New support added to subscribe to call events via webhook, for both twilio IVR and voice widget projects [Call Events Documentation](/reference/call-events) Webhook system is capable of broadcasting additional events in the future
![Call Events Webhook]()
## Streaming Text in Chat Widget Now Optional
[**Changes:**](#changes)
* Added option to disable streaming text in chat widget Stream text can now be turned off in the Modality & interface settings When disabled, the full agent response will be displayed at once instead of being streamed out. Useful for situations where streaming longer messages is not desired
![Streaming Text in Chat Widget Now Optional]()
## Max Memory Turns Setting
Conversation memory is a critical component of the Agent and Prompt steps. Having longer memory gives the LLM model more context about the conversation so far, and make better decisions based on previous dialogs.
However, larger memory adds latency and costs more input tokens, so there is a drawback.
Before, memory was always set to 10 turns. All new projects will now have a default of 25 turns in memory. This can now be adjusted this in the settings, up to 100 turns.
For more information on how memory works, reference: [https://docs.voiceflow.com/docs/memory](/docs/memory)
![Max Memory Turns Setting]()
## Agent Step, Structured Output Improvements, Gemini 2.0 Flash
We're excited to introduce several major updates that enhance the capabilities of the Agent step and expand our model offerings. These improvements provide more flexibility, control, and opportunities for creating powerful AI agents.
[**🧠 Agent Step: Your All-in-One Solution**](#-agent-step-your-all-in-one-solution)
The Agent step has been supercharged to create AI agents that can intelligently respond to user queries, search knowledge bases, follow specific conversation paths, and execute functions - all within a single step. Key features include:
* Intelligent Prompting: Craft detailed instructions to guide your agent's behavior and responses.
* Function Integration: Connect your agent with external services to retrieve and update data.
* Conversation Paths: Define specific flows for your agent to follow based on user intent.
* Knowledge Base Integration: Enable your agent to automatically search your knowledge base for relevant information.
For a comprehensive guide on using the Agent step, check out our [Agent Step Documentation](/docs/agents).
[**🎨 Expanded Support for Structured Output**](#-expanded-support-for-structured-output)
We've significantly expanded our support for structured output, unlocking more use cases and giving you greater control over your agent's responses:
* Arrays and Nested Arrays: You can now define arrays and nested arrays in your output structure.
* Nested Objects: Structured output now supports nested objects, allowing for more complex data structures.
These enhancements enable you to create more sophisticated agents that generate highly structured and detailed responses, reducing the risk of hallucinations and ensuring more accurate outputs.
[**⚡ Gemini 2.0 Flash Support**](#-gemini-20-flash-support)
We've added support for the Gemini 2.0 Flash model, offering you even more options for powering your AI agents. Gemini 2.0 Flash delivers exceptional performance and speed, enabling faster response times and improved user experiences.
To start using Gemini 2.0 Flash, simply select it from the model dropdown when configuring your Agent step.
We can't wait to see what you'll build with these new features and capabilities! As always, we welcome your feedback and suggestions as we continue to improve our platform.
Happy building! 🛠️
The Voiceflow Team
![Agent Step, Structured Output Improvements, Gemini 2.0 Flash]()
## Variable Handling Update: Consistent Behavior for Undefined Values
[**Changes:**](#changes)
* Updated Voiceflow variable handling for consistency in previously undefined behavior: Variables can be any JavaScript object that is JSON serializable. Any variable set to `undefined` will be saved as `null` (this conversion happens at the end of the step, so it does not affect the internal workings of JavaScript steps and functions). Functions can now return `null` (rather than throwing an error) and can no longer return `undefined` (which could cause agents to crash). Functions that attempt to return `undefined` will now return `null` (to ensure backwards compatibility).
These changes will go info effect March 31st.
## New Analytics Dashboard: Gain Deeper Insights into Your Agent's Performance
We've revamped our Agent Analytics Dashboard, not only giving it a fresh new look but also introducing a range of powerful visualizations that provide unprecedented visibility into your agent's performance.
[**🌟 New Visualizations**](#-new-visualizations)
The updated Analytics Dashboard offers a comprehensive set of visualizations that allow you to track and analyze various aspects of your agent's performance:
* Tokens Usage: Monitor AI token consumption over time across all models, giving you a clear picture of your agent's token utilization.
* Total Interactions: Keep track of the total number of interactions (requests) between users and your agent over time, providing insights into engagement levels.
* Latency Monitoring: Measure the average response time of your agent to ensure optimal performance and identify any potential bottlenecks.
* Total Call Minutes: Gain visibility into the cumulative duration of voice calls in minutes, helping you understand the volume and significance of voice interactions.
* Unique Users: Identify the count of distinct users interacting with your agent over time, allowing you to track adoption and growth.
* KB Documents Usage: Analyze the frequency of knowledge base document access, with the ability to toggle between ascending and descending order to identify the most or least used documents.
* Intents Usage: Visualize the distribution of triggered intents, with sorting options to analyze intent frequency and identify popular or underutilized intents.
* Functions Usage: Monitor the frequency of function calls, their success/failure and latency, with sorting capabilities to identify the most or least used functions and optimize your agent's functionality.
* Prompts Usage: Gain insights into the usage frequency of agent prompts, with the ability to toggle between ascending and descending order to analyze prompt utilization and effectiveness.
[**📅 Data Availability**](#-data-availability)
Please note that the new Analytics Dashboard service only has data starting from February 9th, 2025. If you require data prior to that date, you can still access it through our Analytics API.
[**🔧 Upcoming Analytics API Update**](#-upcoming-analytics-api-update)
We're also working on a new version of the Analytics API that will include the additional data points tracked by the new Analytics Dashboard service. Stay tuned for more information on this exciting update!
![New Analytics Dashboard: Gain Deeper Insights into Your Agent's Performance]()
## New Models, Function Editor Enhancements, and Call Recording
We're thrilled to announce several exciting updates that expand your AI agent building capabilities and improve your workflow. Let's dive into what's new!
[**🧠 New Models: Deepseek R1, Llama 3.1 Instant, and Llama 3.2**](#-new-models-deepseek-r1-llama-31-instant-and-llama-32)
We've expanded our model offerings to give you even more options for creating powerful AI agents:
* Deepseek R1: Harness the potential of Deepseek's R1 model for enhanced natural language understanding and generation.
* Llama 3.1 Instant: Experience lightning-fast responses with the Llama 3.1 Instant model.
* Llama 3.2: Leverage the advanced capabilities of Llama 3.2
These new models are available on all paid plans.
[**⚙️ Function Editor Enhancements: Modal View and Snippets**](#️-function-editor-enhancements-modal-view-and-snippets)
We've made some significant improvements to the Function Editor to streamline your development process:
* Modal View: You can now open the Function Editor as a modal directly from the canvas. This allows you to make quick updates and navigate between your functions and the canvas seamlessly.
* Snippets: We've introduced a new snippets feature that enables you to insert pre-written code snippets for common concepts in Voiceflow functions.
[**📞 Call Recording for Twilio Phone Calls**](#-call-recording-for-twilio-phone-calls)
We're excited to introduce call recording functionality for phone calls made through Twilio:
* Automatic Call Recording: All phone calls between users and your AI agent will now be automatically recorded.
* Twilio Integration: The call recordings will be accessible directly in your Twilio account for easy review and management.
You can enable this option in the Agent Settings page under Voice.
![New Models, Function Editor Enhancements, and Call Recording]()
![New Models, Function Editor Enhancements, and Call Recording]()
## Retrieval-Augmented Generation (RAG) for Intent Recognition
We're excited to announce a significant upgrade to our intent recognition system, moving from the traditional Natural Language Understanding (NLU) approach to Retrieval-Augmented Generation (RAG) model using embeddings. This transition brings notable improvements to the speed, accuracy, and overall user experience when interacting with AI agents on our platform.
[**📅 Phased Rollout**](#-phased-rollout)
To ensure a smooth adoption, we will be rolling out the RAG-based intent recognition system to all users in phases over the next week. This gradual deployment allows us to monitor performance and gather feedback while providing ample time for you to adjust to the new system.
[**🆕 Default for New Projects**](#-default-for-new-projects)
For all new projects created on our platform, the RAG-based intent recognition will be the default system. This means that new AI agents will automatically benefit from the enhanced speed, accuracy, and natural conversation capabilities offered by RAG.
[**🌟 Faster Training and Interaction**](#-faster-training-and-interaction)
With the new RAG system, agent training and intent recognition are now substantially faster and more efficient. For example, an agent with 37 intents and 305 utterances now trains about 20 times faster, in just around 1 second. This means quicker agent development and smoother conversations for end-users.
[**🧠 Automatic Agent Training**](#-automatic-agent-training)
Thanks to the advanced training speed enabled by RAG, explicit training is no longer necessary. Simply test your agent, and the training will happen automatically behind the scenes, streamlining your workflow.
[**🎯 Enhanced Understanding of Complex Queries**](#-enhanced-understanding-of-complex-queries)
RAG leverages embeddings to capture the deeper context and meaning behind words, even when phrased differently. This allows the system to better understand and accurately match complex, detailed questions to the appropriate intents, providing more precise responses to users.
[**🗣️ More Natural Conversations**](#️-more-natural-conversations)
With the improved understanding of casual language, slang, and diverse phrasing, the RAG system enables a more natural, conversational experience for users interacting with AI agents on our platform.
[**🔄 Seamless Transition for Existing Projects**](#-seamless-transition-for-existing-projects)
For existing projects, we will keep both the NLU and RAG systems running concurrently for a period of time. This allows you to explore the new system, test it thoroughly, and make any necessary adjustments to your agents. You can easily switch between the NLU and RAG systems in the intent classification settings within the Intents CMS.
We're thrilled to bring you this enhanced experience and look forward to hearing your feedback as you interact with the new RAG-based intent recognition system. Your input is invaluable in helping us continue to innovate and improve our platform to better serve your needs.
![Retrieval-Augmented Generation (RAG) for Intent Recognition]()
## Expanding the Possibilities of User Interaction with Voice
In our mission to redefine how users interact with AI agents, we have introduced a new voice modality option to our web widget. This addition is a step towards creating more natural, intuitive, and engaging user experiences. By enabling voice-based conversations, we are empowering businesses to connect with their customers in a way that feels authentic and effortless.
Voice technology has become an increasingly popular and preferred mode of interaction for many users. By integrating voice functionality into our web widget, we are meeting users where they are and providing them with a seamless way to engage with AI agents. This not only enhances the user experience but also opens up new possibilities for businesses to assist, inform, and guide their customers throughout the customer journey.
[**Natural Voice Interaction**](#natural-voice-interaction)
The web widget now supports voice-based communication, allowing users to speak naturally with AI agents. Businesses can integrate this feature to provide their customers with a hands-free, intuitive way to ask questions, receive recommendations, and get assistance while browsing the site.
[**Customization Options**](#customization-options)
The voice widget offers customization options to ensure seamless integration with your website's branding:
* Launcher Style: Select a launcher style that complements your site's design.
* Color Palette: Choose colors that match your brand guidelines.
* Font Family: Pick a font that aligns with your website's typography.
These options allow you to maintain a consistent brand experience across all customer touchpoints.
[**Powered by Advanced Voice Tech**](#powered-by-advanced-voice-tech)
The voice functionality in the widget leverages the best in voice technologies to deliver high-quality conversations:
* Automated Speech Recognition: Our platform uses advanced STT technology from Deepgram to accurately transcribe user speech in real-time.
* Organic Text-to-Speech: We've integrated with leading providers like 11 Labs and Rime to offer a variety of natural-sounding voices that bring AI agents to life.
These technologies ensure that conversations with AI agents feel authentic, engaging, and representative of your brand's personality.
[**Start Exploring Voice**](#start-exploring-voice)
We invite all our users to start experimenting with the voice capabilities.
As you explore voice functionality, we value your feedback and ideas s- join our Discord community! Your input plays a crucial role in shaping the future of voice-based interactions in the web widget and helping us refine the user experience.
![Expanding the Possibilities of User Interaction with Voice]()
![Expanding the Possibilities of User Interaction with Voice]()
## AI Fallback
We're excited to introduce AI Fallback, a powerful new feature in beta that enhances the reliability and continuity of your AI operations. This feature ensures your AI services remain operational even during provider outages or service interruptions.
[**🔄 Automatic Fallback Switching**](#-automatic-fallback-switching)
AI Fallback automatically switches between models when issues arise. When your primary AI model experiences difficulties, the system seamlessly transitions to your configured backup model, ensuring continuous operation of your AI services.
[**⚙️ Easy Configuration**](#️-easy-configuration)
Setting up AI Fallback is straightforward:
1. Access your agent
2. Navigate to agent settings
3. Set your preferred fallback model by provider
That's all there is to it! The system handles everything else automatically.
[**📈 Enhanced Reliability**](#-enhanced-reliability)
AI Fallback delivers key benefits:
* Minimizes service disruptions during model outages
* Maintains consistent AI performance
* Reduces operational impact of provider issues
* Ensures business continuity
[**🔬 Under the Hood**](#-under-the-hood)
The system continuously monitors your primary AI model's performance and availability. When issues are detected, it automatically:
* Identifies the next available model in your sequence
* Switches ongoing operations to the backup model
* Returns to the primary model once issues are resolved
[**🚀 Getting Started**](#-getting-started)
AI Model Fallback is available exclusively for Teams and Enterprise customers. We're excited to hear your feedback during the beta phase! 🎯
![AI Fallback]()
## New Features: Structured Outputs and Variable Pathing
Today we're introducing two powerful new capabilities in Voiceflow: Structured Outputs and Variable Pathing. These features expand the possibilities for working with data from large language models (LLMs) in your agents. Let's explore what they enable!
[**🎉 Structured Outputs**](#-structured-outputs)
Structured Outputs let you define the format of the data you expect an LLM to return, giving you more control and predictability over the results.
* In a prompt step, enable the new "JSON Output" option to specify the structure of the LLM's response.
* Today, Structured Outputs support the following data types: String Number Boolean Integer Enum
* Support for arrays and nested objects is planned for the near future.
* Structured Outputs are available with `gpt-4o-mini` and `gpt-4o` models.
[**💪 Variable Pathing**](#-variable-pathing)
Variable Pathing provides a streamlined way to work with complex data structures in your Voiceflow project.
* Store an entire object in a single variable, then access its properties using dot notation (eg: `user.name`, `user.email`).
* Capture Structured Output responses or API results as objects.
* Use object properties directly in conditions, messages, and other steps.
* Reduce the need for multiple variables to represent a single entity.
[**🍰 Bringing it All Together**](#-bringing-it-all-together)
Combining Structured Outputs and Variable Pathing opens up new design patterns for crafting agent experiences:
* Define precise data requirements for LLMs to provide relevant information
* Capture responses as feature-rich objects in a single step
* Access and manipulate object properties throughout your project
* Streamline your project's design while expanding its capabilities
We're excited to see the voice experiences you create with these new tools! Feel free to share your questions and feedback with us.
![New Features: Structured Outputs and Variable Pathing]()
![New Features: Structured Outputs and Variable Pathing]()
## Voiceflow Telephony
We're excited to announce the release of Voiceflow Telephony, bringing enterprise-grade voice capabilities to your conversational experiences. This release represents a significant milestone in our mission to provide comprehensive, low-latency voice solutions for businesses of all sizes.
[**Native Twilio Integration**](#native-twilio-integration)
We've integrated with Twilio to make phone-based interactions as simple as possible. The new integration allows you to:
* Import existing Twilio phone numbers directly into Voiceflow
* Associate phone numbers with specific agents
* Configure separate numbers for development and production environments
* Test different versions of your agent against different phone numbers
Setting up telephony is straightforward: simply connect your Twilio account with existing phone numbers, import them into Voiceflow, and assign them to your agents. Your voice experience will be live within minutes.
[**High-Performance Voice**](#high-performance-voice)
[**Streaming Technology**](#streaming-technology)
We've built our telephony feature on top of our streaming API, delivering exceptional performance improvements:
* Dramatically reduced response times
* Near real-time agent reactions
* Optimized voice processing pipeline
[**Speech Recognition**](#speech-recognition)
We've selected Deepgram to provide industry-leading Speech To Text (STT):
* High-accuracy transcription
* Low-latency processing
* Support for over 20 languages
[**Advanced Voice Capabilities**](#advanced-voice-capabilities)
[**Outbound Calling**](#outbound-calling)
We've introduced powerful outbound calling capabilities:
* Programmatically initiate calls to any phone number
* Test outbound calls directly from the Voiceflow interface
* Integrate outbound calling into your existing workflows
[**Voice Technology Stack**](#voice-technology-stack)
Our comprehensive voice stack includes:
* Premium text-to-speech voices from industry leaders, such as: ElevenLabs Rime Google
* Support for advanced telephony features through custom actions: Call forwarding DTMF handling Interruption behaviour
[**Voice Experience Configuration**](#voice-experience-configuration)
We've exposed detailed configuration options to fine-tune your voice experiences:
[**Audio Settings**](#audio-settings)
* Background audio customization
* Audio cue configuration
[**Interaction Parameters**](#interaction-parameters)
* Interruption threshold controls
* Utterance end detection
* Response timing optimization
* User input acceptance timing
[**Beta Program Details**](#beta-program-details)
[**Access and Limitations**](#access-and-limitations)
During the beta period, all users will have access to telephony features with the following concurrent call limits:
[**Coming Soon**](#coming-soon)
* Enhanced call analytics and reporting
* Additional voice customization options
![Voiceflow Telephony]()
![Voiceflow Telephony]()
![Voiceflow Telephony]()
![Voiceflow Telephony]()
## New AI-Native Webchat
We're excited to announce a complete reimagining of the Voiceflow webchat experience. This new version introduces AI-native capabilities, enhanced customization options, and flexible deployment methods to help you create more engaging conversational experiences.
[**AI-Native**](#ai-native)
Our webchat has been rebuilt from the ground up to provide a more natural, AI-driven conversation experience:
* Streaming Text Support: Experience real-time message generation with character-by-word streaming, creating a more engaging and dynamic conversation flow. Users can see responses being crafted in real-time, similar to popular AI chat interfaces.
* AI Disclaimers: Built-in support for displaying AI disclosure messages and customizable AI usage notifications to maintain transparency with your users.
[**Enhanced Customization**](#enhanced-customization)
We've significantly expanded the customization capabilities to give you more control over your chat interface:
[**Interface Types**](#interface-types)
You can now choose from three distinct interface modes:
* Widget: Traditional chat window that appears in the corner of your website
* Popover: Full-screen chat experience that overlays your content
* Embed: Seamlessly integrate the chat interface directly into your webpage layout
[**Visual Customization**](#visual-customization)
The new version introduces comprehensive styling options:
* Color System: Expanded colour palette support with primary, secondary, and accent colour definitions
* Typography: Custom font family support
* Launcher Variations: Classic bubble launcher with customizable icons Button-style launcher with text support
[**Important Notes**](#important-notes)
* Chat Persistence: Now configured through the snippet rather than UI settings.
* Custom CSS: Maintained compatibility with most existing class names.
* Proactive Messages: Temporarily unavailable in this release, with support coming soon
You can find more details [here](/docs/web-chat-migration).
[**Migration**](#migration)
For detailed instructions on migrating from the legacy webchat, please refer to our [Migration Guide](/docs/web-chat-migration).
![New AI-Native Webchat]()
![New AI-Native Webchat]()
## Function libraries, starter templates and ElevenLabs support
[**Function Libraries**](#function-libraries)
Integrate your agent with your favorite tools using our new function libraries. Access pre-built functions for popular platforms like Hubspot, Intercom, Shopify, Zendesk, and Zapier. These functions, sourced from Voiceflow and the community, make it easier than ever to connect Rev with your existing workflows. Showcase readily available integrations to your team and clients.
[**Transcript Review Hotkeys**](#transcript-review-hotkeys)
Reviewing transcripts just got faster and more efficient. You can now press `R` to mark a transcript as Reviewed or `S` to Save it for Later. These handy shortcut keys are perfect for power users who review a high volume of transcripts.
[**Project Starter Templates**](#project-starter-templates)
Getting started is now a breeze. When creating a new project, choose from a set of templates tailored for common use cases like customer support, ecommerce support, and scheduling. These templates help you hit the ground running without the need for extensive setup and customization. Ideal for new users and busy teams.
[**Expanded Voice Support**](#expanded-voice-support)
We now offer an even greater selection of natural-sounding AI voices. We've added support for a variety of new options from ElevenLabs and Rime. Please note that using these voices consumes AI tokens. Check them out for your projects that could benefit from additional voice choices.
![Function libraries, starter templates and ElevenLabs support]()
![Function libraries, starter templates and ElevenLabs support]()
![Function libraries, starter templates and ElevenLabs support]()
## Important Update: Deprecation of AI Response and AI Set Steps
This is an important update to our platform. As part of our ongoing commitment to enhancing your experience and providing the most advanced tools for AI agent development, we have made the decision to deprecate the AI Response and AI Set steps.
What does this mean for you?
* On February 4th, 2025, the AI Response and AI Set steps will be disabled from the step toolbar in the Voiceflow interface to encourage users to move away of these deprecated steps. Existing steps will remain untouched and will continue working as per normal.
* On June 3rd, 2025, these steps will no longer be supported. Any existing projects using these steps will need to be migrated to the new [Prompt](/docs/prompt-step) and [Set](/docs/variables-set) steps. We will be sending out additional communication in advance to the sunset date.
We understand that this change may require some adjustments to your workflow, but rest assured that we are here to support you throughout this transition. The new Prompt and Set steps, along with our powerful Prompt CMS, offer even more flexibility and control over your conversational experiences.
Some key benefits of the new approach include:
* Centralized prompt management:[The Prompt CMS](/docs/prompts-cms-and-editor) serves as a hub for all your prompts, making it easy to create, edit, and reuse them across your projects.
* Advanced prompt configuration: Leverage system prompts, message pairs, conversation history, and variables to craft highly contextual and dynamic responses.
* Seamless integration: The Prompt step allows you to bring your prompts directly into your conversation flows, while the Set step lets you assign prompt outputs to variables for enhanced logic and control.
* Continued innovation: We are committed to expanding the capabilities of these new features, with exciting updates planned for the near future.
For those using the Knowledge Base, we recommend transitioning to the[KB Search step](/docs/kb-search). This step allows you to query your Knowledge Base and feed the results into a prompt, enabling even more intelligent and relevant responses.
To help guide you through migrating from the AI steps to the Prompt step, check our walkthrough below:
We value your feedback and are here to address any questions or concerns you may have. Our team is dedicated to ensuring a smooth transition and helping you unlock the full potential of these powerful new features.
Thank you for your understanding and continued support. We are excited about the future of conversational AI development on Voiceflow and look forward to seeing the incredible experiences you will create with these enhanced capabilities.
Best regards,
Voiceflow
# Build an advanced FAQ agent with metadata filtering
Source: https://docs.voiceflow.com/courses/advanced-knowledge-base
Create a support agent for different user types using metadata filtering to serve the right content.
In this tutorial, you will build a support agent for GoRoute, a fictional ride-sharing and delivery platform. GoRoute has two user types, drivers and couriers, each with different policies, FAQs, and workflows. You'll import content from two separate help sites using LLM chunking strategies, tag each with metadata, and build playbooks that filter the knowledge base so drivers only see driver content and couriers only see courier content.
Before you start, visit [goroute.demo.voiceflow.com](https://goroute.demo.voiceflow.com/) to explore the GoRoute website and see the content you'll be importing into the knowledge base.
From the [Dashboard](https://creator.voiceflow.com), go to **Projects** → **New project**. Name your project "GoRoute Support", set the type to **Chat**, and select **Start from scratch**.
Click **Knowledge Base** in the left sidebar, then **Add data sources**. Select **Sitemap** and paste the URL for the driver help center:
```text theme={null}
https://goroute.demo.voiceflow.com/driver
```
Voiceflow will crawl the sitemap and import all pages under this URL. Under the **Folder** dropdown, click **Create folder** and name it "Driver". This keeps your driver content organized and easy to find as your knowledge base grows.
Under **LLM chunking strategies**, enable the following three options:
* **Smart chunking**: splits content into logical, topic-based sections, which works well for help articles that cover multiple topics on a single page.
* **FAQ optimization**: generates sample questions each section could answer, improving retrieval when users phrase things differently than the source content.
* **Remove HTML and noise**: cleans up messy formatting from web pages so the agent processes clean text.
Different types of content benefit from different chunking strategies. The combination above works well for help center sites, but when you import your own data, experiment with different strategies to find what gets the best results for your content.
Before importing, click **+** in the **Metadata** section and add the following tag:
| Key | Value |
| ----------- | -------- |
| `user_type` | `driver` |
This metadata tag is what allows you to filter queries later so the agent only retrieves driver-specific content when helping a driver.
Click **Add data sources** again. Select **Sitemap** and paste the courier help center URL:
```text theme={null}
https://goroute.demo.voiceflow.com/courier
```
Create a new folder called "Courier" under the **Folder** dropdown. Then select the same three **LLM chunking strategies** as before: **Smart chunking**, **FAQ optimization**, and **Remove HTML and noise**. Add the metadata tag:
| Key | Value |
| ----------- | --------- |
| `user_type` | `courier` |
After both imports finish, your knowledge base will contain content from both help centers. Each article will be tagged based on `user_type`. You can verify this by clicking on a data source and checking its metadata in the right panel. You'll also notice that each page has been split into multiple chunks based on the sections of the page. This is the LLM chunking strategies at work, breaking content into logical, topic-based pieces so the agent can retrieve more precise answers.
Click the **Agent** tab. You'll configure two things here: the **Global prompt** and the **Instructions**. The global prompt defines your agent's personality and applies to every turn. Instructions tell the agent how to route requests to the right skill.
In the **Global prompt** section, define your agent's identity:
```text highlight={3-4} theme={null}
# Personality
You are a support agent for GoRoute, a ride-sharing and delivery platform. You help both drivers and couriers with questions about the platform, policies, earnings, and troubleshooting.
# Tone
Friendly, clear, and efficient. Keep answers concise. Use simple language, as many users are checking between rides or deliveries.
# Guardrails
Never provide information meant for drivers to couriers, or vice versa. The policies are different and mixing them up causes real problems. If you're unsure which user type someone is, ask before answering. Never guess at pay rates, bonuses, or policy details.
```
Then in the **Instructions** field, add routing logic. You'll reference the playbooks you create in the next steps, so come back here to update the skill names if needed:
```text theme={null}
# Identify the user
At the start of the conversation, determine whether the user is a driver or a courier. If it's not clear from their first message, ask: "Are you a GoRoute driver or a courier?"
# Skills
Route to the Driver Support playbook when the user is a driver and asks about ride policies, earnings, vehicle requirements, driver app issues, or any driver-specific topic.
Route to the Courier Support playbook when the user is a courier and asks about delivery policies, earnings, bag requirements, courier app issues, or any courier-specific topic.
If the user asks about something that applies to both (like account settings or payment methods), route to whichever playbook matches the user type they identified as.
```
Finally, toggle off the **Knowledge base** in the **System tools** section of the sidebar. In this tutorial, you only want the knowledge base queried from inside playbooks where metadata filtering is configured. Leaving it on at the agent level would let the agent query all content without any filtering, which could return the wrong information for the user type.
In the **Agent** tab, click **+** in the **Skills** panel to create a new [playbook](/documentation/build/playbooks). Name it "Driver Support".
Set the **Trigger**:
```text theme={null}
Answers questions about GoRoute driver topics including ride policies, earnings, vehicle requirements, and driver app issues.
```
Then write the playbook **instructions**:
```text theme={null}
# Goal
Help the driver find accurate answers to their questions about driving on the GoRoute platform.
# Steps
1. Search the knowledge base for information related to the driver's question.
2. Provide a clear, concise answer based on what you find.
3. If the answer involves multiple steps (like a setup process or troubleshooting flow), walk through them one at a time.
4. If no relevant information is found, let the driver know and offer to connect them with the GoRoute driver support team.
# Important
Only use information retrieved from the knowledge base. Do not answer driver questions from general knowledge. GoRoute policies are specific to the platform.
```
In the **System tools** section on the right, enable the **Knowledge base** tool. Then, click on the tool to expand its settings. Open **Advanced query settings**, then under **Metadata filtering** click **+** to add a filter:
| Key | Value |
| ----------- | -------- |
| `user_type` | `driver` |
This ensures that when the agent runs the Driver Support playbook, it only retrieves content tagged with `user_type: driver`. Courier content will never appear in the results.
Create another playbook called "Courier Support".
Set the **Trigger**:
```text theme={null}
Answers questions about GoRoute courier topics including delivery policies, earnings, bag requirements, and courier app issues.
```
Then write the playbook **instructions**:
```text theme={null}
# Goal
Help the courier find accurate answers to their questions about delivering on the GoRoute platform.
# Steps
1. Search the knowledge base for information related to the courier's question.
2. Provide a clear, concise answer based on what you find.
3. If the answer involves multiple steps, walk through them one at a time.
4. If no relevant information is found, let the courier know and offer to connect them with the GoRoute courier support team.
# Important
Only use information retrieved from the knowledge base. Do not answer courier questions from general knowledge. GoRoute policies are specific to the platform.
```
Then configure metadata filtering on this playbook's Knowledge base tool. Open **Advanced query settings**, click **+** next to **Metadata filtering**, and this time set the value to `courier`:
| Key | Value |
| ----------- | --------- |
| `user_type` | `courier` |
Click **Run** in the top-right corner to test your agent. Try sending these messages to verify routing and filtering are working correctly:
```text theme={null}
Driver test: "I'm a driver. What are the vehicle requirements to drive for GoRoute?"
Courier test: "Hey, I do deliveries for GoRoute. What kind of bag do I need?"
Ambiguous test: "How do I update my payment info?"
```
Check the conversation logs to confirm:
* The correct playbook was triggered for each user type
* The knowledge base query results only contain content matching the right `user_type` metadata tag
* The ambiguous test prompts the agent to ask which user type they are, unless you've already mentioned your user type.
## Tips for building filtered knowledge bases
* **Verify your filtering.** Monitor the logs panel while testing and click into the logs labelled `[Agent] knowledge base search completed`. You should only see chunks tagged with the correct `user_type`. If you see mixed results, double-check your metadata tags on the data sources and the filter configuration in each playbook.
* **Combine chunking strategies for web content.** Smart chunking splits pages into logical sections, FAQ optimization helps match varied user phrasing, and Remove HTML and noise cleans up web formatting. Together, they significantly improve retrieval quality for help center content.
* **Scale this pattern.** You can add more user types (eg: `user_type: restaurant_partner`) by importing more content with new metadata values and creating additional playbooks with the corresponding filters.
## What's next?
You've built an agent that serves different content to different user types using metadata filtering. Explore these resources to go deeper.
Advanced configuration for knowledge base queries, including custom queries and query re-writing.
Programmatically import data into your knowledge base, ensuring it always stays up to date.
# Build your first workflow
Source: https://docs.voiceflow.com/courses/build-your-first-workflow
Create a deterministic flow with a financial disclaimer, buttons, and an embedded playbook for guided conversations.
In this tutorial, you'll build a [workflow](/documentation/build/workflows) for NestEgg, a fictional Canadian financial guidance platform. Workflows are step-by-step flows where every step runs in sequence, exactly as you designed it, with no room for the agent to improvise. They're ideal for processes that must happen in a specific order, like compliance disclaimers, identity verification, or onboarding checklists.
When a user asks Nesty, NestEgg's assistant, for financial advice, the agent will route to the workflow you build. The workflow will display a legal disclaimer, present [buttons](/documentation/build/steps/buttons) to accept or decline, and hand off to a [playbook](/documentation/build/steps/playbook) for a flexible financial conversation if the user agrees. If they decline, control returns to the [agent](/documentation/build/global-prompt). This should take about 5 minutes.
Open the NestEgg Agent template below, choose a workspace to import it to, then click **Import** to add it to your workspace.
Pre-configured NestEgg agent with playbooks and knowledge base content.
The template comes pre-configured with a global prompt, instructions, and knowledge base content for NestEgg. Two playbooks, **Explain NestEgg** and **Glossary Helper**, are already attached to the agent and handle platform questions and financial term definitions. A third playbook, **Explore Finances**, is included but not yet connected. You'll embed it inside the workflow you're about to build.
The only piece missing is a **Financial Guidance** workflow that gates financial advice behind a legal disclaimer. You'll build that now.
In the **Agent** tab, click **+** in the **Skills** panel to create a new [workflow](/documentation/build/workflows). Name it "Financial guidance".
Set the **Trigger** to:
```text theme={null}
Displays the financial disclaimer and collects the user's agreement before providing financial guidance.
```
Then click **Create workflow**. You'll be taken to the canvas where you'll build the workflow step by step.
Drag a [**Message** step](/documentation/build/steps/message) onto the canvas and connect it to the Start chip. If you don't see the Message step, press the **⌵** button at the top of the step sidebar to show scripted steps.
In the message step, write the following disclaimer message:
```text theme={null}
Before we continue, please review the following disclaimer:
NestEgg provides general financial education and information only. Nothing shared in this conversation constitutes personalized financial advice, investment recommendations, or a solicitation to buy or sell any financial product. Your financial situation is unique. Please consult a licensed financial advisor before making any investment decisions.
```
Leave **Wait for user input** disabled. The buttons in the next step will handle that.
Drag a [**Buttons** step](/documentation/build/steps/buttons) onto the bottom of your Message step to add buttons to your message. Then, add two buttons:
* `I agree`
* `I don't agree`
Each button creates its own connection point on the step. You'll wire each one to a different path.
Drag a [**Playbook** step](/documentation/build/steps/playbook) onto the canvas and connect it to the "I agree" button's connection point. If you don't see the Playbook step, click the **⌵** button at the top of the step sidebar to switch back to agentic steps.
Then, click into the Playbook step you just added and select the "**Explore finances**" playbook. You should also ensure the **Playbook talks first** is enabled so the playbook greets the user immediately after they accept the disclaimer.
Once you select the playbook, you'll see an [exit condition](/documentation/build/playbooks) called "User is finished exploring" appear as a connection point on the step. This is how the playbook signals to the workflow that the conversation is finished. Leave it unconnected - when a connection point in a workflow has no target, control passes back to your [agent](/documentation/build/global-prompt) automatically.
Drag a [**Message** step](/documentation/build/steps/message) onto the canvas and connect it to the "I don't agree" button's connection point. Write a short acknowledgment:
```text theme={null}
No problem. If you change your mind, just ask and I can bring up the disclaimer again. Is there anything else I can help you with?
```
Enable **Wait for user input** on this message so the workflow pauses for the user to respond before handing off to the agent. Leave the output port unconnected. This returns control to the agent.
Your completed workflow should look like this:
![Finishedworkflow]()
![Finishedworkflow]()
Click **Run** in the top-right corner to test your agent. Try the following:
**Trigger the workflow:**
```text theme={null}
"What's the difference between a TFSA and an RRSP?"
```
The agent should route to the Financial Guidance workflow. You should see the disclaimer message followed by the two buttons.
**Accept the disclaimer:**
Click "I agree". The Explore Finances playbook should take over and start a conversation about your financial question. Try asking follow-up questions to see the playbook navigate the conversation.
**Decline the disclaimer:**
This time, open the **Agent** tab and press the **Run** button in the top right of that tab. This will allow you to fully test whether the workflow passes control back to the Agent after the user fails to agree to the terms and conditions.
Ask the same question as before - `"What's the difference between a TFSA and an RRSP?"` , but this time click **I don't agree**. The Agent will switch to the financial guidance workflow and you should see the acknowledgment message, and then be returned to the agent. Then, try asking a non-financial question to confirm the agent is back in control: `Tell me about NestEgg`. You'll see that this question is still answered using the **Explain NestEgg** playbook, as this doesn't require the terms to be accepted.
## Tips for building workflows
* **Use workflows for things that must happen in order.** Legal disclaimers, identity verification, onboarding checklists. Anywhere you need guaranteed steps in a guaranteed sequence, use a workflow. If the conversation can be flexible, use a [playbook](/documentation/build/playbooks) instead.
* **Embed playbooks for flexible moments.** The Explore Finances playbook inside this workflow is a good example. The disclaimer and button choice are deterministic. They happen the same way every time. But the financial conversation afterward is open-ended, so a playbook handles it. This pattern is useful any time you need a controlled entry point followed by a free-form conversation.
* **Leave output ports unconnected to return to the agent.** When a step in a workflow has an empty output port, control passes back to your agent. You don't need to explicitly route back, just leave the port empty.
* **Remember the user's agreement with variables.** Right now, the disclaimer appears every time the workflow runs. In a production agent, you could use a [set step](/documentation/build/steps/set) to save a [variable](/documentation/build/data/variables) like `{disclaimer_accepted}` after the user agrees, and a [condition step](/documentation/build/steps/condition) at the start of the workflow to skip the disclaimer if it's already been accepted.
## What's next?
You've built your first workflow with a deterministic disclaimer flow and an embedded playbook. Explore these resources to go deeper.
Learn about all the steps available in workflows, nesting workflows, and more.
Write better playbook instructions, configure exit conditions, and add tools.
# Chat agent quick start guide
Source: https://docs.voiceflow.com/courses/chat-agent-quick-start
Build and launch your first chat agent in 3 minutes or less.
Create, configure, and publish your first chat agent on Voiceflow. No coding required.
From the [Dashboard](https://creator.voiceflow.com), go to **Projects** → **New project**. Name your project, keep the default settings, and select **Start from scratch**.
This opens the global agent view, where you'll configure your agent's high-level behavior.
In the **Global agent** description, click **generate** and describe your agent's actions, goals, and personality. Voiceflow will automatically create a detailed prompt in seconds.
For example:
```text theme={null}
You are Alex, a friendly customer support agent for AcmeCorp.
Help customers with orders, returns, billing, and product questions.
Be concise, empathetic, and professional. If you can't resolve an
issue, offer to create a support ticket.
```
To give your agent real information to reference, click the **Knowledge Base** icon in the left sidebar. You can add context by:
* **Uploading documents** - PDFs, text files, or CSVs (e.g., your FAQ, product catalog, or return policy).
* **Pasting a URL** - Your agent will index the content directly from the page.
* **Adding text manually** - Paste in key information directly.
Your agent will use this knowledge to answer questions accurately.
Back in the **Agent** tab, click **Publish** in the top-right corner. Your agent is now ready to use!
That's it! Your agent is now deployed and available to use. Try it out using the widget in the bottom-right corner of the editor.
## Tips for refining your chat agent
* **Start simple.** Get a basic agent working first, then layer on complexity. You can add deterministic [Workflow](/documentation/build/workflows) steps and agentic [Playbooks](/documentation/build/playbooks) to get the most out of your agent.
* **Use your knowledge base.** The more relevant content you upload, the more accurate your agent's responses will be.
* **Iterate on your prompt.** Small tweaks to the system prompt can make a big difference in response quality.
## What's next?
You've built your first chat agent on Voiceflow. Now learn how to build production-grade agents with our documentation.
Complete specialized tasks using AI.
Add logic and determinism to your agent.
/
# Tutorials
Source: https://docs.voiceflow.com/courses/home
Learn how to build powerful, production-ready AI agents using Voiceflow.
## Get started
Build and deploy your first chat AI agent in 3 minutes or less.
Build and deploy your first voice AI agent in 3 minutes or less.
## Improve your agent
Create a deterministic flow with a disclaimer, buttons, and an embedded playbook.
Connect your agent to third-party tools so it can interact with the outside world.
Create a support agent grounded in FAQ data from your knowledge base.
Serve different content to different user types using metadata filtering.
Create a deterministic flow with a disclaimer, buttons, and an embedded playbook.
Gate your agent behind identity verification using an initialization workflow, playbooks, and API calls.
## Migrate
Discover how to migrate your Voiceflow v4 project to the new environments system, featuring branching, A/B tests, and more.
# Build an authentication workflow
Source: https://docs.voiceflow.com/courses/initialization-workflow
Gate your agent behind identity verification using an initialization workflow, playbooks, and API calls.
An [initialization workflow](/documentation/build/framework/initialization-workflow) runs automatically at the start of every conversation, before the agent takes control. It gives you a deterministic space to handle setup like loading user data, verifying identity, or collecting required information. Once the workflow completes, control passes to your agent and the conversation continues normally.
In this tutorial, you'll build an initialization workflow for GoRoute, a fictional ride-sharing and delivery platform. Before the agent can help a user, the workflow will collect their email and PIN, validate the credentials against an API, and only let the conversation continue once authentication succeeds. This should take about 10 minutes.
Open the GoRoute support template below, choose a workspace to import it to, and click **Import** to add it to your workspace. Then, open the project.
Pre-configured GoRoute support agent with playbooks and knowledge base content.
The template comes pre-configured with a global prompt, instructions, knowledge base content, and playbooks for GoRoute's driver and courier support. It also includes a pre-built **GoRoute authenticator** [API tool](/documentation/build/tools/api-tool) that validates user credentials against the GoRoute API. You'll build an authentication layer on top of this so the agent knows who it's talking to before answering any questions.
Open the **Framework** tab in the sidebar and click **Add workflow** on the initialization node, then **Create workflow**. Name it "Authentication" and set the **Trigger** to:
```text theme={null}
Authenticates the user by collecting their email and PIN before allowing access to the agent.
```
Click **Create workflow**. To open the workflow on the canvas, click the pencil icon next to its name.
Drag a [**Playbook** step](/documentation/build/steps/playbook) onto the canvas and connect it to the Start chip. Click on the step, select **New playbook**, and name it "Authenticate user".
Set the **Trigger** to:
```text theme={null}
Collects the user's email address and 4-digit PIN code for authentication.
```
Click **Create playbook**. In the playbook editor, write the following **instructions**:
```text theme={null}
# Goal
Collect the user's email address and 4-digit PIN code so they can be authenticated against the GoRoute system.
# Steps
1. Check the conversation history. If this is the start of the conversation, greet the user and let them know you need to verify their identity before you can help. If the user has already attempted to log in and been sent back, let them know the credentials didn't match and ask them to try again.
2. Ask for their email address associated with their GoRoute account.
3. Once you have the email, ask for their 4-digit PIN code.
4. As soon as you have both values, use the GoRoute authenticator tool to validate their credentials.
5. If the tool returns the user's account details, use the User is authenticated tool to exit.
6. If the tool returns an error, let the user know the credentials didn't match and start again from step 2.
# Important
- Do not accept anything other than an email format for the email field.
- The PIN must be exactly 4 digits.
- If the user provides both email and PIN in a single message, accept them both.
- Never repeat the user's email or PIN back to them.
- Do not send a confirmation message after successful authentication. Call the User is authenticated tool immediately.
```
In the **Tools** panel on the right side of the playbook editor, click **+** next to **Tools**, then **API** to filter to API tools. Select **GoRoute authenticator**. This [API tool](/documentation/build/tools/api-tool) is already configured in the template and sends the user's email and PIN to the GoRoute API. It returns their account details on success, or an error if the credentials are invalid.
Once added, you'll see it listed under **Tools**. Click on it to inspect its configuration. The tool has two input variables, `email` and `pin`, both set to **Agent collect**. This means the playbook will automatically collect these values from the conversation and pass them into the tool.
The GoRoute authenticator API tool is included for this tutorial. In your own projects, you can create an [API tool](/documentation/build/tools/api-tool) that connects to your own authentication API. Click the pencil icon next to **GoRoute authenticator** to see how this one is set up, or [view the full documentation for the demo API here](https://goroute.demo.voiceflow.com/docs).
You need to save the user's account details from a successful API call so the agent can use them later.
Click on the **GoRoute authenticator** tool and press **▶** next to the **Capture response** option. Enter `james.wilson@example.com` for email and `1234` for pin, then click **Run**. You should see a `200 OK` response with a `data` object containing the user's account details.
Click on `data` in the response preview and create a new variable by clicking **Create variable**. Name it `user_data` and set the description to:
```text theme={null}
Information about the current user, such as their name and account type.
```
Then, click **Create variable**. You should now see `data → user_data` listed under **Capture response**. This means the user's account details (name, account type, and more) will be automatically saved to the `{user_data}` [variable](/documentation/build/data/variables) whenever the API call succeeds.
When the credentials are invalid, the API response does not contain a `data` key, so `{user_data}` stays empty. You'll use this in the next step to make sure the playbook can only exit after a successful authentication.
In the **Exit conditions** panel on the right side of the playbook editor, click **+** to add a new exit condition. Name it "User is authenticated" and set the **Trigger** to:
```text theme={null}
The user has provided valid credentials and their account details have been successfully retrieved.
```
Then add `{user_data}` as a **required variable** on this exit condition. Because `{user_data}` only gets populated after a successful API call, the playbook can't exit until the user provides valid credentials. If authentication fails, `{user_data}` stays empty and the playbook keeps the conversation going.
Close the playbook editor to return to the canvas. You'll see "User is authenticated" appear as a connection point on the Playbook step.
Connect the "User is authenticated" exit to a [**Message** step](/documentation/build/steps/message). Set the Message step's text to the following:
```text theme={null}
You were successfully authenticated! Please note that all conversations with GoRoute support are logged so that we can serve you better.
```
Leave the Message step's output port unconnected. This passes control to the [agent](/documentation/build/global-prompt) after the message is sent.
This workflow sends a simple message after authentication, but you could chain on additional logic here. For example, use a [Set step](/documentation/build/steps/set) to extract fields from `{user_data}` into individual variables, route to another playbook for onboarding questions, or make additional API calls to preload the user's recent activity.
Go back to the **Agent** tab, then click **Run** in the top-right corner to test your agent. The initialization workflow will start automatically.
**Test with invalid credentials:**
Try entering a wrong PIN or a non-existent email. The playbook should let you know the credentials didn't match and ask you to try again, without leaving the playbook.
**Test with valid credentials:**
Use any of the test accounts below:
| Email | PIN | Name |
| -------------------------- | ------ | ------------ |
| `james.wilson@example.com` | `1234` | James Wilson |
| `mei.chen@example.com` | `5678` | Mei Chen |
| `oliver.brown@example.com` | `9012` | Oliver Brown |
The playbook should ask for your email and PIN, call the API to validate them, and then show the success message before handing off to the agent.
**Test the authenticated agent:**
After successful authentication, try asking a question like "What are the vehicle requirements to drive with GoRoute?" If you authenticated as James Wilson (a driver), the agent should route to the driver support playbook and answer using driver-specific content.
You run the agent from the **Agent** tab rather than from the workflow's canvas so you can see the initialization workflow in action. If you run the workflow from the canvas, only the workflow will run - the agent won't continue after the user authenticates.
## Tips for building authentication workflows
* **The playbook handles the retry loop.** The playbook manages the entire authentication conversation, including retries. If the API returns an error, the playbook tells the user and asks them to try again. This keeps the workflow canvas simple.
* **Use API tools for authentication.** The GoRoute authenticator is an [API tool](/documentation/build/tools/api-tool) that sends credentials to an external API. You can create your own API tools to connect to any authentication system.
* **Capture response data for later.** The API tool saves the response to `{user_data}`, which your agent can reference in its global prompt and instructions to personalize the conversation.
* **Initialization workflows run before the agent.** Anything you put in the initialization workflow happens before the agent sees any messages. This is useful for gating access, loading context, or sending a static greeting.
* **Automate some of these steps.** In the real world, you can pass variables directly into the conversation [through the chat widget](/documentation/deploy/widget/web-chat-api), or automatically detect a user's phone number using the `user_id` variable.
## What's next?
You've built an initialization workflow that authenticates users before the agent takes over. Explore these resources to go deeper.
Learn more about initialization workflows and common patterns like loading context, static greetings, and onboarding flows.
Create custom API tools to connect your agent to any external service.
# Integrate with third-party tools
Source: https://docs.voiceflow.com/courses/integrate-with-third-party-tools
Connect your agent with the outside world in 5 minutes.
Voiceflow's tools let you connect your agent to external services so it can take real-world actions during a conversation. This guide walks you through a complete integration using the [Gmail tool](/documentation/build/tools/gmail-tool), which you can use to automatically send emails directly from your agent.
### What can integrating tools be used for?
Voiceflow offers the option to link other softwares (ie. Gmail, Excel, etc.) to your agent in a couple of simple steps. For example, you want your agent to send an email? Integrate the Gmail tool and it can do that!
In a new project or an existing one, open the [Agent](/documentation/build/global-prompt) tab. Make sure your agent has a global prompt that defines its overall behaviour and purpose. If this is your first time setting up an agent, [visit our getting started guide](/courses/chat-agent-quick-start) before continuing.
Create a new [playbook](/documentation/build/playbooks) and title it "Send summary email". In the playbook's **Trigger**, describe its purpose so the agent knows when to invoke it.
For this integration, your playbook will need to collect an `{email_address}` from the user to send emails to. Use the example prompt below as a starting point for your "Send summary email" playbook.
```text theme={null}
Your goal is to wrap up the conversation by sending the user a summary of what was discussed over email.
**Steps:**
1. Ask the user for their email address in a friendly way (eg: "Before I send that over, could I grab your email address?")
2. Store it as {email_address}
3. Confirm the address back to the user before sending
```
Inside your playbook, add the Gmail tool. Select **Connect** → **Connect**, then choose your Gmail account. Once connected, select **Send email** as the action.
In the tool's **Trigger**, describe what you want the tool to send (eg: a summary of the conversation sent to `{email_address}`). Use the example below as a reference.
Send a friendly summary email to email\_address. The subject line should be "Here's a summary of our conversation". In the body, write a short, warm recap of the key points discussed, any actions the user said they'd take, and anything you agreed to follow up on. Keep it concise and easy to skim.
```text theme={null}
Send a summary email to {email_address} with the following:
**To:** {email_address}
**Subject:** Here's a summary of our conversation
**Body:**
- A short, warm intro (1-2 sentences)
- Key points discussed
- Any actions the user said they'd take
- Anything you agreed to follow up on
Keep it concise and easy to skim.
```
Open **Agent** → **Publish** in the top-right corner. Your agent is now live and can automatically send emails from your connected Gmail account!
## What's next?
Now that you've connected your first integration, you're ready to explore all the tools available for your agent.
All of Voiceflow's officially supported integrations.
Want to connect to another service? You can use the [API tool](/documentation/build/tools/api-tool) in a playbook or the [API step](/documentation/build/steps/api) in a workflow to connect to any external API.
# Migrate to environments
Source: https://docs.voiceflow.com/courses/migrate-to-environments
Switch from our legacy environments system to our new, more powerful version.
In April 2026, Voiceflow released a new [environments](/documentation/deploy/environments) system that replaces the fixed `development`, `staging` , and `production` environments with a flexible, branchable model. Every project now starts with a single environment called `main`, and you can create more whenever you want to test a change in isolation, compare two versions of your agent against each other, or roll out a new version gradually.
Existing projects keep working the way they always have, with the original `development`, `staging` and `production` environments, until you opt in to migrate. Once you migrate a project, the legacy `development`, `staging`, and `production` aliases stop working, so you'll need to update any integration that points at them. Most projects take a couple of minutes to update.
Migrating without updating your integrations will break your live agent for users. Update every integration that uses the legacy aliases before, or immediately after, you migrate.
## Update the chat widget
If you've embedded the chat widget on your website, replace your snippet with the new default below (don't forget to fill in your project's ID). The new snippet doesn't include `versionID`, which means the widget routes each new session according to the [traffic split](/documentation/deploy/environments/traffic-split) configured in **Settings** → **Environments**. For most projects, this is exactly what you want: it automatically respects A/B tests and gradual rollouts.
```javascript theme={null}
```
You can also find your project's code snippet in the **Widget** tab.
If you'd rather pin the widget to a specific environment (for example, to load a non-production environment on a staging site), set `versionID` to that environment's alias. See our [chat widget API documentation](/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads) for more information.
## Update your Conversations API calls
If you're calling the [Conversations API](/api-reference/conversations-api/overview) directly, update any request that passes `environment: 'production'` by choose one of these options:
* Updating it to use `environment: 'main'` instead.
* Using the [traffic split](https://docs.voiceflow.com/documentation/deploy/environments/traffic-split) feature by migrating to the new [start session](/api-reference/v4interact/start-session-with-traffic-split) and [interact](/api-reference/v4interact/interact-stream) endpoints. This is a more intensive process than switching the environment to `main`, but will give you the ability to A/B test changes prior to release.
For requests that pass `'staging'` or `'development'`, choose whichever option fits best:
* Point them at `'main'` to keep using the same default.
* Point them at a new environment you create for staging or development work.
## Migrate your project
Once your integrations are ready, open **Settings** → **General** in your project and scroll to the **Danger zone** section. Click **Migrate** next to **Migrate to environments** to switch your project over.
![Migration]()
## After you migrate
Your agent keeps serving users from `main` by default. Now you can:
* [Iterate without disturbing live traffic](/documentation/deploy/environments) by cloning `main` into a new environment and editing freely.
* [Split traffic](/documentation/deploy/environments/traffic-split) across environments to A/B test a change against `main` on real conversations.
* [Compare versions side by side](/documentation/deploy/environments/publishing#version-history-and-reverting) and revert, clone, or [merge](/documentation/deploy/environments/merging) from any point in history.
# Voice agent quick start guide
Source: https://docs.voiceflow.com/courses/phone-agent-quick-start
Build and launch your first voice agent in 3 minutes or less.
Create, configure, and call your first voice agent on Voiceflow. No coding required.
From the [Dashboard](https://creator.voiceflow.com), go to **Projects** → **New project**. Name your project, set the type to **Voice**, and select **Start from scratch**.
This opens the global agent view, where you'll configure your agent's high-level behavior.
In the **Global agent** description, click **generate** and describe your agent's actions, goals, and personality. You can also customize the agent's tone, speed, and how long it waits for a user to reply. Voiceflow will automatically create a detailed prompt in seconds.
For example:
```text theme={null}
You are Alex, a calm and friendly voice support agent for AcmeCorp.
Help customers with orders, returns, billing, and product questions.
Speak naturally in short, conversational sentences — avoid long
lists or complex phrasing. Stay warm, patient, and reassuring.
If you can't resolve an issue, offer to create a support ticket.
```
To give your agent real information to reference, click the **Knowledge Base** icon in the left sidebar. You can add context by:
* **Uploading documents** - PDFs, text files, or CSVs (e.g., your FAQ, product catalog, or return policy).
* **Pasting a URL** - Your agent will index the content directly from the page.
* **Adding text manually** - Paste in key information directly.
Your agent will use this knowledge to answer questions accurately.
Back in the **Agent** tab, click **Publish** in the top-right corner. To receive a call from your agent, click **Call** in the top-right, enter your phone number, and start speaking with your agent!
That's it! Your agent is now deployed and available to use.
## Tips for refining your voice agent
* **Start simple.** Get a basic agent working first, then layer on complexity. You can add deterministic [Workflows](/documentation/build/workflows) and agentic [Playbooks](/documentation/build/playbooks) to get the most out of your agent.
* **Use your knowledge base.** The more relevant content you upload, the more accurate your agent's responses will be.
* **Iterate on your prompt.** Small tweaks to the system prompt can make a big difference in response quality.
* **Set up a phone number.** [Configure a dedicated number](/documentation/deploy/phone/connect-a-phone-number) so your agent can be reached by simply dialing in.
## What's next?
You've built your first voice agent on Voiceflow. Now learn how to build production-grade agents with our documentation.
Complete specialized tasks using AI.
Add logic and determinism to your agent.
# Build a simple FAQ agent
Source: https://docs.voiceflow.com/courses/simple-knowledge-base
Create a support agent grounded in FAQ data from your knowledge base.
In this tutorial, you will build a customer support agent for a fictional enterprise software company called NovaTech. Your agent will answer common support questions using FAQ data stored in the knowledge base. This should take about 5 minutes.
From the [Dashboard](https://creator.voiceflow.com), go to **Projects** → **New project**. Name your project "NovaTech Support", set the type to **Chat**, and select **Start from scratch**.
This opens the global agent view, where you'll configure your agent's high-level behaviour.
Download the sample CSV below and upload it to get started. It contains 50 FAQ entries across Account, Billing, Technical, Features, and General categories.
50 sample FAQ entries for the NovaTech support agent.
To upload the CSV to your knowledge base, click **Knowledge Base** in the left sidebar, then **Add data sources**. Select **Table** and upload the CSV file containing NovaTech's support FAQs.
Each row in the CSV becomes a separate chunk, and column headers become field names. This makes it easy for the agent to find the right answer for a given question.
Click the **Agent** tab. You'll configure two things here: the **Global prompt** and the **Instructions**. The global prompt defines your agent's personality and applies to every turn. Instructions tell the agent how to handle different types of requests.
In the **Global prompt** section, define your agent's identity:
```text theme={null}
# Personality
You are a friendly and efficient support agent for NovaTech, an enterprise software platform. You help customers resolve issues quickly and clearly.
# Tone
Warm, professional, and concise. Avoid jargon. Speak like a helpful colleague, not a robot.
# Guardrails
Only provide information grounded in the knowledge base. Never guess at steps, settings, or policies. If you're unsure, say so honestly rather than making something up.
```
Then in the **Instructions** field, tell the agent how to handle incoming questions:
```text theme={null}
Always search the knowledge base before answering a question. Use the information you find to give a clear, step-by-step response.
If the knowledge base doesn't have a relevant answer, let the customer know honestly and offer to connect them with the NovaTech support team.
Do not answer questions that are unrelated to NovaTech.
```
Make sure the **Knowledge base** toggle is enabled under **System tools**. This lets your agent automatically search the FAQ data when answering questions.
Click **Run** in the top-right corner to test your agent. Try prompts like:
* *"How do I add someone to my team?"*
* *"My dashboard is super slow, what's going on?"*
* *"I need to set up 2FA on my account"*
* *"How do I schedule a report?"*
Your agent will search the knowledge base and respond with the relevant FAQ answer. If a question doesn't match anything in the CSV, the agent should let the user know that it couldn't find information about their query rather than making up information.
## Tips for refining your agent
* **Expand your FAQ data.** The more Q\&A pairs in your CSV, the more questions your agent can handle accurately. Add rows as you discover common support requests.
* **Iterate on your prompt.** Small tweaks to the global prompt can make a big difference. Try adjusting the tone or adding specific guardrails based on what you see in testing.
* **Layer on complexity.** Once the basics work, you can add [playbooks](/documentation/build/playbooks) for specific support scenarios (eg: guided troubleshooting, billing disputes) and use [system tools](/documentation/build/tools/system-tools) like Cards or Buttons to make responses more interactive.
## What's next?
Now you've built your first support agent, you're ready to learn about Voiceflow's advanced knowledge base functionality.
Learn how to use website importing, metadata filtering, the knowledge base tool inside playbooks, and more.
# Developer tools overview
Source: https://docs.voiceflow.com/developer-tools/developer-tools-overview
Manage and test your agents programmatically.
Voiceflow's developer tools help you test, debug, and manage your agents outside of the visual builder. Whether you prefer working in a terminal or need to automate testing as part of your CI/CD pipeline, these tools give you programmatic access to your agents and their data.
The Voiceflow CLI lets you interact with your agents from the command line. You can run conversations, manage knowledge base documents, export transcripts, and more. The Test Platform provides a web-based interface for creating and scheduling automated test suites to validate your agent's behavior.
## Developer tools
Interact with your agents, manage documents, and export data from the command line.
Create automated test suites and schedule recurring tests to validate agent behavior.
# Voiceflow CLI overview
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli
Command-line tool for testing, managing, and automating your Voiceflow agents.
`voiceflow-cli` is a command-line tool that helps Voiceflow users test their agents and interact with them in various ways.\
It is useful for your day-to-day tasks or if you want to integrate it with your favorite CI tool.
## Get started
* [How to install the tool](/developer-tools/voiceflow-cli/overview/cli-install)
* [Authentication](/api-reference/authentication)
* [Read the FAQ](/developer-tools/voiceflow-cli/overview/faq)
# Export agent information
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/agent/export
Export your Voiceflow agent configuration and data as .vf files.
With the `voiceflow-cli` you can export your agent information. This is useful when you want to get the `.vf` file of your project. The `voiceflow-cli` has one command that allows you to export an agent from your terminal:
To export an agent, you need to know the `agent-id` and the `version-id` of the agent you want to export from. You can find that information in the Voiceflow Agent section under your Agent Settings on [voiceflow.com](https://voiceflow.com).
```sh theme={null}
voiceflow agent export --agent-id --version-id --output-file
```
# Agent
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/agent/index
Interact with and manage your Voiceflow agents from the command line.
## What is this?
A Voiceflow agent is a conversational AI that can be used to create voice and chat applications. It is a collection of conversational components that are used to create a conversational flow. The agent can be used to create voice and chat applications that can be used to interact with users.
## Reference
The `voiceflow-cli` has a command that allows you to interact with your Voiceflow Agents from your terminal or from your CI pipelines.
To know more, you can run the `voiceflow agent` command. For the usage, please refer to this [page](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-agent).
# Fetch analytics
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/analytics/fetch
Export your agent's analytics data with customizable filters and options.
With the `voiceflow-cli` you can fetch the analytics of your project. This is useful when you want to get the get the analytics and import them to another system. The `voiceflow-cli` has one command that allows you to export your voiceflow agent Analytics from your terminal:
To export the analytics, you need to know the `agent-id` of the agent you want to export from. You can find that information in the Voiceflow Agent section under your Agent Settings on [voiceflow.com](https://voiceflow.com).
```sh theme={null}
voiceflow analytics fetch --agent-id --output-file
```
### Filters
The Voiceflow analytics command has a few filters that you can use to narrow down the data you want to export. The filters are:
#### Time Range
* Start Time
* Flag: `--start-time, -s`
* Format: ISO-8601
* Default: Current day minus one month
* Example: `--start-time 2025-01-01T00:00:00.000Z`
* End Time
* Flag: `--end-time, -s`
* Format: ISO-8601
* Default: Current day
* Example: `--end-time 2025-01-02T00:00:00.000Z`
#### Limit
* Flag: `--limit, -l`
* Description: Maximum number of records to fetch
* Default: 100
* Example: `--limit 500`
#### Output File
* Flag: `--output-file, -d`
* Description: Path where analytics will be saved
* Default: `analytics.json`
* Example: `--output-file my-analytics.json`
#### Analytics Types
* Flag: `--analytics, -t`
* Description: Types of analytics to fetch
* Default: All types listed below
* Multiple values allowed: Yes
| Analytics Type | Description |
| --------------------- | ---------------------------- |
| `interactions` | User interaction data |
| `sessions` | Session-level analytics |
| `top_intents` | Most triggered intents |
| `top_slots` | Most used slots |
| `understood_messages` | Successfully parsed messages |
| `unique_users` | Distinct user counts |
| `token_usage` | API token consumption |
## Example Usage
```bash theme={null}
voiceflow analytics fetch \
--agent-id abc123 \
--start-time 2025-01-01T00:00:00.000Z \
--end-time 2025-01-02T00:00:00.000Z \
--limit 500 \
--analytics interactions,sessions \
--output-file jan-2024-analytics.json
```
# Analytics
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/analytics/index
Access and analyze your agent's performance metrics, from your terminal.
## What is this?
Voiceflow agents' analytics provide insights into how your users are interacting with your voice and chat applications. It helps you understand how your users are interacting with your application, what intents they are hitting, and where they are dropping off.
## Reference
The `voiceflow-cli` has a command that allows you to interact with your Voiceflow Agents' analytics from your terminal or from your CI pipelines.
To know more, you can run the `voiceflow analytics` command. For the usage, please refer to this [page](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-analytics).
# API endpoints
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/api-serve/api-endpoints
Reference documentation for all Voiceflow CLI API server endpoints.
## Health Check
```http theme={null}
GET /health
```
Returns the health status of the server.
## Execute Test Suite
```http theme={null}
POST /api/v1/tests/execute
Content-Type: application/json
{
"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"
}
]
}
}
]
}
}
]
}
}
```
**Response:**
```json theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "running",
"started_at": "2023-01-01T00:00:00Z",
"logs": ["Test execution started"]
}
```
Executes a test suite asynchronously and returns an execution ID for tracking. The suite configuration and tests are now embedded directly in the request body, making the API more HTTP-friendly and eliminating the need for file system access.
### Request Parameters
* `api_key` (optional): Override the global Voiceflow API key for this specific test execution
* `voiceflow_subdomain` (optional): Override the global Voiceflow subdomain for this specific test execution. This allows you to test against different Voiceflow environments or custom subdomains without affecting the global configuration
* `suite`: The test suite configuration containing the test definitions
### Using Custom Subdomains
When you specify a `voiceflow_subdomain`, the API will use that subdomain for all interactions in the test suite. For example:
* If you set `"voiceflow_subdomain": "my-custom-env"`, requests will be sent to `https://general-runtime.my-custom-env.voiceflow.com`
* If you omit this field, the global subdomain configuration will be used
* This is particularly useful for testing against staging environments or customer-specific deployments
## Get Test Status
```http theme={null}
GET /api/v1/tests/status/{execution_id}
```
**Response:**
```json theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"started_at": "2023-01-01T00:00:00Z",
"completed_at": "2023-01-01T00:05:00Z",
"logs": [
"Starting test suite execution...",
"Running Test ID: example_test",
"Test suite execution completed successfully"
]
}
```
Retrieves the current status and logs of a test execution.
## System Information
```http theme={null}
GET /api/v1/system/info
```
**Response:**
```json theme={null}
{
"version": "1.0.0",
"go_version": "go1.20.0",
"os": "linux",
"arch": "amd64"
}
```
Returns system information about the running server instance.
## OpenAPI/Swagger Documentation
Once the server is running, you can access the interactive API documentation at:
```
http://localhost:8080/swagger/index.html
```
```
http://localhost:8080/swagger/index.html
```
# API server
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/api-serve/index
Run a local HTTP API server to execute tests via REST endpoints.
# API Server Introduction
The Voiceflow CLI now includes an HTTP API server that exposes test execution functionality as REST endpoints with auto-generated OpenAPI/Swagger documentation.
## Features
* **HTTP API**: Execute test suites via REST endpoints
* **Real-time Logging**: Capture and return test execution logs in API responses
* **OpenAPI/Swagger**: Auto-generated API documentation at `/swagger/index.html`
* **Asynchronous Execution**: Non-blocking test execution with status tracking
* **CORS Support**: Enable cross-origin requests for web frontends
* **Health Checks**: Built-in health check endpoints
## OpenAPI Specifications
The server provides OpenAPI specifications in both YAML and JSON formats:
* **YAML Format**: Available at [`/static/swagger.yaml`](https://voiceflow.xavidop.me/static/swagger.yaml)
* **JSON Format**: Available at [`/static/swagger.json`](https://voiceflow.xavidop.me/static/swagger.json)
These specifications can be used to generate client libraries, import into API testing tools, or integrate with other OpenAPI-compatible tooling.
## Starting the Server
### Basic Usage
```bash theme={null}
# Start server on default port (8080)
voiceflow server
# Start server on custom port
voiceflow server --port 9090
# Start server with debug mode
voiceflow server --debug
# Start server with custom host
voiceflow server --host 127.0.0.1 --port 8080
```
### Command Line Options
| Flag | Short | Default | Description |
| ----------- | ----- | --------- | ------------------------------------- |
| `--port` | `-p` | `8080` | Port to run the server on |
| `--host` | `-H` | `0.0.0.0` | Host to bind the server to |
| `--debug` | `-d` | `false` | Enable debug mode |
| `--cors` | | `true` | Enable CORS middleware |
| `--swagger` | | `true` | Enable Swagger documentation endpoint |
## Configuration
### Environment Variables
The server respects all existing Voiceflow CLI environment variables:
* `VF_API_KEY`: Voiceflow API Key (from the Settings tab)
* `OPENAI_API_KEY`: OpenAI API Key (for similarity validations)
### CORS Configuration
CORS is enabled by default. To disable CORS:
```bash theme={null}
voiceflow server --cors=false
```
### Debug Mode
Enable debug mode for detailed logging:
```bash theme={null}
voiceflow server --debug
```
# Public instance
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/api-serve/public-instance
Try the Voiceflow CLI API server online, without local setup.
# Public Instance
## Try the Voiceflow CLI Server Online
If you want to try out the Voiceflow CLI server without setting it up locally, you can use our public instance:
**Base URL:** [https://tests-api.voiceflow.com/](https://tests-api.voiceflow.com/)
## Interactive API Documentation
You can explore and test the API endpoints directly in your browser using our Swagger playground:
[API Docs](/api-reference/api-overview)
The Swagger interface allows you to:
* View all available API endpoints
* See request/response schemas
* Test API calls directly from your browser
* Download API specifications
## Getting Started
1. Visit the [Swagger playground](https://docs.voiceflow.com/reference/post_api-v1-tests-execute#/)
2. Explore the available endpoints
3. Try out the API calls with your own data
4. Use the examples from the [usage examples](/developer-tools/voiceflow-cli/api-serve/usage-examples) by replacing `http://localhost:8080` with `https://voiceflow-cli-api.xavidop.me`
# Security and troubleshooting
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/api-serve/security-troubleshooting
Secure your API server and resolve deployment issues.
## Security Considerations
* **Network Binding**: The server runs on all interfaces (`0.0.0.0`) by default. In production environments, consider binding to specific interfaces using the `--host` flag.
* **Authentication**: There is no built-in authentication mechanism. For production deployments, consider adding a reverse proxy with authentication if needed.
* **Data Storage**: Test executions are stored in memory only. Consider implementing persistent storage solutions for production use cases.
* **CORS**: Cross-Origin Resource Sharing (CORS) is enabled by default. You can disable it using `--cors=false` if not needed.
## Troubleshooting
### Server Won't Start
**Problem**: Server fails to start or reports port binding errors.
**Solutions**:
1. Check if the port is already in use:
```bash theme={null}
lsof -i :8080
```
2. Try a different port:
```bash theme={null}
voiceflow server --port 9090
```
3. Check if you have permission to bind to the port (especially for ports \< 1024):
```bash theme={null}
sudo voiceflow server --port 80
```
### API Returns 404
**Problem**: API endpoints return 404 Not Found errors.
**Solutions**:
1. Ensure you're using the correct base path `/api/v1/` for API endpoints
2. Verify the server is running and accessible
3. Check the server logs for any startup errors
### Logs Not Appearing
**Problem**: Test execution logs are not visible or incomplete.
**Solutions**:
1. Enable debug mode to see more detailed logging:
```bash theme={null}
voiceflow server --debug
```
2. Verify that environment variables (VF\_API\_KEY, etc.) are properly set or the api key is provided in the request is correct
### Connection Refused Errors
**Problem**: Cannot connect to the server from external clients.
**Solutions**:
1. Verify the server is bound to the correct interface:
```bash theme={null}
voiceflow server --host 0.0.0.0 --port 8080
```
2. Check firewall settings and ensure the port is open
3. For local testing, try connecting to `127.0.0.1` instead of `localhost`
### High Memory Usage
**Problem**: Server consumes excessive memory during long-running operations.
**Solutions**:
1. Monitor test execution status and clean up completed executions
2. Consider implementing execution cleanup routines
3. Restart the server periodically for long-running deployments
### Swagger Documentation Not Loading
**Problem**: Cannot access Swagger UI at `/swagger/index.html`.
**Solutions**:
1. Ensure Swagger is enabled (it's enabled by default):
```bash theme={null}
voiceflow server --swagger=true
```
2. Try accessing the full URL: `http://localhost:8080/swagger/index.html`
3. Check browser console for JavaScript errors
4. Verify CORS settings if accessing from a different domain
# Usage examples
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/api-serve/usage-examples
Practical examples of using the Voiceflow CLI API server with curl and other tools.
## Using curl
### 1. Start a test execution
```bash theme={null}
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"}]}}]}}]}}'
```
### 1b. Start a test execution with custom subdomain
```bash theme={null}
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"
}
]
}
}
]
}
}
]
}
}'
```
### 2. Check test status
```bash theme={null}
curl http://localhost:8080/api/v1/tests/status/YOUR_EXECUTION_ID
```
### 3. Health check
```bash theme={null}
curl http://localhost:8080/health
```
## Using JavaScript/fetch
```javascript theme={null}
// 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);
}
```
## Using Python requests
```python theme={null}
import requests
import time
# Execute a test suite with custom subdomain
response = requests.post('http://localhost:8080/api/v1/tests/execute', json={
'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'
}
]
}
}
]
}
}
]
}
})
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)
# Example: Testing multiple environments
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']}")
```
```python theme={null}
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)
```
# Agent-to-agent examples
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/automated-testing/agent-to-agent-examples
Real-world examples of agent-to-agent testing scenarios.
## Basic Examples
### Simple Customer Service
```yaml theme={null}
name: Basic Customer Inquiry
description: Test agent's ability to handle simple customer questions
agent:
goal: "Get information about store hours and location"
persona: "A polite customer who needs basic store information"
maxSteps: 8
userInformation:
- name: 'location'
value: 'downtown'
```
### User Account Issue
```yaml theme={null}
name: Account Login Problem
description: Test agent's ability to help with login issues
agent:
goal: "Resolve a login problem and successfully access my account"
persona: "A frustrated user who can't remember their password"
maxSteps: 12
userInformation:
- name: 'email'
value: 'user@example.com'
- name: 'username'
value: 'johndoe123'
- name: 'last_login'
value: '2 weeks ago'
```
## Industry-Specific Examples
### Banking & Financial Services
#### ATM Transaction Support
```yaml theme={null}
name: ATM Transaction Help
description: Test agent's ability to assist with ATM issues
agent:
goal: "Complete a cash withdrawal after card was temporarily blocked"
persona: "An anxious customer whose card stopped working at an ATM"
maxSteps: 15
userInformation:
- name: 'account_number'
value: '1234567890'
- name: 'phone'
value: '555-123-4567'
- name: 'card_last_four'
value: '5678'
- name: 'withdrawal_amount'
value: '200'
- name: 'atm_location'
value: 'Main Street Branch'
```
#### Credit Card Dispute
```yaml theme={null}
name: Credit Card Dispute Resolution
description: Test agent's ability to handle credit card disputes
agent:
goal: "Report an unauthorized charge and request a refund"
persona: "A concerned customer who noticed a fraudulent charge on their statement"
maxSteps: 20
userInformation:
- name: 'card_number'
value: '**** **** **** 1234'
- name: 'dispute_amount'
value: '$89.99'
- name: 'merchant_name'
value: 'Unknown Online Store'
- name: 'transaction_date'
value: 'January 15, 2025'
```
### E-commerce & Retail
#### Product Return
```yaml theme={null}
name: Defective Product Return
description: Test agent's ability to process product returns
agent:
goal: "Return a broken item and get a full refund"
persona: "A disappointed customer who received a damaged product"
maxSteps: 14
userInformation:
- name: 'order_number'
value: 'ORD-789456'
- name: 'email'
value: 'customer@email.com'
- name: 'product_name'
value: 'Bluetooth Wireless Headphones'
- name: 'issue'
value: 'right earbud not working'
- name: 'purchase_date'
value: '2024-12-20'
```
#### Order Tracking
```yaml theme={null}
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'
```
### Healthcare
#### Appointment Scheduling
```yaml theme={null}
name: Urgent Appointment Request
description: Test agent's ability to schedule medical appointments
agent:
goal: "Schedule an urgent appointment with a specialist for recurring symptoms"
persona: "A worried patient experiencing worsening health symptoms"
maxSteps: 18
userInformation:
- name: 'patient_id'
value: 'PAT-789123'
- name: 'insurance_provider'
value: 'Blue Cross Blue Shield'
- name: 'symptoms'
value: 'persistent chest pain and shortness of breath'
- name: 'preferred_doctor'
value: 'Dr. Johnson (Cardiology)'
- name: 'availability'
value: 'weekday afternoons'
```
#### Prescription Refill
```yaml theme={null}
name: Prescription Refill Request
description: Test agent's ability to handle prescription refills
agent:
goal: "Refill my blood pressure medication that's running low"
persona: "An elderly patient who needs help navigating the refill process"
maxSteps: 12
userInformation:
- name: 'prescription_number'
value: 'RX-456789'
- name: 'medication_name'
value: 'Lisinopril 10mg'
- name: 'pharmacy'
value: 'CVS Pharmacy on Oak Street'
- name: 'doctor_name'
value: 'Dr. Smith'
```
### Travel & Hospitality
#### Hotel Booking
```yaml theme={null}
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'
```
#### Flight Change Request
```yaml theme={null}
name: Flight Modification
description: Test agent's ability to handle flight changes
agent:
goal: "Change my flight to an earlier departure due to a schedule conflict"
persona: "A stressed traveler whose meeting was moved up unexpectedly"
maxSteps: 14
userInformation:
- name: 'confirmation_number'
value: 'ABC123'
- name: 'current_flight'
value: 'UA456 departing 6:00 PM'
- name: 'preferred_time'
value: 'morning departure'
- name: 'destination'
value: 'Los Angeles'
- name: 'travel_date'
value: 'January 25, 2025'
```
### Technical Support
#### Software Installation Help
```yaml theme={null}
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'
```
#### Internet Connectivity Issue
```yaml theme={null}
name: Internet Service Problem
description: Test agent's ability to troubleshoot connectivity issues
agent:
goal: "Resolve internet outage and restore service to my home"
persona: "A work-from-home professional whose internet suddenly stopped working"
maxSteps: 18
userInformation:
- name: 'account_number'
value: 'ISP-789456'
- name: 'service_address'
value: '456 Elm Street, Suburb, State'
- name: 'plan_type'
value: 'Business 500 Mbps'
- name: 'equipment'
value: 'Cisco modem and Netgear router'
- name: 'outage_duration'
value: '3 hours'
```
## Complex Scenarios
### Multi-Step Customer Journey
```yaml theme={null}
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'
```
### Crisis Management
```yaml theme={null}
name: Service Outage Communication
description: Test agent's ability to handle service disruption inquiries
agent:
goal: "Get updates about the service outage and estimated restoration time"
persona: "An angry customer whose business is affected by the outage"
maxSteps: 12
userInformation:
- name: 'business_account'
value: 'BIZ-654321'
- name: 'service_type'
value: 'Enterprise Cloud Hosting'
- name: 'affected_services'
value: 'email server and website'
- name: 'business_impact'
value: 'cannot process customer orders'
```
## Personality Variations
### Different Customer Types
#### The Patient Customer
```yaml theme={null}
name: Patient Customer Interaction
description: Test with a calm, understanding customer persona
agent:
goal: "Resolve a billing discrepancy in my monthly statement"
persona: "A patient, polite customer who understands that mistakes happen"
maxSteps: 10
userInformation:
- name: 'account_number'
value: 'ACC-112233'
- name: 'billing_month'
value: 'December 2024'
- name: 'disputed_amount'
value: '$25.99'
```
#### The Urgent Customer
```yaml theme={null}
name: High-Priority Customer Issue
description: Test with a time-sensitive, urgent customer persona
agent:
goal: "Get immediate help with a payment that failed during checkout"
persona: "An urgent customer who needs immediate resolution for a time-sensitive purchase"
maxSteps: 8
userInformation:
- name: 'transaction_id'
value: 'TXN-998877'
- name: 'card_ending'
value: '4567'
- name: 'purchase_amount'
value: '$299.99'
- name: 'deadline'
value: 'need to complete purchase today'
```
#### The Confused Customer
```yaml theme={null}
name: Confused Customer Guidance
description: Test with a customer who needs extra explanation
agent:
goal: "Understand how to use the new mobile app features"
persona: "A confused customer who is not tech-savvy and needs step-by-step guidance"
maxSteps: 16
userInformation:
- name: 'phone_type'
value: 'iPhone 12'
- name: 'app_version'
value: '2.1.0'
- name: 'specific_feature'
value: 'mobile check deposit'
```
## Tips for Effective Agent Tests
### 🎯 Goal Writing Best Practices
* **Be Specific**: Instead of "get help", use "resolve login issue and access account"
* **Include Context**: Mention why the goal is important to the user
* **Make it Measurable**: Define what "success" looks like
### 👤 Persona Development
* **Add Emotion**: Include emotional state (frustrated, confused, urgent)
* **Technical Level**: Specify technical expertise level
* **Background Context**: Provide relevant situational details
### 📊 User Information Strategy
* **Essential Data**: Include information your agent typically needs
* **Realistic Values**: Use believable names, addresses, and IDs
* **Complete Coverage**: Provide all data types your agent might request
### ⚡ Step Optimization
* **Start Conservative**: Begin with fewer steps and increase if needed
* **Monitor Logs**: Check test logs to see actual step usage
* **Buffer for Edge Cases**: Add 20-30% buffer for unexpected paths
These examples demonstrate the flexibility and power of Agent-to-Agent testing across different industries and scenarios. Each test simulates realistic user behavior while working toward specific, measurable goals.
# Agent-to-agent tests reference
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/automated-testing/agent-to-agent-tests
Define agent-to-agent tests for realistic conversation testing.
## Overview
Agent-to-Agent testing is a revolutionary approach to conversation testing that uses AI-powered agents to simulate realistic user interactions with your Voiceflow agent. Instead of predefined scripts, these tests use artificial intelligence to conduct natural, goal-oriented conversations.
There are two types of agent-to-agent testing available:
1. **OpenAI-Powered Testing**: Uses OpenAI models (GPT-4, GPT-3.5, etc.) to simulate user behavior
2. **Voiceflow Agent Testing**: Uses another Voiceflow agent as the tester to interact with your target agent
## How It Works
### OpenAI-Powered Testing Flow
1. **🚀 Initialization**: Two Voiceflow agents are configured - one as the tester and one as the target
2. **💬 Conversation Start**: Both agents are launched simultaneously
3. **🔧 Variable Setup**: Optional variables are set in both agents using the State Variables API
4. **🤖 Agent Interaction**: The tester agent conducts a conversation with your target agent
5. **🎯 Goal Tracking**: OpenAI evaluates whether the specified goal is achieved based on the conversation
6. **✅ Completion**: The test succeeds when the goal is achieved or times out after maximum steps
### Voiceflow Agent-to-Agent Testing Flow
1. **🚀 Initialization**: Two Voiceflow agents are configured - one as the tester and one as the target
2. **💬 Conversation Start**: Both agents are launched simultaneously
3. **🤖 Agent Interaction**: The tester agent conducts a conversation with your target agent
4. **🎯 Goal Tracking**: OpenAI evaluates whether the specified goal is achieved based on the conversation
5. **✅ Completion**: The test succeeds when the goal is achieved or times out after maximum steps
### Key Advantages
* **🎭 Natural Conversations**: AI agents respond like real users, not scripted robots
* **🔄 Multiple Paths**: One test can explore various conversation flows automatically
* **📊 Comprehensive Coverage**: Tests edge cases and unexpected user behaviors
* **⚡ Efficient**: Replaces dozens of traditional tests with one adaptive test
* **🎯 Goal-Focused**: Measures success based on outcomes, not exact responses
* **🤖 Dual Testing Modes**: Choose between OpenAI-powered testing or Voiceflow agent testing based on your needs
## Test Configuration
### OpenAI-Powered Testing Structure
```yaml theme={null}
name: Customer Support Agent Test
description: Test agent's ability to resolve customer issues
agent:
goal: "Get help with a billing issue and update my account information"
persona: "A confused customer who received an unexpected charge on their account"
maxSteps: 20
userInformation:
- name: 'email'
value: 'john.doe@example.com'
- name: 'account_number'
value: 'ACC-123456'
- name: 'phone'
value: '555-0123'
openAIConfig:
model: gpt-4o
temperature: 0.7
```
### Voiceflow Agent-to-Agent Testing Structure
```yaml theme={null}
name: Customer Support Agent Test
description: Test using a Voiceflow agent as the tester
agent:
goal: "Get help with a billing issue and update account information"
maxSteps: 15
# OpenAI config is still used for goal evaluation
openAIConfig:
model: gpt-4o
temperature: 0.3
# Optional: Variables to set in the target agent being tested after launch
# Note: Target agent variables are only set when newSessionPerTest is enabled in the suite
voiceflowAgentTargetConfig:
variables:
service_list: "basic, premium, enterprise"
greeting_message: "Welcome to our service! How can I assist you today?"
voiceflowAgentTesterConfig:
environmentName: "production" # Environment of the tester agent
apiKey: "VF.DM.your-tester-agent-api-key"
# Note: userInformation is not used with Voiceflow agent testing
# The tester agent should be pre-configured with any needed information
# Optional: Set variables in the tester agent
variables:
user_name: "John Doe"
user_id: "12345"
booking_type: "hotel"
check_in_date: "2026-02-15"
```
### Configuration Properties
#### `goal` (Required)
Defines what the AI agent is trying to accomplish. Be specific and measurable.
**Examples:**
* `"Complete a hotel booking for 2 guests for next weekend"`
* `"Report a lost credit card and request a replacement"`
* `"Get technical support for a software installation problem"`
* `"Schedule a doctor's appointment for next month"`
#### `persona` (OpenAI-Powered Testing Only)
Describes the character and context the AI agent should adopt during the conversation. **This property is only used with OpenAI-powered testing and is ignored when using Voiceflow agent testing.**
**Examples:**
* `"An elderly customer who is not tech-savvy and needs extra help"`
* `"A busy professional who wants quick, efficient service"`
* `"A frustrated customer whose previous issue wasn't resolved"`
* `"A new user who doesn't understand the product yet"`
#### `maxSteps` (Required)
Maximum number of conversation turns before the test is considered failed. Consider your conversation complexity when setting this value.
**Recommendations:**
* Simple tasks: 5-10 steps
* Medium complexity: 10-20 steps
* Complex scenarios: 20-30 steps
#### `userInformation` (OpenAI-Powered Testing Testing Only)
Predefined user data that the AI agent can provide when your Voiceflow agent requests personal information. **This property is only used with OpenAI-powered testing.**
For Voiceflow agent testing, any required user information should be pre-configured within the tester agent itself.
**Common Information Types:**
* Contact details: `email`, `phone`, `address`
* Account information: `account_number`, `customer_id`, `membership_id`
* Personal details: `name`, `first_name`, `last_name`, `date_of_birth`
* Transaction data: `order_number`, `transaction_id`, `amount`
#### `openAIConfig` (Optional)
Configures the OpenAI model and parameters used for the AI agent in this specific test. This configuration overrides any suite-level OpenAI settings.
**For OpenAI Testing**: Used to power the AI agent that conducts the conversation.\
**For Voiceflow Agent Testing**: Used only for goal evaluation to determine if the test objective has been achieved.
**Properties:**
* `model`: The OpenAI model to use (default: `gpt-4o`)
* `temperature`: Controls response randomness from 0.0 (deterministic) to 1.0 (creative) (default: `0.7`)
#### `voiceflowAgentTesterConfig` (Voiceflow Agent-to-Agent Testing Only)
Configures a Voiceflow agent to act as the tester instead of using OpenAI. When this configuration is present, the system will use agent-to-agent testing with two Voiceflow agents.
**Properties:**
* `environmentName`: The environment name of the tester Voiceflow agent (e.g., "production", "development")
* `apiKey`: The API key for the tester Voiceflow agent (format: `VF.DM.xxxxx.xxxxx`)
* `variables` (Optional): A map of variables to set in the tester agent after the launch event. These variables will be set using the [Voiceflow State Variables API](https://docs.voiceflow.com/reference/updatestatevariables-1) after launching the tester agent.
**Important Notes:**
* When using Voiceflow agent testing, the `persona` and `userInformation` properties are ignored
* The tester agent should be pre-configured with appropriate conversation logic and any required user data
* Variables are set immediately after the launch event, allowing you to initialize the tester agent's state for each test
* OpenAI is still used for goal evaluation even when using Voiceflow agent testing
#### `voiceflowAgentTargetConfig` (Voiceflow Agent-to-Agent Testing Only)
Configures variables for the target Voiceflow agent being tested. This allows you to initialize the target agent's state for each test run.
**Properties:**
* `variables` (Optional): A map of variables to set in the target agent after the launch event. These variables will be set using the [Voiceflow State Variables API](https://docs.voiceflow.com/reference/updatestatevariables-1) after launching the target agent.
**Important Notes:**
* Variables are only set when `newSessionPerTest` is enabled (since the target agent needs to be launched)
* This is useful for setting up test data or initial state in the agent being tested
* Variables are set after the launch event but before the conversation begins
**Example:**
```yaml theme={null}
# OpenAI-powered testing configuration
agent:
goal: "Get technical support for a complex software issue"
persona: "A software developer who needs detailed technical assistance"
maxSteps: 15
openAIConfig:
model: gpt-4o
temperature: 0.3 # Lower temperature for more focused technical responses
```
```yaml theme={null}
# Voiceflow agent-to-agent testing configuration
agent:
goal: "Complete a hotel booking for this weekend"
maxSteps: 12
openAIConfig:
model: gpt-4o
temperature: 0.3 # Used only for goal evaluation
# Optional: Variables to set in the target agent being tested after launch
# Note: Target agent variables are only set when newSessionPerTest is enabled in the suite
voiceflowAgentTargetConfig:
variables:
service_list: "basic, premium, enterprise"
greeting_message: "Welcome to our service! How can I assist you today?"
voiceflowAgentTesterConfig:
environmentName: "production"
apiKey: "VF.DM.your-tester-agent-key"
# Optional: Set variables in the tester agent
variables:
user_name: "John Doe"
user_id: "12345"
booking_type: "hotel"
check_in_date: "2026-02-15"
```
## Choosing Between Testing Methods
### OpenAI-Powered Testing
**Best for:**
* ✅ Flexible persona and behavior simulation
* ✅ Dynamic user information generation
* ✅ Complex reasoning and decision-making scenarios
* ✅ Testing edge cases and unexpected user behaviors
* ✅ Rapid prototyping and testing different user types
**Requirements:**
* OpenAI API key and sufficient quota
* Persona and user information configuration
### Voiceflow Agent Testing
**Best for:**
* ✅ Consistent, reproducible test behavior
* ✅ Testing specific conversation flows designed in Voiceflow
* ✅ Using existing Voiceflow agents as test users
* ✅ Avoiding OpenAI API costs for conversation simulation
* ✅ Pre-configured user personas built in Voiceflow
**Requirements:**
* A separate Voiceflow agent configured as the tester
* API key for the tester agent
* OpenAI API key still needed for goal evaluation
## OpenAI Model Configuration
### Model Recommendations
* `gpt-4o`: Best for complex reasoning and nuanced conversations
* `gpt-4o-mini`: Good balance of performance and cost for most use cases
* `gpt-3.5-turbo`: Budget-friendly option for simpler interactions
### Temperature Guidelines
* `0.0-0.3`: Highly focused, deterministic responses (ideal for technical support)
* `0.4-0.7`: Balanced responses with some creativity (good for general conversations)
* `0.8-1.0`: More creative and varied responses (useful for casual interactions)
## Suite-Level OpenAI Configuration
You can also configure OpenAI settings at the suite level, which applies to all agent tests unless overridden at the test level:
```yaml theme={null}
name: Customer Service Test Suite
description: Comprehensive customer service scenarios
environmentName: production
# Suite-level OpenAI configuration
openAIConfig:
model: gpt-4o-mini
temperature: 0.5
tests:
- id: billing_support
file: ./tests/billing_test.yaml
- id: technical_support
file: ./tests/technical_test.yaml # Can override with test-level config
- id: voiceflow_agent_test
file: ./tests/voiceflow_agent_test.yaml # Uses suite config for goal evaluation
```
## Best Practices
### Writing Effective Goals
✅ **Good Goals:**
* Specific and measurable
* Achievable within the conversation scope
* Focused on user outcomes
❌ **Avoid:**
* Vague objectives
* Impossible tasks
* Testing internal system functions
### Creating Realistic Personas (OpenAI Testing)
✅ **Good Personas:**
* Include emotional context
* Specify technical skill level
* Mention relevant background
❌ **Avoid:**
* Generic descriptions
* Inconsistent characteristics
* Unrealistic behaviors
### Configuring Voiceflow Tester Agents
✅ **Best Practices:**
* Design the tester agent with clear conversation flows
* Include appropriate user information within the agent
* Test the tester agent independently before using in tests
* Use meaningful environment names and secure API keys
❌ **Avoid:**
* Using production agents directly as testers
* Hardcoding sensitive information in tester agents
* Creating overly complex tester agent flows
### Setting Appropriate Step Limits
* **Too Low**: May timeout before completion
* **Too High**: May hide conversation inefficiencies
* **Just Right**: Allows natural completion with buffer for edge cases
## Authentication Requirements
### OpenAI Testing Requirements
OpenAI-powered agent tests require OpenAI API access for the AI agent functionality. Make sure to:
1. Set up your OpenAI API key in your environment
2. Configure authentication as described in the [Authentication](/developer-tools/voiceflow-cli/overview/authentication) page
3. Ensure sufficient API quota for test execution
### Voiceflow Agent Testing Requirements
Voiceflow agent-to-agent tests require:
1. **Target Agent**: API key for the agent being tested
2. **Tester Agent**: API key for the agent acting as the tester (specified in `voiceflowAgentTesterConfig`)
3. **OpenAI API**: Still required for goal evaluation functionality
4. **Environment Access**: Ensure both agents are accessible in their respective environments
## Monitoring and Debugging
### Test Logs
Both testing methods provide detailed logs including:
**OpenAI Testing Logs:**
* AI agent's thought process and responses
* Conversation flow and decision points
* Goal achievement evaluation
* User information requests and responses
**Voiceflow Agent Testing Logs:**
* Interaction between tester and target agents
* Message exchange flow
* Goal achievement evaluation
* Agent response details
### Common Issues
**General Issues:**
* **Goal not achieved**: Review if the goal is realistic and achievable
* **Timeout errors**: Consider increasing `maxSteps` or simplifying the goal
* **Authentication errors**: Verify API key configuration
**OpenAI Testing Specific:**
* **Inconsistent behavior**: AI responses may vary; focus on goal achievement rather than exact responses
* **OpenAI API errors**: Check API key and quota limits
**Voiceflow Agent Testing Specific:**
* **Tester agent errors**: Verify the tester agent is properly configured and accessible
* **API key issues**: Ensure both target and tester agent API keys are valid
* **Environment mismatches**: Verify environment names are correct for both agents
# Interaction-based examples
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/automated-testing/contains
See practical examples of interaction-based tests with validation rules.
# Example using `contains` validation
## Suite file
```yaml theme={null}
# suite.yaml
name: Example Suite
description: Suite used as an example
environmentName: production
# Optional: Create a new user session for each test (default: false)
# When enabled, each test will run with a fresh user session
newSessionPerTest: true
tests:
- id: test_id
file: ./test.yaml
```
## Test file
```yaml theme={null}
# test.yaml
name: Example test
description: These are some tests
interactions:
- id: test_1
user:
type: text
text: hi
agent:
validate:
- type: contains
value: hello
```
```yaml theme={null}
# test.yaml
name: Example test
description: These are some tests
interactions:
- id: test_1
user:
type: text
text: hi
agent:
validate:
- type: contains
value: hello
```
# Automated testing
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/automated-testing/index
Test your agents with interaction-based and AI-powered agent-to-agent testing.
## What is this?
Use the Conversation Profiler to test user utterances and improve your agent's interaction model.
The Conversation Profiler supports **two distinct testing approaches** to validate your agent's conversation flow:
### 🔧 Traditional Interaction-Based Testing
Test the conversation flow with **predefined interactions** where you send specific user utterances to your agent and validate exact responses. This approach is ideal for:
* **Regression testing** to ensure specific responses remain consistent
* **Validation of exact conversation flows** with predetermined inputs and outputs
* **Quality assurance** for specific features or conversation paths
#### Reference
It is important to know which [suites](/developer-tools/voiceflow-cli/automated-testing/suites) and [tests](/developer-tools/voiceflow-cli/automated-testing/tests) you can build. Because of that, you can find the entire reference on the [Reference](/developer-tools/voiceflow-cli/automated-testing/agent-to-agent-tests) page. Suites and test are defined as `yaml` files.
### 🤖 Agent-to-Agent Testing
Simulate **realistic conversations** using AI-powered agents that interact naturally with your Voiceflow agent to achieve specific goals. This approach offers two testing methods:
**OpenAI-Powered Testing:**
* Uses OpenAI models (GPT-4, GPT-4o, etc.) to simulate user behavior
* Configurable personas and dynamic user information
* Ideal for testing varied user types and edge cases
**Voiceflow Agent Testing:**
* Uses another Voiceflow agent as the tester
* Consistent, reproducible test behavior
* Leverages existing Voiceflow agent configurations
Both methods are ideal for:
* **End-to-end conversation testing** with natural, adaptive interactions
* **User behavior simulation** where the AI agent responds dynamically like real users
* **Goal-oriented testing** to ensure your agent can handle varied conversation paths
Both testing approaches can be run in your CI/CD pipelines and include additional features beyond the Voiceflow console's Test Agent feature. Every suite is executed in the same Voiceflow user's session.
All of the commands that are available in `voiceflow-cli` to execute the Conversation profiler are located within the [`voiceflow test subcommand`](../command-line-usage/voiceflow-test).
#### Reference
It is important to know which [suites](/developer-tools/voiceflow-cli/automated-testing/suites) and [tests](/developer-tools/voiceflow-cli/automated-testing/tests) you can build. Because of that, you can find the entire reference on the [Reference](/developer-tools/voiceflow-cli/automated-testing/agent-to-agent-tests) page. Suites and test are defined as `yaml` files.
## Examples
You can find some useful examples on our [GitHub repo](https://github.com/xavidop/voiceflow-cli/tree/main/examples)
## Execution Example
Here is a simple example of the `voiceflow test execute` command:
```sh theme={null}
voiceflow test execute examples/test/
```
The above command will give you output similar to the following:
```sh theme={null}
$ voiceflow test execute examples/test/
Dec 31 10:54:01.664 [INFO] Suite: Example Conversation Profiler Suite
Description: Suite used as an example
Environment: development
Dec 31 10:54:01.664 [INFO] Running Tests:
Dec 31 10:54:01.664 [INFO] Running Test ID: Example test
Dec 31 10:54:01.664 [INFO] Interaction ID: test_1_1
Dec 31 10:54:01.664 [INFO] Interaction Request Type: launch
Dec 31 10:54:02.693 [INFO] Interaction Response Type: text
Dec 31 10:54:02.693 [INFO] Interaction Response Message: Hey there! 🌟 Welcome to the Isla Experience! I’m like a warm cup of cocoa on a chilly day—sweet, comforting, and maybe a little too hot if you’re not careful! How’s your day going?
Dec 31 10:54:02.693 [INFO] All validations passed for Interaction ID: test_1_1
Dec 31 10:54:02.693 [INFO] Interaction ID: test_1_2
Dec 31 10:54:02.693 [INFO] Interaction Request Type: text
Dec 31 10:54:02.693 [INFO] Interaction Request Payload: I am doing well
Dec 31 10:54:03.889 [INFO] Interaction Response Type: text
Dec 31 10:54:03.889 [INFO] Interaction Response Message: Awesome! Glad to hear it! Are you riding the wave of good vibes, or did you just find a hidden stash of chocolate? 🍫 Either way, I’m here for it! What’s been the highlight of your day so far?
Dec 31 10:54:03.889 [INFO] All validations passed for Interaction ID: test_1_2
Dec 31 10:54:03.889 [INFO] Interaction ID: test_1_3
Dec 31 10:54:03.889 [INFO] Interaction Request Type: text
Dec 31 10:54:03.889 [INFO] Interaction Request Payload: I have been working very hard
Dec 31 10:54:06.090 [INFO] Interaction Response Type: text
Dec 31 10:54:06.091 [INFO] Interaction Response Message: Ah, the classic “I’m working hard” routine! It’s like a superhero origin story, but instead of gaining superpowers, you just gain a lot of coffee stains and a questionable relationship with your chair. What kind of work are you diving into?
Dec 31 10:54:06.091 [INFO] All validations passed for Interaction ID: test_1_3
```
!!! info "Are you running this command in a CI/CD pipeline?"\
If this is the case, we recommend that you set the `--output-format` parameter to `json`.
# Suite reference
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/automated-testing/suites
Structure and configure test suites for your Voiceflow agents.
## Reference
A suite is a yaml file with the following structure:
```yaml theme={null}
# suite.yaml
# Name of the suite.
name: Example Suite
# Brief description of the suite.
description: Suite used as an example
# Environment name of your Voiceflow agent. It could be development, or production.
environmentName: development
# Optional: Create a new user session for each test (default: false)
# When enabled, each test will run with a fresh user session
newSessionPerTest: true
# You can have multiple tests defined in separated files
tests:
# ID of the test.
- id: test_id
# File where the test specification is located
file: ./test.yaml
```
### Session Management
By default, all tests within a suite share the same user session (user ID). This means that:
* Variables set in one test persist to the next test
* The conversation context carries over between tests
* Tests are executed sequentially with the same user state
If you want each test to start with a fresh session, set `newSessionPerTest: true`. This will:
* Generate a new user ID for each test
* Clear all conversation context between tests
* Ensure tests are completely isolated from each other
## JSON Schema
`voiceflow-cli` also has a [jsonschema](http://json-schema.org/draft/2020-12/json-schema-validation.html) file, which you can use to have better\
editor support:
```sh theme={null}
https://voiceflow.xavidop.me/static/conversationsuite.json
```
You can also specify it in your `yml` config files by adding a\
comment like the following:
```yaml theme={null}
# yaml-language-server: $schema=https://voiceflow.xavidop.me/static/conversationsuite.json
```
# Interaction-based tests reference
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/automated-testing/tests
Define and structure interaction-based tests to validate agent responses.
## Overview
Test the conversation flow with **predefined interactions** where you send specific user utterances to your agent and validate exact responses.
## Reference
A traditional test is a YAML file with the following structure:
```yaml theme={null}
# test.yaml
# Name of the test.
name: Example test
# Brief description of the test.
description: These are some tests
# A interactions is the test itself: given an input, you will validate the agent response returned by Voiceflow
# You can have multiple interactions defined
interactions:
# The ID of the interactions
- id: test_1
user:
# the input type
# it could be text, audio or prompt
type: text
# The input itself in text format. For type: audio, you have to specify the audio file.
text: I want 3 pizzas
agent:
validate:
# String validation to check if the response returned by Voiceflow is correct
- type: contains
value: pizza
- id: test_2
user:
type: text
text: hi
agent:
# example with a traceType validation
validate:
- type: traceType
value: speak
- id: test_3
user:
type: text
audio: hello
agent:
# example with a regexp validation
validate:
- type: regexp
value: '/my-regex/'
- id: test_4
user:
type: text
audio: hello
agent:
# example with a similarity validation
validate:
- type: similarity
similarityConfig:
provider: 'openai'
model: 'gpt-4o'
temperature: 0.8
top_k: 5
top_p: 0.9
similarityThreshold: 0.5
values:
- 'hi'
- 'Hello'
- id: test_5
user:
type: text
text: 'myVariableValue1'
agent:
# example with a variable validation
validate:
- type: variable
value: 'myVariableValue1'
variableConfig:
name: 'variableName1'
```
## Input types
### Text input
The input text is the simplest one. You just have to specify the text you want to send to Voiceflow. Make sure that the text is in the language you specified in the `localeId` field. to use this type you have to set the `type` field to `text` and the `text` field to the text you want to send.
```yaml theme={null}
user:
type: text
text: I want 3 pizzas
```
### Launch input
The launch input is used to start a new conversation session. This is typically the first interaction in a test. To use this type you have to set the `type` field to `launch`.
```yaml theme={null}
user:
type: launch
```
### Event input
The event input allows you to send custom events to your Voiceflow agent. Events can be used to trigger specific flows or actions in your agent. To use this type you have to set the `type` field to `event` and the `event` field to the event name you want to send.
```yaml theme={null}
user:
type: event
event: user_logged_in
```
Example with validation:
```yaml theme={null}
- id: event_example
user:
type: event
event: user_logged_in
agent:
validate:
- type: contains
value: "Welcome back!"
```
### Intent input
The intent input allows you to directly send an intent to your Voiceflow agent, bypassing NLU processing. This is useful when you have your own NLU matching or want to test specific intent handling. To use this type you have to set the `type` field to `intent` and provide an `intent` object with the intent name and optional entities.
```yaml theme={null}
user:
type: intent
intent:
name: order_pizza
entities:
- name: pizza_type
value: pepperoni
- name: size
value: large
```
The `intent` object accepts the following properties:
* `name`: (Required) The name of the intent to trigger
* `entities`: (Optional) An array of entity objects with `name` and `value` fields
Examples:
```yaml theme={null}
# Intent with entities
- id: intent_with_entities
user:
type: intent
intent:
name: order_pizza
entities:
- name: pizza_type
value: pepperoni
- name: size
value: large
agent:
validate:
- type: contains
value: "one large pepperoni pizza"
# Intent without entities
- id: intent_no_entities
user:
type: intent
intent:
name: get_help
agent:
validate:
- type: contains
value: "How can I help you?"
```
### Button input
The button input allows you to simulate clicking a button that was presented in a previous choice/button response from your Voiceflow agent. This is useful for testing conversational flows that include button interactions. To use this type you have to set the `type` field to `button` and the `value` field to the button label you want to click.
```yaml theme={null}
user:
type: button
value: Yes, continue
```
The button interaction automatically:
* Finds the matching button from the previous `choice` trace by its label
* Sends the complete button request (including path type and payload) back to Voiceflow
* Handles the button click as if a user clicked it in a real conversation
**Important**: A button interaction must follow an interaction that returned a `choice` trace type with buttons. The `value` must match the `label` field in one of the button's payload.
Example workflow:
```yaml theme={null}
# First interaction receives a choice with buttons
- id: show_options
user:
type: text
text: "Show me options"
agent:
validate:
- type: traceType
value: choice
# Second interaction clicks one of the buttons
- id: select_option
user:
type: button
value: "Yes, continue" # Must match button label
agent:
validate:
- type: contains
value: "Great! Continuing..."
```
Complete example:
```yaml theme={null}
name: Button Interaction Example
description: Test demonstrating button click simulation
interactions:
- id: launch_conversation
user:
type: launch
agent:
validate:
- type: contains
value: "Welcome"
- type: traceType
value: choice
- id: click_yes_button
user:
type: button
value: "Yes" # Clicks the button with label "Yes"
agent:
validate:
- type: contains
value: "You selected yes"
```
## Validation types
### Contains
The contains validation type is the simplest one. It just checks if the response returned by the Voiceflow agent contains the value specified in the `value` field. To use this type you have to set the `type` field to `contains` and the `value` field to the value you want to check:
```yaml theme={null}
validate:
# String validation to check if the response returned by Voiceflow is correct
- type: contains
value: pizza
```
### Equals
The equals validation type is a little bit more complex. It checks if the response returned by the Voiceflow agent is equal to the value specified in the `value` field. To use this type you have to set the `type` field to `equals` and the `value` field to the value you want to check:
```yaml theme={null}
validate:
# String validation to check if the response returned by Voiceflow is correct
- type: equals
value: Here you have 3 pizzas
```
### Regexp
The regexp validation type is the most complex one. It checks if the response returned by the Voiceflow agent matches the regexp specified in the `value` field. To use this type you have to set the `type` field to `regexp` and the `value` field to the regular expression you want to check:
```yaml theme={null}
validate:
# String validation to check if the response returned by Voiceflow is correct
- type: regexp
value: '/Here you have \d pizzas/'
```
### TraceType
The traceType validation type checks if the response returned by the Voiceflow agent has the trace type specified in the `value` field. To use this type you have to set the `type` field to `traceType` and the `value` field to the trace type you want to check:
```yaml theme={null}
validate:
# String validation to check if the response returned by Voiceflow is correct
- type: traceType
value: speak
```
### Similarity
The similarity validation type checks if the response returned by the Voiceflow agent is similar to the values specified in the `values` field. To use this type you have to set the `type` field to `similarity` and the `values` field to the values you want to check:
```yaml theme={null}
validate:
# String validation to check if the response returned by Voiceflow is correct
- type: similarity
similarityConfig:
provider: 'openai'
model: 'gpt-4o'
temperature: 0.8
top_k: 5
top_p: 0.9
similarityThreshold: 0.5
values:
- 'hi'
- 'Hello'
```
You can also use the `similarityConfig` field to specify the similarity configuration. The `provider` field specifies the similarity provider you want to use. The `model` field specifies the model you want to use. The `temperature` field specifies the temperature you want to use. The `top_k` field specifies the top k you want to use. The `top_p` field specifies the top p you want to use. The `similarityThreshold` field specifies the similarity threshold you want to use.
The only provider available for now is `openai`.
For LLM Providers authentication please check the [Authentication](/developer-tools/voiceflow-cli/overview/authentication) page.
### Variable
The variable validation type checks if a variable in the Voiceflow agent has the expected value. To use this type you have to set the `type` field to `variable`, the `value` field to the expected value, and provide a `variableConfig` object with the variable details:
```yaml theme={null}
validate:
# Variable validation to check if a variable has the expected value
- type: variable
value: 'myVariableValue1'
variableConfig:
name: 'variableName1'
```
The `variableConfig` object accepts the following properties:
* `name`: (Required) The name of the variable to validate
* `jsonPath`: (Optional) A JSONPath expression to extract nested values from JSON/object variables
Examples:
```yaml theme={null}
validate:
# Simple variable validation
- type: variable
value: 'myVariableValue1'
variableConfig:
name: 'variableName1'
# Multiple variable validations
- type: variable
value: 'myVariableValue2'
variableConfig:
name: 'variableName2'
# Variable validation with JSONPath if the variable is a JSON/object
- type: variable
value: 'myVariableValue3'
variableConfig:
name: 'variableName3'
jsonPath: '$.hello'
```
## JSON Schema
`voiceflow-cli` also has a [jsonschema](http://json-schema.org/draft/2020-12/json-schema-validation.html) file, which you can use to have better\
editor support:
```sh theme={null}
https://voiceflow.xavidop.me/static/conversationtest.json
```
You can also specify it in your `yml` config files by adding a\
comment like the following:
```yaml theme={null}
# yaml-language-server: $schema=https://voiceflow.xavidop.me/static/conversationtest.json
```
```yaml theme={null}
# yaml-language-server: $schema=https://voiceflow.xavidop.me/static/conversationtest.json
```
# CLI Quickstart
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/cli-quick-start
Get up and running with the Voiceflow CLI in minutes.
`voiceflow-cli` is a command-line tool that allows Voiceflow users to [upload files to their knowledge base](/developer-tools/voiceflow-cli/documents/upload-files), [download transcripts](/developer-tools/voiceflow-cli/transcripts/fetching), [run automated tests](/developer-tools/voiceflow-cli/automated-testing/index), and more.
In a few minutes, this guide will walk you through installing the CLI, authenticating your agent, and uploading a document to your [knowledge base](doc:knowledge-base).
## 1. Install the CLI
Open your terminal, then input the command below that corresponds to your operating system. If you're on MacOS or Linux, [install brew before running this command](https://brew.sh/).
```curl Mac or Linux theme={null}
brew install xavidop/tap/voiceflow
```
```text Windows theme={null}
curl -sfL https://voiceflow.xavidop.me/static/run | bash
```
Alternatively, you can install the Voiceflow CLI via Chocolatey (Windows) or APT (Linux). [Click here to learn more.](doc:cli-install)
To check if the Voiceflow CLI was successfully installed, run:
```bash theme={null}
voiceflow --help
```
You should see a list of commands, as shown below. If you do, the installation was successful - you're all set!!
## 2. Grab your agent's API key
* Open the [Voiceflow Creator](https://creator.voiceflow.com/), and click the agent you want to use with the CLI.
* In the sidebar, click **Settings** → **API keys**
* Click the **copy** button to grab your API key
## 3. Add the agent's API key to your environment
Run the following command, making sure you replace `YOUR_KEY` with the copied API key from the previous step. This will add your API key to the environment.
```Text bash theme={null}
export VF_API_KEY=YOUR_KEY
```
Alternatively, you can authenticate using a flag, or a `.env` file. [Click here to learn more.](doc:authentication)
## 4. Upload data to your agent's knowledge base
You're almost there! Finally, paste the following command into your terminal to upload data to your agent's knowledge base. In this example, we'll upload the contents of this page!
```bash theme={null}
voiceflow document upload-url --url https://docs.voiceflow.com/docs/cli-quick-start.md --name "Quick Start"
```
While the upload processes, you'll see a pending status in your terminal.
To check if your data was successfully updated to the agent's knowledge base, go back to your Voiceflow project, and click **knowledge base** button in your sidebar. You should see your newly updated file as shown below.
## Congratulations!
You just successfully installed the CLI, authenticated your agent, and uploaded your first document to the knowledge base. From here, you can explore the full range of CLI commands to test your agent, fetch transcripts, and automate your workflows. Happy building!
# voiceflow
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/index
Reference for Voiceflow CLI command syntax and global options.
Voiceflow CLI
## Synopsis
Welcome to voiceflow-cli!
This utility provides you with an easy way to interact\
with your Voiceflow agents.
You can find the documentation at [https://github.com/xavidop/voiceflow-cli](https://github.com/xavidop/voiceflow-cli).
Please file all bug reports on GitHub at [https://github.com/xavidop/voiceflow-cli/issues](https://github.com/xavidop/voiceflow-cli/issues).
```
voiceflow [flags]
```
## Options
```
-h, --help help for voiceflow
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow agent](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-agent) - Actions on agents
* [voiceflow analytics](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-analytics) - Actions on analytics
* [voiceflow completion](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-completion) - Generate the autocompletion script for the specified shell
* [voiceflow dialog](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-dialog) - Start a dialog with the Voiceflow project
* [voiceflow document](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-document) - Actions on documents
* [voiceflow jsonschema](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-jsonschema) - outputs voiceflow's JSON schema
* [voiceflow kb](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-kb) - Actions on knowledge base
* [voiceflow server](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-server) - Start a Voiceflow server
* [voiceflow test](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-test) - Actions on conversation testing
* [voiceflow transcript](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-transcript) - Actions on transcripts
* [voiceflow version](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-version) - Get voiceflow-cli version
# voiceflow agent
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-agent
CLI reference for agent management commands.
Actions on agents
```text theme={null}
voiceflow agent [flags]
```
## Options
```text theme={null}
-h, --help help for agent
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow agent export](/developer-tools/voiceflow-cli/agent/export) - Export a voiceflow project into a file
# voiceflow analytics
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-analytics
CLI reference for analytics fetching commands.
Actions on analytics
```text theme={null}
voiceflow analytics [flags]
```
## Options
```text theme={null}
-h, --help help for analytics
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow analytics fetch](/developer-tools/voiceflow-cli/analytics/fetch) - Fetch all project analytics. They could write into a file
# voiceflow completion
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-completion
Enable shell autocompletion for Voiceflow CLI commands.
Generate the autocompletion script for the specified shell
## Synopsis
Generate the autocompletion script for voiceflow for the specified shell.\
See each sub-command's help for details on how to use the generated script.
## Options
```text theme={null}
-h, --help help for completion
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
# voiceflow dialog
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-dialog
Start a dialog with the Voiceflow project.
Actions on agents
```text theme={null}
voiceflow dialog [flags]
```
## Options
```text theme={null}
-h, --help help for dialog
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow dialog replay](/developer-tools/voiceflow-cli/dialog/replay) - Replay a dialog with the Voiceflow project
* [voiceflow dialog start](/developer-tools/voiceflow-cli/dialog/start) - Start a dialog with the Voiceflow project
# voiceflow document
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-document
CLI reference for knowledge base document management commands.
Actions on documents
```text theme={null}
voiceflow document [flags]
```
## Options
```text theme={null}
-h, --help help for document
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow document upload-file](/developer-tools/voiceflow-cli/documents/upload-files) - Upload a file to a knowledge base
* [voiceflow document upload-url](/developer-tools/voiceflow-cli/documents/upload-urls) - Upload a URL to a knowledge base
# voiceflow jsonschema
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-jsonschema
Export Voiceflow's JSON schema for custom integrations.
Outputs voiceflow's JSON schema
```
voiceflow jsonschema [flags]
```
## Options
```
-h, --help help for jsonschema
-f, --output-folder string Where to save the JSONSchema file (default "-")
```
## Options inherited from parent commands
```
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
# voiceflow kb
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-kb
CLI reference for knowledge base management commands.
Actions on knowledge base
```text theme={null}
voiceflow kb [flags]
```
## Options
```text theme={null}
-h, --help help for kb
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow kb query](/developer-tools/voiceflow-cli/knowledge-base/query) - Query a knowledge base
# voiceflow server
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-server
CLI reference for starting the Voiceflow test API server.
Start the Voiceflow CLI API server
## Synopsis
Start the Voiceflow CLI API server to expose test execution endpoints.
The server provides HTTP endpoints for:
* Executing test suites
* Checking test execution status
* Retrieving system information
The server includes auto-generated OpenAPI/Swagger documentation available at /swagger/index.html
```
voiceflow server [flags]
```
## Examples
```
# Start server on default port (8080)
voiceflow server
# Start server on custom port
voiceflow server --port 9090
# Start server with debug mode
voiceflow server --debug
# Start server with custom host
voiceflow server --host 127.0.0.1 --port 8080
```
## Options
```
--cors Enable CORS middleware (default true)
-d, --debug Enable debug mode
-h, --help help for server
-H, --host string Host to bind the server to (default "0.0.0.0")
-p, --port string Port to run the server on (default "8080")
--swagger Enable Swagger documentation endpoint (default true)
```
## Options inherited from parent commands
```
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
# voiceflow test
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-test
CLI reference for test execution commands.
Actions on conversation testing
```text theme={null}
voiceflow test [flags]
```
## Options
```text theme={null}
-h, --help help for test
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow test execute](/developer-tools/voiceflow-test-platform/test-execution) - Execute a suite
# voiceflow transcript
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-transcript
CLI reference for transcript fetching and management commands.
Actions on transcripts
```text theme={null}
voiceflow transcript [flags]
```
## Options
```text theme={null}
-h, --help help for transcript
```
## Options inherited from parent commands
```text theme={null}
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
* [voiceflow transcript fetch](/developer-tools/voiceflow-cli/transcripts/fetching) - Fetch one transcripts from a project
* [voiceflow transcript to-test](/developer-tools/voiceflow-cli/transcripts/transcripts-to-test) - Transforms a transcript into a test
# voiceflow version
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/command-line-usage/voiceflow-version
Check your installed Voiceflow CLI version.
Get voiceflow-cli version
```
voiceflow version [flags]
```
## Options
```
-h, --help help for version
```
## Options inherited from parent commands
```
-z, --open-api-key string Open API Key (optional)
-o, --output-format string Output Format. Options: text, json. Default: text (optional) (default "text")
-u, --skip-update-check Skip the check for updates check run before every command (optional)
-v, --verbose verbose error output (with stack trace) (optional)
-x, --voiceflow-api-key string Voiceflow API Key (optional)
-b, --voiceflow-subdomain string Voiceflow Base URL (optional). Default: empty
```
## See also
* [voiceflow](/developer-tools/voiceflow-cli/command-line-usage/index) - Voiceflow CLI
# Dialog
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/dialog/index
Conduct interactive conversations with your Voiceflow projects.
The `dialog` commands allow you to interact with your Voiceflow project through a conversational interface. You can start new conversations, record them for later use, replay previous conversations, and create tests from your interactions.
### Available Commands
| Command | Description |
| ------------------------------------------------------ | ---------------------------------------------------- |
| [start](/developer-tools/voiceflow-cli/dialog/start) | Start a new conversation with your Voiceflow project |
| [replay](/developer-tools/voiceflow-cli/dialog/replay) | Replay a previously recorded conversation |
### Common Options
All dialog commands support these common options:
| Option | Description |
| --------------------- | ---------------------------------------------------------------------------------- |
| `--environment`, `-e` | Voiceflow environment to use (default: "development") |
| `--user-id`, `-u` | User ID for the conversation (optional, will generate a random ID if not provided) |
### Basic Usage
```bash theme={null}
# 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
```
For detailed information about each command, refer to their specific documentation pages.
# Replay
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/dialog/replay
Replay previously recorded conversations for testing and debugging.
***
## sidebar\_position: 2
## Replay command
The `replay` command allows you to replay previously recorded conversations with your Voiceflow project. This is useful for testing changes to your project with consistent inputs, demonstrating flows, or debugging issues.
## Usage
```bash theme={null}
voiceflow dialog replay -f RECORD_FILE [options]
```
## Options
| Option | Shorthand | Description |
| --------------- | --------- | ------------------------------------------------- |
| `--record-file` | `-f` | Path to the recorded conversation file (required) |
| `--environment` | `-e` | Environment to use (default: "development") |
| `--user-id` | `-u` | User ID for the conversation (optional) |
## Examples
### Replay a recorded conversation
```bash theme={null}
voiceflow dialog replay -f my-conversation.json
```
This will replay all interactions from the recording file against your Voiceflow project.
### Replay with a specific user ID
```bash theme={null}
voiceflow dialog replay -f my-conversation.json --user-id user123
```
This allows you to maintain consistent user state or test with specific user profiles.
### Replay in production environment
```bash theme={null}
voiceflow dialog replay -f my-conversation.json -e production
```
Replays the conversation using your production environment settings.
## How replay works
The `replay` command:
1. Reads the recorded conversation file specified with `-f`
2. Processes each interaction in sequence, automatically sending user inputs to the Voiceflow API
3. Displays the responses from your Voiceflow project for each interaction
4. Adds brief pauses between interactions to simulate natural conversation timing
## Creating recording files
To create a file for replay, use the `dialog start` command with the `--record-file` option:
```bash theme={null}
voiceflow dialog start --record-file my-conversation.json
```
During the conversation, every interaction will be saved to the specified file. When you finish the conversation (by typing `exit` or pressing `Ctrl+C`), the complete recording will be available for replay.
## Troubleshooting
If the replay produces different results than the original conversation:
1. Check if your Voiceflow project has been modified since the recording
2. Verify you're using the same environment that was used during recording
3. Consider using a consistent user ID if your project relies on user-specific state
4. Ensure any external APIs or services your project depends on are available
# Start
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/dialog/start
Start an interactive conversation session with your agent.
The `start` command initiates an interactive conversation with your Voiceflow project. This allows you to test your project's dialog flow by sending text inputs and receiving responses.
## Usage
```bash theme={null}
voiceflow dialog start [options]
```
## Options
| Option | Shorthand | Description |
| --------------- | --------- | -------------------------------------------------- |
| `--environment` | `-e` | Alias of the environment to use (default: "main") |
| `--user-id` | `-u` | User ID for the conversation (optional) |
| `--record-file` | `-f` | File to save the conversation recording (optional) |
| `--save-test` | `-t` | Save the conversation as a test file (optional) |
## Examples
### Start a basic conversation
```bash theme={null}
voiceflow dialog start
```
This starts a conversation with your Voiceflow project in the default environment (Main). You can type messages and see the responses from your project.
### Start with a specific user ID
```bash theme={null}
voiceflow dialog start --user-id user123
```
Using a consistent user ID allows the conversation to maintain state across multiple sessions.
### Record a conversation
```bash theme={null}
voiceflow dialog start --record-file my-conversation.json
```
This will save the entire conversation to a file that can be replayed later using the `replay` command.
### Start a conversation and save it as a test
```bash theme={null}
voiceflow dialog start --save-test
```
This records the conversation and automatically saves it as a YAML test file that can be used with the `voiceflow test` commands.
### Conversation in a specific environment
```bash theme={null}
voiceflow dialog start -e my-feature
```
Starts the conversation using the environment whose alias is `my-feature`. You can find each environment's alias in **Settings** → **Environments**.
## Interactive Commands
During an active conversation session, you can use these special commands:
| Command | Action |
| ---------------- | ------------------------------------------------------------ |
| `exit` or `quit` | End the conversation and exit |
| `Ctrl+C` | Interrupt the conversation (will save recordings if enabled) |
## Recording Format
When you use the `--record-file` option, the conversation is saved in JSON format with the following structure:
```json theme={null}
{
"name": "Recording_YYYYMMDD_HHMMSS",
"interactions": [
{
"id": "launch",
"user": {
"type": "launch"
},
"agent": [
{
"type": "text",
"value": "Hello! How can I help you today?"
}
]
},
{
"id": "interaction_1",
"user": {
"type": "text",
"text": "What's the weather like?"
},
"agent": [
{
"type": "text",
"value": "I don't have access to weather information."
}
]
}
]
}
```
This recording can be used with the `voiceflow dialog replay` command to repeat the conversation.
# Documents
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/documents/index
Upload and manage documents in your knowledge base.
## What is this?
The Documents are items that are uploaded to the Knowledge Base. They can be used to store information that can be used to answer questions or provide information to the users. The documents can be uploaded in various formats like PDF, Word, Markdown, etc. The documents can be processed using the LLM model to generate questions, summarize content, etc.
## Reference
The `voiceflow-cli` has a command that allows you to interact with your documents of your Voiceflow Knowledge bases from your terminal or from your CI pipelines.
To know more, you can run the `voiceflow document` command. For the usage, please refer to this [page](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-document).
# Upload files
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/documents/upload-files
Upload local files to your Voiceflow knowledge base.
## Upload URLs to the knowledge base
With the `voiceflow-cli` you can upload content from a file to your Voiceflow Knowledge Base with customizable processing options. This is useful when you want to perform a automations around your knowledge base. The `voiceflow-cli` has one command that allows you to update your knowledge base from your terminal:
### Command Usage
```bash theme={null}
voiceflow document upload-file [flags]
```
#### Aliases
* `uf`
* `upload-files`
### Parameters
#### Required Flags
* `--file`: Path to local file
#### Processing Options
* `--max-chunk-size`: Maximum size of content chunks
* `--markdown-conversion`: Convert content to markdown format
* `--overwrite`: Overwrite existing document if present
#### LLM Processing Options
* `--llm-generated-q`: Enable LLM-generated questions
* `--llm-prepend-context`: Prepend context using LLM
* `--llm-based-chunking`: Use LLM for content chunking
* `--llm-content-summarization`: Enable content summarization
#### Metadata
* `--tags`: Array of tags to associate with document
### Examples
#### Basic File Upload
```bash theme={null}
voiceflow document upload-file \
--file ./docs/api.pdf
```
#### Advanced Upload with Processing
```bash theme={null}
voiceflow document upload-file \
--file ./docs/guide.md \
--max-chunk-size 1000 \
--markdown-conversion \
--llm-generated-q \
--llm-content-summarization \
--tags guide,user
```
#### Upload with Overwrite
```bash theme={null}
voiceflow document upload-file \
--file ./docs/updated-policy.pdf \
--overwrite \
--tags policy,legal
```
### Supported File Types
* PDF
* TXT
* DOC/DOCX
* MD
* And other text-based formats
### Requirements
* File must be accessible locally
# Upload URLs
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/documents/upload-urls
Import content from URLs into your knowledge base.
## Upload URLs to the Knowledge Base
With the `vocieflow-cli` you can upload content from a URL to your Voiceflow Knowledge Base with customizable processing options. This is useful when you want to perform a automations around your knowledge base. The `voiceflow-cli` has one command that allows you to update your knowledge base from your terminal:
### Command Usage
```bash theme={null}
voiceflow document upload-url [flags]
```
#### Aliases
* `ur`
* `upload-urls`
### Parameters
#### Required Flags
* `--url`: URL to upload content from
* `--name`: Name for the uploaded document
#### Processing Options
* `--max-chunk-size`: Maximum size of content chunks
* `--markdown-conversion`: Convert content to markdown format
* `--overwrite`: Overwrite existing document if present
#### LLM Processing Options
* `--llm-generated-q`: Enable LLM-generated questions
* `--llm-prepend-context`: Prepend context using LLM
* `--llm-based-chunking`: Use LLM for content chunking
* `--llm-content-summarization`: Enable content summarization
#### Metadata
* `--tags`: Array of tags to associate with the document
### Examples
#### Basic Upload
```bash theme={null}
voiceflow document upload-url --url https://docs.example.com/api --name "API Documentation"
```
#### Advanced Upload with LLM Processing
```bash theme={null}
voiceflow document upload-url \
--url https://docs.example.com/api \
--name "API Documentation" \
--max-chunk-size 1000 \
--markdown-conversion \
--llm-generated-q \
--llm-content-summarization \
--tags api,documentation
```
#### Upload with Overwrite
```bash theme={null}
voiceflow document upload-url \
--url https://docs.example.com/api \
--name "API Documentation" \
--overwrite \
--tags api,v2
```
# Knowledge base
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/knowledge-base/index
Manage your agent's knowledge base repository and settings.
## What is this?
The Knowledge Base is a repository and management system for content that your AI Agent uses to provide accurate and contextually relevant responses. It allows you to:
1. Store and organize information your agent can reference
2. Provide context for more accurate and relevant responses
3. Easily update and maintain your agent's knowledge
## Reference
The `voiceflow-cli` has a command that allows you to interact with your Voiceflow Knowledge bases from your terminal or from your CI pipelines.
To know more, you can run the `voiceflow kb` command. For the usage, please refer to this [page](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-kb).
# Query
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/knowledge-base/query
Query your knowledge base with AI model processing.
## Export an agent
With the `voiceflow-cli` you can query your agents' knowledge base. This is useful when you want to perform a query on your knowledge base. The `voiceflow-cli` has one command that allows you to query your knowledge base from your terminal:
### Parameters
#### Required Parameters
* `--model, -m`: AI model to process knowledge base queries
* Required: Yes
* Example: `--model gpt-4`
#### Optional Parameters
##### Model Configuration
* `--temperature, -r`
* Range: 0.0 to 1.0
* Default: 0.7
* Purpose: Controls response randomness
* `--chunk-limit, -c`
* Default: 2
* Purpose: Maximum chunks to process
* `--synthesis, -s`
* Default: true
* Purpose: Enable/disable AI answer generation
* `--system-prompt, -p`
* Default: empty
* Purpose: Custom system instructions
##### Tag Filtering
* `--include-tags, -t`
* Default: \[]
* Purpose: Tags to include in search
* `--include-operator, -i`
* Values: "and"/"or"
* Purpose: Logic operator for included tags
* `--exclude-tags, -y`
* Default: \[]
* Purpose: Tags to exclude from search
* `--exclude-operator, -j`
* Values: "and"/"or"
* Purpose: Logic operator for excluded tags
* `--include-all-tagged, -g`
* Default: false
* Purpose: Include all documents with tags
* `--include-all-non-tagged, -n`
* Default: false
* Purpose: Include all documents without tags
##### Output
* `--output-file, -d`
* Default: "query.json"
* Purpose: Results output location
### Examples
#### Basic Query
```bash theme={null}
voiceflow kb query --quesiton "How does feature X work?" --model gpt-4
```
# Authentication
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/overview/authentication
Authenticate with Voiceflow for CLI access.
## Voiceflow API Key
`voiceflow-cli` uses Voiceflow APIs. To interact with your Voiceflow projects you will need a [Voiceflow API Key](https://docs.voiceflow.com/reference/authentication). You can get your API Key in your Voiceflow project > Settings page. You can pass the API Key to the CLI using the `--voiceflow-api-key` flag or by setting the `VF_API_KEY` environment variable. `voiceflow-cli` also works with `.env` files. You can create a `.env` file in the root of your project and add the `VF_API_KEY` variable to it.
The `voiceflow-cli` source code is open source, you can check it out [here](https://github.com/xavidop/voiceflow-cli) to learn more about the actions the tool performs.
## Base URL
The base URL for the Voiceflow API is `https://..voiceflow.com`. The default value is without subdomain: `https://.voiceflow.com`. If you are using a different Voiceflow environment, you can pass the subdomain using the `--voiceflow-subdomain` flag.
## Open AI API Key
`voiceflow-cli` uses Open AI APIs. To interact with Open AI you will need an API Key. You can get your API Key in your Open AI account. You can pass the API Key to the CLI using the `--openai-api-key` flag or by setting the `OPENAI_API_KEY` environment variable. `voiceflow-cli` also works with `.env` files. You can create a `.env` file in the root of your project and add the `OPENAI_API_KEY` variable to it.
# Install
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/overview/cli-install
Install the Voiceflow CLI on your machine.
You can use `voiceflow-cli` by installing a pre-compiled binary (in several ways), using Docker, or compiling it from source. In the below sections, you can find the steps for each approach.
## Install a pre-compiled binary
### homebrew tap
Install the Voiceflow CLI:
```sh theme={null}
brew install xavidop/tap/voiceflow
```
### snapcraft
```sh theme={null}
sudo snap install voiceflow
```
### aur
```sh theme={null}
yay -S cxcli-bin
```
### scoop
```powershell theme={null}
scoop bucket add voiceflow https://github.com/xavidop/scoop-bucket.git
scoop install voiceflow
```
### chocolatey
```powershell theme={null}
choco install voiceflow
```
### apt
```sh theme={null}
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
```
### yum
```sh theme={null}
echo '[voiceflow]
name=Voiceflow CLI Repo
baseurl=https://yum.fury.io/xavidop/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/voiceflow.repo
sudo yum install voiceflow
```
### nix
#### nixpkgs
```bash theme={null}
nix-env -iA voiceflow
```
!!! info\
The [package in nixpkgs](https://github.com/NixOS/nixpkgs/blob/main/pkgs/tools/misc/voiceflow/default.nix) might be slightly outdated, as it is not updated automatically. Use our NUR to always get the latest updates.
#### nur
First, you'll need to add our [NUR](https://github.com/xavidop/nur) to your nix configuration.\
You can follow the guides [here](https://github.com/nix-community/NUR#installation).
Once you do that, you can install the packages.
```nix theme={null}
{ pkgs, lib, ... }: {
home.packages = with pkgs; [
nur.repos.xavidop.voiceflow
];
}
```
### deb, rpm and apk packages
Download the `.deb`, `.rpm` or `.apk` packages from the \[OSS releases page]\[releases] and install them with the appropriate tools.
### go install
```sh theme={null}
go install github.com/xavidop/voiceflow-cli@latest
```
### bash script
```sh theme={null}
curl -sfL https://voiceflow.xavidop.me/static/run | bash
```
#### Additional Options
You can also set the `VERSION` variable to specify\
a version instead of using latest.
You can also pass flags and args to voiceflow-cli:
```bash theme={null}
curl -sfL https://voiceflow.xavidop.me/static/run |
VERSION=__VERSION__ bash -s -- version
```
!!! tip\
This script does not install anything, it just downloads, verifies and runs voiceflow-cli. Its purpose is to be used within scripts and CIs.
### manually
Download the pre-compiled binaries from the \[releases page]\[releases] and copy them to the desired location.
## Verifying the artifacts
### binaries
All artifacts are checksummed, and the checksum file is signed with \[cosign]\[].
1. Download the files you want along with the `checksums.txt`, `checksum.txt.pem`, and `checksums.txt.sig` files from the \[releases]\[releases] page:
```sh theme={null}
wget https://github.com/xavidop/voiceflow-cli/releases/download/__VERSION__/checksums.txt
wget https://github.com/xavidop/voiceflow-cli/releases/download/__VERSION__/checksums.txt.sig
wget https://github.com/xavidop/voiceflow-cli/releases/download/__VERSION__/checksums.txt.pem
```
2. Verify the signature:
```sh theme={null}
COSIGN_EXPERIMENTAL=1 cosign verify-blob \
--cert checksums.txt.pem \
--signature checksums.txt.sig \
checksums.txt
```
3. If the signature is valid, you can then verify the SHA256 sums match with the downloaded binary:
```sh theme={null}
sha256sum --ignore-missing -c checksums.txt
```
### docker images
Our Docker images are signed with \[cosign]\[].
Verify the signatures:
```sh theme={null}
COSIGN_EXPERIMENTAL=1 cosign verify xavidop/voiceflow
```
!!! info\
The `.pem` and `.sig` files are the image `name:tag`, replacing `/` and `:` with `-`.
## Running with Docker
You can also use `voiceflow-cli` within a Docker container.\
To do that, you'll need to execute something more-or-less like the examples below.
Registries:
* [`xavidop/voiceflow`](https://hub.docker.com/r/xavidop/voiceflow)
* [`ghcr.io/xavidop/voiceflow`](https://github.com/xavidop/voiceflow-cli/pkgs/container/voiceflow)
Example usage:
```sh theme={null}
docker run --rm \
xavidop/voiceflow voiceflow version
```
Note that the image will almost always have the last stable Go version.
If you need other packages and dependencies, you are encouraged to keep your own image.
## Compiling from source
If you just want to build from source for whatever reason, follow these steps:
**clone:**
```sh theme={null}
git clone https://github.com/xavidop/voiceflow-cli
cd voiceflow-cli
```
**get the dependencies:**
```sh theme={null}
go mod tidy
```
**build:**
```sh theme={null}
go build -o voiceflow .
```
**verify that it works:**
```sh theme={null}
./voiceflow version
```
# FAQ
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/overview/faq
Frequently asked questions about Voiceflow CLI and supported features.
## How does it work?
`voiceflow-cli` has three main purposes:
1. Make the interaction with your Voiceflow agents from your laptop or your continuous integration pipelines easier than ever
2. Create testing tools that will help users build their Voiceflow agent
## Who is `voiceflow-cli` for?
`voiceflow-cli` is primarily for software engineering teams who are currently using Voiceflow. It is recommended for machine learning engineers that usually work with LLMs, STT, TTS, NLU and NLP technologies.
## What kind of machines/containers do I need for the `voiceflow-cli`?
You'll need either: a bare-metal host (your own, AWS i3.metal or Equinix Metal) or a VM that supports nested virtualization such as those provided by Google Cloud, Azure, AWS, DigitalOcean, etc. or a Linux or Windows container.
## When will Jenkins, GitLab CI, BitBucket Pipeline Runners, Drone or Azure DevOps be supported?
For the current phase, we're targeting GitHub Actions because it has fine-grained access controls and the ability to schedule exactly one build to a runner. The other CI systems will be available soon.
That said, if you're using these tools within your organization, we'd like to hear from you.\
So feel free to reach out to us if you feel `voiceflow-cli` would be a good fit for your team.
Feel free to contact us at: [xavierportillaedo@gmail.com](mailto:xavierportillaedo@gmail.com)
## What kind of access is required in my Voiceflow project?
Refer to the Authentication page [here](/developer-tools/voiceflow-cli/overview/authentication)
## Can voiceflow-cli be used on public repos?
Yes, `voiceflow-cli` can be used on public and private repos.
## What's in the Container image and how is it built?
The Container image contains uses `alpine:latest` and the `voiceflow-cli` installed on it.
The image is built automatically using GitHub Actions and is available on a container registry.
## Is ARM64 supported?
Yes, `voiceflow-cli` is built to run on both Intel/AMD and ARM64 hosts. This includes a Raspberry Pi 4B, AWS Graviton, Oracle Cloud ARM instances and potentially any other ARM64 instances that support virtualisation.
## Are Windows or macOS supported?
Yes, in addition to Linux, Windows and macOS are also supported platforms for `voiceflow-cli` at this time on a AMD64 or ARM64 architecture.
## Is `voiceflow-cli` free and open-source?
`voiceflow-cli` is an open source tool, however, it interacts with Voiceflow, so a Voiceflow account is required.
The website and documentation are available on GitHub and we plan to release some open source tools in the future for voiceflow customers.
# Roadmap
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/overview/roadmap
Future plans and upcoming features for Voiceflow CLI.
`voiceflow-cli` is in active development. The core product is functioning.
Our goal with the tool is to prove that there's market fit for a solution like this, and if so, we'll invest more time in automation, user experience, more features.
For now, if you're interested in participating and giving feedback, we believe `voiceflow-cli` already solves pain at this stage.
Shipped:
* [x] Available in homebrew, scoop, choco, winget package managers
* [x] Documentation updated
* [x] Test execution
* [x] Container image available for multiple architectures
* [x] SBOM files created
* [x] Artifacts uploaded, signed and available on GitHub
Coming soon:
* [ ] Continuous integration support (GitHub Action, CircleCI, etc.)
* [ ] Add more Voiceflow APIs
# Fetching transcripts
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/transcripts/fetching
Export conversation transcripts with filtering and analysis options.
With the `voiceflow-cli` you can fetch the transcripts of your project. This is useful when you want to analyze the conversation flow of your agent. The `voiceflow-cli` has 2 commands that allow you to fetch the transcripts from your terminal:
## Fetching all transcripts
To fetch all transcripts, you need to know the `agent-id` of the agent you want to fetch the transcripts from. You can find that information in the Voiceflow Agent section under your Agent Settings on [voiceflow.com](https://voiceflow.com).
```sh theme={null}
voiceflow transcript fetch-all --agent-id
```
### Time Range Filters
* Start Time
* Flag: `--start-time, -s`
* Format: ISO-8601
* Default: Current date minus one month
* Example: `--start-time 2024-01-01T00:00:00Z`
* End Time
* Flag: `--end-time, -e`
* Format: ISO-8601
* Default: Current date
* Example: `--end-time 2024-02-01T00:00:00Z`
### Content Filters
* Tag Filter
* Flag: `--tag, -g`
* Description: Filter transcripts by specific tag
* Default: Empty (no filter)
* Example: `--tag production`
* Range Filter
* Flag: `--range, -r`
* Description: Filter transcripts by date range
* Default: Empty (no filter)
* Example: `--range Yesterday`
### Example Usage
```bash theme={null}
voiceflow transcript fetch-all \
--agent-id abc123 \
--start-time 2024-01-01T00:00:00Z \
--end-time 2024-02-01T00:00:00Z \
--tag production \
--range Yesterday \
--output-directory ./my-transcripts
```
## Fetching a specific transcript
To fetch a specific transcript, you need to know the `transcript-id` of the transcript you want to fetch. You can find the `transcript-id` in the Voiceflow Transcript section.
```sh theme={null}
voiceflow transcript fetch --agent-id --transcript-id
```
# Transcripts
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/transcripts/index
View turn-by-turn conversation records to understand agent performance.
## What is this?
The goal of the Transcripts is to give you and your team an understanding of where your assistant was successful in helping your users, and where it can be improved.
Each transcript provides a turn-by-turn record of each user interaction, what utterances they used, and what intents they hit along the way.
## Reference
The `voiceflow-cli` has a command that allows you to interact with transcripts from your terminal or from your CI pipelines.
To execute know more, you can run the `voiceflow transcript` command. For the usage, please refer to this [page](/developer-tools/voiceflow-cli/command-line-usage/voiceflow-transcript).
# Transform transcripts into tests
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/transcripts/transcripts-to-test
Convert transcripts into reusable test cases for your test suites.
## Overview
Convert a Voiceflow transcript into a reusable [test case](/developer-tools/voiceflow-cli/automated-testing/tests).
## Command
```bash theme={null}
voiceflow transcript to-test [flags]
```
## Parameters
### Required flags
* `--agent-id`: Voiceflow Agent ID
* `--transcript-id`: ID of the transcript to convert
### Optional flags
* `--output-file`: Path to save the generated test (default: test.yaml)
* `--test-name`: Name for the generated test
* `--test-description`: Description for the generated test
## Examples
### Basic usage
```bash theme={null}
voiceflow transcript to-test \
--agent-id your-agent-id \
--transcript-id transcript-123
```
### Full example with options
```bash theme={null}
voiceflow transcript to-test \
--agent-id your-agent-id \
--transcript-id transcript-123 \
--output-file my-test.yaml \
--test-name "Payment Flow Test" \
--test-description "Validates the payment processing dialogue"
```
## Output
The command generates a YAML file containing:
* Test metadata (name, description)
* User interactions
* Expected agent responses
* Validation rules
# Troubleshooting
Source: https://docs.voiceflow.com/developer-tools/voiceflow-cli/troubleshooting
Resolve common Voiceflow CLI issues and get support.
## Project not found
Make sure that the Voiceflow project exists and is accessible by the user and API Key that is in used corresponds to that project. If the project is not found, the CLI will return an error message.
# Billing overview
Source: https://docs.voiceflow.com/documentation/account-management/billing
If you need help with a billing query, [click here to contact support](mailto:support@voiceflow.com). If you are an Enterprise customer, please contact your account manager.
Your Voiceflow bill is made up of a monthly plan fee, optional add-ons like editor seats and phone numbers, and credit-based usage. Everything is billed at the organization level, and the plan you pick determines which features you can use and how many credits you get each month. Credits are shared across all workspaces in your organization.
You can view current pricing for plans, add-ons, and credit bundles inside Voiceflow by opening **Plans and Billing** tab from your [Voiceflow dashboard](https://creator.voiceflow.com).
## Plans
Your plan controls which Voiceflow features you have access to and sets your monthly credit allotment. Voiceflow offers four plans:
* **Free** is designed for trying out Voiceflow. It has limited features and a one-time credit grant that does not renew, so it isn't suitable for production usage.
* **Pro** is designed for individual builders. It includes access to all LLM models and a higher agent limit than Free.
* **Business** is designed for growing teams. It includes additional features like LLM fallback models and priority support.
* **Enterprise** is designed for organizations running large-scale workloads or requiring advanced security and compliance features. Enterprise plans include unlimited product usage, single sign-on, private cloud hosting, and custom credit allotments.
You can compare all plan features, upgrade, or change your plan directly from inside the **Plans** tab in **Plans and Billing**.
## Add-ons
Add-ons extend your plan with additional capacity. They're billed monthly alongside your plan subscription and managed from the **Add-ons** tab in **Plans and Billing**.
* **Editor seats** let additional team members edit agents in your workspace. Every paid plan includes some free editor seats, and you can purchase more as needed. A single editor seat provides access to all agents in the workspace, though you can restrict editors to specific projects if needed. Viewers are free and unlimited on all plans.
* One **Voiceflow phone number** per workspace is included with your plan. You can add additional phone numbers for testing or production purposes as an add-on.
* Each plan has a **concurrent calls** limit - the number of calls that agents in your workspace can send and/or receive simultaneously. This limit can be increased through the concurrent calls add-on. Note that this limit does not apply to chat or API sessions.
## Credits
Credits are how Voiceflow charges for agent usage. Your agent consumes credits when it performs actions like generating AI responses and making phone calls. Paid plans include a monthly credit allotment that resets at the start of each billing cycle, and credits are shared across all workspaces in your organization. The Free plan includes a one-time credit grant that does not renew.
You can monitor your current credit usage in two places:
* The **credit usage box** at the bottom-left of your workspace
* The **Plans and Billing** section of your workspace
If you're running low on credits, you can upgrade to a higher plan or credit bundle, or enable auto top-ups. Auto top-ups automatically purchase additional credits when you hit zero, so your agents aren't interrupted mid-month. You can toggle this setting on from the **Plans** page.
You can see a full breakdown of all actions that are charged credits on the [credits pricing table](/documentation/account-management/billing/credits-pricing-table).
## Managing your subscription
You can handle most billing actions yourself from **Plans and Billing** in the workspace sidebar. From there you can compare and change plans, manage add-ons, update your payment method, download invoices, and more.
For a full walkthrough of each self-serve action, see [managing your subscription](/documentation/account-management/billing/managing-your-subscription).
## Enterprise billing
Enterprise customers are billed per their contract and work with a dedicated account manager rather than the self-serve billing flow. Contact your account manager with questions.
# Credits pricing table
Source: https://docs.voiceflow.com/documentation/account-management/billing/credits-pricing-table
How credits are consumed across your agent's LLM, voice, and orchestration usage.
Credits are the currency that powers your Voiceflow agent. Every interaction, from chat messages to LLM calls to voice minutes, consumes a certain number of credits depending on the vendor and model you use. The tables below show current credit costs so you can estimate usage and plan accordingly.
# Managing your subscription
Source: https://docs.voiceflow.com/documentation/account-management/billing/managing-your-subscription
How to manage your Voiceflow plan, add-ons, payment method, invoices, and other billing settings.
You can manage almost everything about your Voiceflow subscription directly in the tool. Open **Plans and Billing** from the workspace sidebar to get started. You can also reach it by clicking **Manage** on the credit usage toast at the bottom-left of your workspace.
## Changing your plan
Open **Plans and Billing** → **Plans** from the [Voiceflow dashboard](https://creator.voiceflow.com) to see a side-by-side comparison of all available plans and what's included in each. Click the plan you want and follow the prompts to switch.
## Managing add-ons
The **Add-ons** tab lets you adjust editor seats and Voiceflow phone numbers. Use the **+** and **−** buttons next to each add-on to increase or decrease your allocation. Changes apply to your subscription and are reflected in your next billing cycle.
## Changing your credit bundle
If your included credits aren't enough, you can upgrade your credit bundle. Open **Plans and Billing** → **Billing**, click **Manage** in the subscription overview, then click **Edit credit bundle** next to **Plan cost**. Pick the bundle size you want and confirm.
## Enabling auto top-ups
Auto top-ups prevent your agents from running out of credits mid-month. When enabled, Voiceflow automatically purchases additional credits when your balance hits zero. Nothing is charged in advance.
To turn this on, open **Plans and Billing** → **Billing**, click **Manage** in the subscription overview, and click **Enable** next to **Usage based billing**. Set the dollar amount you want added each time your credits run out and confirm. You can adjust the amount or disable auto top-ups at any time from the same modal.
## Updating billing details
All billing settings live in the **Billing** tab inside **Plans and Billing**.
Your **billing email** receives invoices, payment receipts, renewal reminders, and failed-payment alerts. It can be different from your account login email. Click **Edit** in the **Billing email** block to change it.
To update your **payment method**, click **Edit** in the **Payment information** block and enter your card details. Your **billing address** appears on every invoice and can be updated in the **Billing address** block at the bottom of the tab.
## Downloading invoices
In the **Billing** tab, scroll to **Billing history** to find past invoices. Click **View** next to any date to open and download the invoice as a PDF. Use **Load more** to access older records.
## Canceling your subscription
Open **Plans and Billing** → **Billing**, click **Manage** in the subscription overview, then click **Cancel subscription** and follow the confirmation prompts. You keep access to your paid features until the end of your current billing period. After that, your account reverts to the free tier. Past invoices remain accessible in your billing history.
## What requires contacting support
Most billing actions are self-serve, but a few situations require reaching out:
* **Enterprise** customers manage their subscription through their dedicated account manager.
* For custom invoicing, tax exemptions, procurement, refund requests, or disputed charges, email [support@voiceflow.com](mailto:support@voiceflow.com).
# Workspaces
Source: https://docs.voiceflow.com/documentation/account-management/collaboration
Organize projects and collaborate with your team.
![Cover Placeholder]()
A workspace is a container for your projects. Everyone you invite to a workspace can see all the projects inside it, so think of workspaces as team boundaries. Your plan determines how many workspaces you can create.
## Organizing your workspace
When you log in to Voiceflow, you'll land on your workspace. You can organize projects into folders, and customize each project's icon, name, and description by hovering over it and clicking the three-dot menu. From there you can also export the project as a `.vf` file or share a clone link that lets others copy your agent.
To switch between workspaces, click your workspace name in the top left corner of the dashboard. From here, you can also create new workspaces.
## Inviting team members
In the **Members** section of your workspace, you can manage collaborators and permissions. You can invite people by entering their email address or by copying a magic link to share directly. Magic links expire after 72 hours.
When inviting someone, you choose their role. You can change a team member's role later from the same menu, though you can only assign roles at or below your own access level.
### Roles
Voiceflow workspaces have five different roles that users may be assigned to:
* **Owner** has full control over the workspace, including billing, settings, and member management. The person who creates a workspace is automatically its owner. On Enterprise plans, owners control all workspaces in the organization.
* **Admin** can do everything except transfer ownership. Admins manage workspace settings, invite and remove members, and edit all projects.
* **Editor** can build and publish agents, manage project settings, and import or export projects. Editors cannot invite new members or change workspace settings.
* **Viewer** can see projects and leave comments, but cannot make edits. Viewer seats are free and unlimited on all plans.
* **Billing** has the same access as a viewer, plus the ability to manage billing and subscription settings.
## Project-level permissions
By default, workspace members have the same access to every project. But you can give viewers or billing users edit access to specific projects without upgrading their workspace role.
To manage project access, hover over a project card, click the three-dot menu, and select **Manage access**. You can only add people who are already workspace members.
Keep in mind that viewers with project-level edit access count as editors for [billing purposes](/documentation/account-management/billing).
# Behaviour
Source: https://docs.voiceflow.com/documentation/build/behaviour
Fine tune your agent for optimal performance.
The Behaviour tab controls your agent's default model, session handling, and fallback responses. Settings here apply project-wide - individual playbooks can override model settings where needed.
Some settings differ depending on whether you're building a **Chat** or **Voice** project. Differences are noted below.
## Model & reasoning
### Default model
The LLM that powers your agent. Select your primary model, temperature, and max token limit. These can be overridden at the playbook level.
![Default Model Docs]()
* **Model** - your primary LLM (eg: Claude 4.6 Sonnet, Gemini 2.0 Flash)
* **Temperature** - controls how creative or deterministic responses are. Lower values (closer to 0) produce more consistent output, higher values (closer to 1) introduce more variation.
* **Max tokens** - maximum response length per turn
### Memory
How many conversation turns the agent keeps in context (10-100, default 50). Higher values give the agent more history to work with but increase latency and token usage.
Memory is stored in the `{vf_memory}` variable. Most agents work well between 25-50 turns. If you're hitting token limits or noticing slow responses, try reducing this value.
![Max Memory Docs]()
Conversation memory that exceeds this turn count isn't forgotten completely. Rather it's condensed and summarized so your agent still has access to critical information, while keeping its context window small for optimal performance.
### Faster processing
Enables faster processing for supported models. Uses more credits. Off by default. When on, you can check any model dropdown in Voiceflow to see supported models.
![Priority Processing Docs]()
### Outage protection
Voiceflow automatically detects model provider outages and allows you to switch to a fallback LLM provider if your primary provider goes down. Configure a fallback for each provider independently - for example, route OpenAI failures to Claude, and Anthropic failures to GPT-4.1.
![Outage Protection Docs]()
**Note:** your agent can perform very differently when being powered by different models.
### Timezone
Sets the timezone for the `{vf_now}` and other built-in time variables, and any time-aware behavior.
![Timezone Docs]()
You can think of this as your agents internal clock. You also have access to the built-in variable`{vf_user_timezone}`.
## Voice output
Voice output is also available in **chat** projects as Voiceflow's chat widget handles multi-modal usecases with voice mode.
### Provider, voice, and model
Select your TTS provider (eg: ElevenLabs, Cartesia, Rime, Google Chirp, Amazon, Microsoft), choose a voice, and pick the synthesis model. You can also connect a custom voiceID from ElevenLabs if you have one.
### Sync audio and text output
Streams TTS in real time, keeping audio synced with the text output. Off by default.
![Voice Output Docs]()
### Voice tuning
Fine-tune how the voice sounds:
* **Similarity boost** (0-1, default 0.75) - how closely the output adheres to the source voice. Higher values are more accurate but may reduce naturalness.
* **Talking speed** (0.7-1.3, default 1.00) - playback speed of the voice.
* **Stability** (0-1, default 0.50) - higher values produce more consistent output across regenerations but can sound more monotone.
![Talking Speed Docs]()
### Pronunciation dictionary
The pronunciation dictionary rewrites words or phrases in your agent's responses before they're sent to text-to-speech. This ensures correct pronunciation of names, places, or technical terms:
* enforce brand pronunciations (`nginx` → `engine x`)
* expand abbreviations (`Dr.` → `Doctor`)
* spell out acronyms (`TTS` → `Text to Speech`)
* normalize locale spellings (`colour` → `color`)
Matching is case-insensitive and respects whole-word boundaries. The JSON view is used for bulk editing of large dictionaries.
For finer control you can use **TTS provider-specific phonetic markup** in the `to` field.
* **Cartesia** uses a proprietary IPA syntax `<>` ([guide](https://docs.cartesia.ai/build-with-cartesia/capability-guides/custom-pronunciations))
* **ElevenLabs** (Turbo v2 / Multilingual v2 only) uses SSML `` tags with either IPA or CMU Arpabet ([guide](https://elevenlabs.io/docs/overview/capabilities/text-to-speech/best-practices#pronunciation))
![Pronunciation]()
### Background audio and audio cues
Audio cues is also available in **chat** projects as Voiceflow's chat widget handles multi-modal usecases with voice mode.
Add optional ambient audio or audio effects during conversations.
1. **Background audio** - ambient audio that plays in the background for the duration of a call
2. **Audio cue** - a subtle sound effect that plays when the agent starts thinking
![Audio Cues Docs]()
## Voice input
Voice input is also available in **chat** projects as Voiceflow's chat widget handles multi-modal usecases with voice mode.
### Provider, model, and language
Select your STT provider (eg: Deepgram, Gladia, Cartesia, AssemblyAI, Google), transcription model (eg: Flux), and language.
We highly recommend using the **Deepgram Flux** model. It's incredibly strong at understanding when the user is done talking, which can massively reduced the perceived latency of voice conversations.
### Keywords
Comma-separated list of words to boost recognition for - proper nouns, product names, or industry-specific terms that standard transcription might miss.
**Good keyword examples:**
* **Product and company names**: Brand names, service names, competitor names
* **Industry-specific terminology**: Medical terms (`tretinoin`, `diagnosis`)
* **Multi-word phrases**: Common phrases in your domain (`account number`, `customer service`)
* **Proper nouns**: Names, brands, titles with appropriate capitalization (`Deepgram`, `iPhone`, `Dr. Smith`)
![Voice Input Docs]()
### End-of-turn detection
Controls when the agent decides the user has finished speaking:
* **End-of-turn confidence** (0.5-0.9, default 0.60) - minimum confidence score required to close a turn. Lower values make the agent more responsive, higher values wait for more certainty.
* **End-of-turn timeout** (0.5-5s, default 0.60s) - how long to wait after the user stops speaking before closing the turn, regardless of confidence. Increase this if users are getting cut off mid-sentence.
![End Of Turn Confidence Docs]()
### Keypad input
Allow users to input digits via keypad (DTMF) during a call. When enabled, configure:
Keypad input is only available in **voice** projects.
* **Timeout** (0-10s, default 2) - how long to wait before processing the input. Set to 0 to process only after a delimiter is pressed.
* **Delimiter** - the key that signals input is complete. Options: Pound (#) or Star (\*). If both a delimiter and timeout are set, whichever comes first triggers processing.
![Keypad Input Docs]()
## Session & timeout
### Session timeout (Chat projects)
Time in minutes before an inactive chat session ends (1-2,880 min (2 days), default 15 minutes). Toggle off to keep sessions alive indefinitely.
![Timeout Chat Docs 2]()
### Session timeout (Voice projects)
How long to wait before a call is automatically ended due to inactivity (10-300 seconds, default 60).
![Timeout Voice Docs]()
### Chat persistence
Controls how and whether chat history is stored between sessions.
Chat persistence is only available in **chat** projects.
* **Never forget** - conversation history persists indefinitely. The user can return at any time and pick up where they left off.
* **Forget after all tabs are closed** - history is cleared when the user closes all browser tabs with the chat widget. Reopening starts a fresh session.
* **Forget after page refresh** - history is cleared every time the page reloads. Each page visit is a new conversation.
![Chat Persistence]()
## Events
Events let you trigger agent behavior from outside the conversation - a webhook, a CRM update, a system alert, or any external signal your application sends.
![Events Behaviour Docs]()
To create an event, click **New event**, give it a name, and choose its behaviour:
| Behaviour | When to use |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Continue conversation** | The event updates user state without changing the conversation state. The agent keeps doing whatever it was doing. |
| **Return to agent** | The event hands control back to the agent to decide what to do next. Use this when the event changes context and the agent needs to re-evaluate - for example, a priority flag being set mid-conversation. |
| **Run workflow** | The event triggers a specific workflow directly. Use this when you know exactly what should happen - for example, an order status change should always kick off the order update flow. |
## Fallback
![No Match Reply Docs]()
### Global no-match
How the agent responds when it can't match any skill, user intention, or knowledge base result. Click **Edit** to configure:
* **Generative** - provide a prompt that tells the agent how to handle the situation. The agent generates a response dynamically based on your instructions.
* **Scripted** - write a fixed response that's sent every time. Use this when you want exact control over the wording.
If you're building a fully agentic project, you don't need to worry about this behaviour setting. It's really for experiences that don't rely on an agent to handle un-happy path dialogs.
### Global no-reply
How the agent responds when the user says nothing. Off by default. When enabled, click **Edit** to configure:
* **Generative** - provide a prompt for how to re-engage the user (eg: "Ask them if they're still there, or nudge them toward the conversation's goal").
* **Scripted** - write a fixed follow-up message.
* **Inactivity time** - how many seconds of silence before the agent responds (default 10).
* **Max no-reply messages per turn** - how many times the agent will follow up before ending the session (default 5). For example, with 10 seconds and 5 attempts, the session ends after 50 seconds of total silence.
# Personas
Source: https://docs.voiceflow.com/documentation/build/data/personas
Test your agent as a specific kind of user.
Personas let you start a conversation with specific [variable](/documentation/build/data/variables) values already in place. They're useful for testing how your agent handles different customer types or account states without setting things up by hand each time.
You can create a new persona or use an existing persona in three places:
* **Run panel**: pick a persona when manually testing your agent with the **Run** button.
* **Prototype links**: pick a persona when generating a prototype link, and it applies for anyone who opens the link.
* [**Tests**](/documentation/measure/tests): click **Add persona** at the top of a test to run it as a specific persona every time.
Personas can't be used when you embed the chat widget on a live site. They're meant for testing, not for real users.
## Personas and environments
Personas are scoped to the [environment](/documentation/deploy/environments/overview) they were created in. Cloning an environment duplicates its personas. Merging an environment into `Main` replaces the personas there with the ones from the source.
# PII redaction
Source: https://docs.voiceflow.com/documentation/build/data/pii-redaction
Automatically redact personally identifiable information from transcripts.
The PII redaction feature must be subscribed to by [contacting our sales team](mailto:sales@voiceflow.com).
![PII Redaction]()
PII redaction automatically detects and removes personally identifiable information from your production transcripts. When enabled, data like names, email addresses, phone numbers, and financial details are replaced with generic markers (eg: `[NAME]`, `[EMAIL_ADDRESS]`) before transcripts are stored. Sensitive user information never persists in your conversation logs.
## How it works
PII is detected using a machine learning model hosted within Voiceflow's infrastructure. Your data is never sent to any third-party service during the redaction process.
Key behaviours:
* **Production only.** Redaction applies only to production conversations. Development and test conversations are not redacted, so you can debug freely.
* **Not retroactive.** Enabling redaction does not affect existing transcripts. Disabling it does not unredact previously redacted transcripts. Only future conversations are affected.
* **Structure preserved.** The overall structure of your traces and requests remains the same. Only the content of specific text properties is modified.
## Enabling PII redaction
You can unlock the PII redaction feature by subscribing the applicable add-on. To do so, [contact our sales team](mailto:sales@voiceflow.com). If you're on an enterprise plan, reach out to your account manager to have the feature enabled for your organization.
Open the project that you'd like to redact PII from. Then, head to **Settings → Security** and enable the PII redaction feature.
![Clean Shot 2026 05 01 At 18 08 41@2x]()
PII redaction is a project-level setting. If you'd like to redact PII from multiple projects, enable it in **Settings → Security** on each individual project.
## Viewing unredacted transcripts
After redaction is enabled, you can temporarily view the original unredacted version of a transcript using the toggle in the transcript detail view. This is intended for debugging purposes.
Unredacted transcripts are only available for **48 hours** after the conversation takes place. After that, the original data is permanently deleted and cannot be recovered.
## What gets redacted
PII redaction scans both your agent's responses (traces) and user inputs (requests), covering a wide range of PII types across different data structures.
### Detected PII types
The redaction system detects over 35 types of personally identifiable information:
| Category | Examples |
| ------------------ | -------------------------------------------------------------------- |
| **Identity** | Names, date of birth, age, gender, marital status, nationality |
| **Contact** | Email addresses, phone numbers, physical addresses, IP addresses |
| **Financial** | Credit card numbers, bank accounts, routing numbers, CVV codes |
| **Government IDs** | Social Security numbers, driver's license, passport numbers, tax IDs |
| **Health** | Medical conditions, medications, blood type, medical procedures |
| **Authentication** | Usernames, passwords, PINs |
| **Other** | Organization names, URLs, vehicle identifiers, device IDs |
### Protection methods
The system uses four approaches depending on the type of content:
| Method | What it does | Example |
| -------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| **Censor** | Replaces detected PII with markers like `[NAME]` or `[EMAIL_ADDRESS]` | `"Hi John"` → `"Hi [NAME]"` |
| **Erase** | Sets the property to an empty string (used for content that can't be selectively redacted) | Audio URLs are removed entirely |
| **Override** | Replaces the value with a safe placeholder | Image URLs are replaced with a placeholder image |
| **Censor rich text** | Strips rich text formatting and replaces content with redacted plain text | Slate content is flattened and censored |
### Trace data
Traces represent the messages and content your agent sends during a conversation, including text responses, cards, carousels, and media. PII redaction processes each trace type differently depending on the properties it contains.
**Modified properties:**
* `payload.message`: Censor redaction
* `payload.slate.content`: Censor rich text redaction
* `payload.audio.src`: Erase redaction
```json Before redaction theme={null}
{
"type": "text",
"payload": {
"audio": {
"message": "Hi, my name is John Smith and my email is john@email.com",
"src": "https://example.com/audio/user-message.mp3"
},
"slate": {
"id": 1,
"content": [
{
"children": [
{ "text": "Hi, my name is John Smith and my email is john@email.com" }
]
}
]
}
}
}
```
```json After redaction theme={null}
{
"type": "text",
"payload": {
"audio": {
"message": "Hi, my name is [NAME] and my email is [EMAIL_ADDRESS]",
"src": ""
},
"slate": {
"id": 1,
"content": [
{
"children": [
{ "text": "Hi, my name is [NAME] and my email is [EMAIL_ADDRESS]" }
]
}
]
}
}
}
```
**Modified properties:**
* `payload.message`: Censor redaction
* `payload.src`: Erase redaction
```json Before redaction theme={null}
{
"type": "speak",
"payload": {
"type": "message",
"message": "Hello Sarah, your appointment at 123 Main Street is confirmed",
"src": "https://example.com/audio/response.mp3"
}
}
```
```json After redaction theme={null}
{
"type": "speak",
"payload": {
"type": "message",
"message": "Hello [NAME], your appointment at [LOCATION_ADDRESS] is confirmed",
"src": ""
}
}
```
**Modified properties:**
* `payload.title`: Censor redaction
* `payload.description.text`: Censor redaction
* `payload.description.slate`: Censor rich text redaction
* `payload.imageUrl`: Override redaction
* `payload.buttons[].name`: Censor redaction
* `payload.buttons[].request.payload.label`: Censor redaction
```json Before redaction theme={null}
{
"type": "cardV2",
"payload": {
"title": "Contact John Smith",
"description": {
"text": "Call John at 555-123-4567"
},
"imageUrl": "https://example.com/photos/john-profile.jpg",
"buttons": [
{
"name": "Call John",
"request": {
"type": "path",
"payload": { "label": "Contact John Smith" }
}
}
]
}
}
```
```json After redaction theme={null}
{
"type": "cardV2",
"payload": {
"title": "Contact [NAME]",
"description": {
"text": "Call [NAME] at [PHONE_NUMBER]"
},
"imageUrl": "https://cdn.voiceflow.com/assets/pii_redaction_placeholder_img.png",
"buttons": [
{
"name": "Call [NAME]",
"request": {
"type": "path",
"payload": { "label": "Contact [NAME]" }
}
}
]
}
}
```
Each card in the carousel is processed the same way as a CardV2 trace.
**Modified properties (per card):**
* `payload.cards[].title`: Censor redaction
* `payload.cards[].description.text`: Censor redaction
* `payload.cards[].description.slate`: Censor rich text redaction
* `payload.cards[].imageUrl`: Override redaction
* `payload.cards[].buttons[].name`: Censor redaction
* `payload.cards[].buttons[].request.payload.label`: Censor redaction
```json Before redaction theme={null}
{
"type": "carousel",
"payload": {
"layout": "Carousel",
"cards": [
{
"title": "Dr. Sarah Johnson",
"description": {
"text": "Cardiology specialist at Boston Medical Center"
},
"imageUrl": "https://example.com/photos/dr-sarah.jpg",
"buttons": [
{
"name": "Book with Dr. Johnson",
"request": {
"type": "Action",
"payload": { "label": "Schedule with Sarah Johnson" }
}
}
]
},
{
"title": "Dr. Michael Chen",
"description": {
"text": "Located at 456 Health Ave, contact at mike@clinic.com"
},
"imageUrl": "https://example.com/photos/dr-chen.jpg"
}
]
}
}
```
```json After redaction theme={null}
{
"type": "carousel",
"payload": {
"layout": "Carousel",
"cards": [
{
"title": "Dr. [NAME]",
"description": {
"text": "Cardiology specialist at [ORGANIZATION]"
},
"imageUrl": "https://cdn.voiceflow.com/assets/pii_redaction_placeholder_img.png",
"buttons": [
{
"name": "Book with Dr. [NAME]",
"request": {
"type": "Action",
"payload": { "label": "Schedule with [NAME]" }
}
}
]
},
{
"title": "Dr. [NAME]",
"description": {
"text": "Located at [LOCATION_ADDRESS], contact at [EMAIL_ADDRESS]"
},
"imageUrl": "https://cdn.voiceflow.com/assets/pii_redaction_placeholder_img.png"
}
]
}
}
```
**Modified properties:**
* `payload.buttons[].name`: Censor redaction
* `payload.buttons[].request.payload.label`: Censor redaction
```json Before redaction theme={null}
{
"type": "choice",
"payload": {
"buttons": [
{
"name": "Contact Dr. Smith",
"request": {
"type": "text",
"payload": { "label": "Reach out to Dr. Smith at his office" }
}
},
{
"name": "Call Dr. Smith's office",
"request": {
"type": "text",
"payload": { "label": "Phone: 555-123-4567" }
}
}
]
}
}
```
```json After redaction theme={null}
{
"type": "choice",
"payload": {
"buttons": [
{
"name": "Contact Dr. [NAME]",
"request": {
"payload": { "label": "Reach out to Dr. [NAME] at his office" }
}
},
{
"name": "Call Dr. [NAME] office",
"request": {
"payload": { "label": "Phone: [PHONE_NUMBER]" }
}
}
]
}
}
```
**Modified properties:**
* `payload.image`: Override redaction
```json Before redaction theme={null}
{
"type": "visual",
"payload": {
"image": "https://example.com/user-photos/john-selfie.jpg",
"visualType": "image",
"device": "mobile",
"dimensions": { "width": 800, "height": 600 }
}
}
```
```json After redaction theme={null}
{
"type": "visual",
"payload": {
"image": "https://cdn.voiceflow.com/assets/pii_redaction_placeholder_img.png",
"visualType": "image",
"device": "mobile",
"dimensions": { "width": 800, "height": 600 }
}
}
```
### Request data
Requests represent user inputs sent to your agent, such as typed messages, button presses, and intent matches. These are redacted in the same way as traces to ensure PII is removed from both sides of the conversation.
**Modified properties:**
* `payload`: Censor redaction
```json Before redaction theme={null}
{
"type": "text",
"payload": "Hi, my name is Sarah Johnson and I need help with my account. You can reach me at sarah@email.com or 555-123-4567"
}
```
```json After redaction theme={null}
{
"type": "text",
"payload": "Hi, my name is [NAME] and I need help with my account. You can reach me at [EMAIL_ADDRESS] or [PHONE_NUMBER]"
}
```
**Modified properties:**
* `payload.query`: Censor redaction
* `payload.entities[].value`: Censor redaction
Intent names and entity types are preserved.
```json Before redaction theme={null}
{
"type": "intent",
"payload": {
"intent": { "name": "book_appointment" },
"query": "I want to book an appointment with Dr. Smith for John Doe on March 15th",
"entities": [
{ "name": "doctor_name", "value": "Dr. Smith" },
{ "name": "patient_name", "value": "John Doe" },
{ "name": "date", "value": "March 15th" }
]
}
}
```
```json After redaction theme={null}
{
"type": "intent",
"payload": {
"intent": { "name": "book_appointment" },
"query": "I want to book an appointment with Dr. [NAME] for [NAME] on [DATE]",
"entities": [
{ "name": "doctor_name", "value": "[NAME]" },
{ "name": "patient_name", "value": "[NAME]" },
{ "name": "date", "value": "[DATE]" }
]
}
}
```
**Modified properties:**
* `payload.label`: Censor redaction
```json Before redaction theme={null}
{
"type": "path",
"payload": {
"label": "Contact Dr. Sarah Johnson at Boston Medical"
}
}
```
```json After redaction theme={null}
{
"type": "path",
"payload": {
"label": "Contact Dr. [NAME] at [ORGANIZATION]"
}
}
```
**Modified properties:**
* `payload.message`: Censor redaction
```json Before redaction theme={null}
{
"type": "message",
"payload": {
"message": "Please send the invoice to john.smith@company.com and call me at 555-123-4567"
}
}
```
```json After redaction theme={null}
{
"type": "message",
"payload": {
"message": "Please send the invoice to [EMAIL_ADDRESS] and call me at [PHONE_NUMBER]"
}
}
```
**Modified properties:**
* `payload.label`: Censor redaction (if present)
```json Before redaction theme={null}
{
"type": "action",
"payload": {
"label": "Send confirmation email to sarah.johnson@email.com"
}
}
```
```json After redaction theme={null}
{
"type": "action",
"payload": {
"label": "Send confirmation email to [EMAIL_ADDRESS]"
}
}
```
### Debug traces
Debug traces contain technical information about your agent's operation, such as model usage, latency metrics, and navigation data. These are handled differently from regular traces using an allowlist system. All properties in `payload.metadata` are redacted by default unless explicitly allowlisted.
The following properties are preserved as-is and never redacted:
* `userID` - User identifier
* `versionID` - Version identifier
* `tools` - Tool registration and agent step data
* `model` - AI model identifiers
* `provider` - Service provider information
* `voice` - Voice configuration
* `postMultiplierTokensConsumption` - Token consumption metrics
* `variant` - Message variant information
* `code` - Execution code
* `latency` - Performance timing metrics
* `maxTokens` - Token limits
* `queryTokens` - Query token counts
* `answerTokens` - Answer token counts
* `temperature` - AI temperature settings
* `tokens` - Token counts
* `multiplier` - Token multipliers
* `nextID` - Navigation identifiers
* `diagramID` - Diagram identifiers
* `intent` - Intent information
* `confidence` - Confidence scores
* `tokensMultiplier` - Token multiplier values
* `tokensConsumption` - Token consumption data
* `nodeID` - Node identifiers
* `result` - Result data
* `status` - Status information
* `tokenConsumption` - Token consumption data
All other properties are replaced with PII detection markers or the message `[Restricted due to potential PII]`. This ensures new debug metadata properties are automatically protected until explicitly reviewed.
### Redaction examples
These quick examples show how common types of PII appear in your transcript data before and after redaction is applied:
**Text content:**
* Before: `"Hello, I'm Sarah Johnson from Acme Corp"`
* After: `"Hello, I'm [NAME] from [ORGANIZATION]"`
**Contact information:**
* Before: `"Call me at 555-123-4567 or email sarah@acme.com"`
* After: `"Call me at [PHONE_NUMBER] or email [EMAIL_ADDRESS]"`
**Address information:**
* Before: `"I live at 123 Main St, Boston, MA 02101"`
* After: `"I live at [LOCATION_ADDRESS], [LOCATION_CITY], [LOCATION_STATE] [LOCATION_ZIP]"`
## Limitations
There are a few things to keep in mind when using PII redaction. These limitations are by design to balance privacy protection with usability.
* **Development conversations are not redacted.** Only production conversations are processed.
* **Redaction is not retroactive.** Enabling or disabling PII redaction only affects future conversations.
* **Audio is erased entirely.** Audio URLs are set to empty strings because audio content cannot be selectively edited to remove only PII.
* **Images are replaced with a placeholder.** All image URLs are overridden with a standard placeholder to prevent potential PII exposure through images.
* **Detection is English only.** The PII detection model analyzes text in English.
# Secrets
Source: https://docs.voiceflow.com/documentation/build/data/secrets
Securely store sensitive information.
![Cover Placeholder]()
Secrets let you securely store sensitive information like API keys, database credentials, and encryption keys. Unlike variables, secret values are encrypted and hidden from view, keeping your credentials safe while still allowing your agent to use them.
## Creating secrets
You can create and manage secrets in **Settings** → **Secrets**. Click **New Secret** in the top right to create one.
When creating a secret, you'll provide a name, value, and visibility setting:
* **Masked** secrets are hidden by default but can be temporarily revealed by clicking on them.
* **Restricted** secrets cannot be revealed after creation. Use this for highly sensitive credentials.
You can also create secrets inline while building. Type `{` in any input field, switch to the **Secrets** tab in the dropdown, then click **Create Secret** at the bottom.
## Using secrets
Secrets work like variables but are accessed from a separate tab. In any input field within a [tool](/documentation/build/tools/api-tool), type `{` to open the dropdown, then switch to the **Secrets** tab and select the secret you need.
![Screenshot2026 02 17at4 49 22PM]()
## Managing secrets
To edit or delete a secret, click the three dots menu next to it. For masked secrets, you can also copy the value to your clipboard. Restricted secrets cannot be copied or revealed.
![Clean Shot 2026 06 16 At 19 16 31@2x]()
## Secrets across environments
Secrets are project-wide. The values you set in **Settings** → **Secrets** are the defaults for every [environment](/documentation/deploy/environments) in your project, including `Main`, and any change applies across all of them immediatelySecrets are project-wide. The values you set in **Settings** → **Secrets** are the defaults for every [environment](/documentation/deploy/environments) in your project, including `Main`, and any change applies across all of them immediately.
To give one environment a different value, set a per-environment **override**. Open **Settings** → **Environments**, open the `...` menu next to the environment, and select **Override live secrets** or **Override draft secrets**. An override applies only to that environment's draft or live version. It never changes the project-wide default or affects any other environment, and secrets without an override fall back to the default.
![Secrets Override]()
## Overrides and merging
Because [merges](/documentation/deploy/environments/merging) replace the content of `Main`, when you merge an environment to main, its secret overrides are also applied to `Main`. If you've been testing with non-production credentials, such as a development API key, we recommend you remove the live secrets override prior to merging to prevent your live agent being connected to non-production APIs.
To give one environment a different value, set a per-environment **override**. Open **Settings** → **Environments**, open the `...` menu next to the environment, and select **Override live secrets** or **Override draft secrets**. An override applies only to that environment's draft or live version. It never changes the project-wide default or affects any other environment, and secrets without an override fall back to the default.
![Secrets Override]()
## Duplicating and exporting projects
When you duplicate or export a project, only secret names are included. Secret values are never copied for security reasons. After importing a duplicated project, you'll need to re-enter the secret values in **Settings** → **Secrets**.
## Security
Secrets are encrypted using AES-256 GCM, which provides both confidentiality and integrity protection through a Message Authentication Code (MAC). Encryption keys are securely managed and secrets are stored and transmitted according to industry best practices.
# Variables
Source: https://docs.voiceflow.com/documentation/build/data/variables
Store and reuse context throughout a conversation.
![Variables Docs]()
Variables let your agent remember and reuse information during a conversation - things like a user's name, account details, or selections they've made. They act as your agent's short-term memory, letting it personalize responses, make decisions, and pass data between steps.
Variables are scoped to individual users via `user_id`. If ten users are talking to your agent simultaneously, their variable values are completely independent.
## Creating variables
You can create a variable from anywhere your can insert them - type `{` in most text inputs across Voiceflow to see your existing variables or create a new one inline.
![Create Var Docs]()
You can also manage variables from the **Variables** tab in the sidebar. Click **New variable** in the top right to create one, or click an existing variable to edit it. When creating a variable, you can optionally set a default value - this gives your agent a fallback if the variable hasn't been set yet during a conversation. By default, variables are initialized automatically and set to 0.
![Variables Table Docs]()
## Using variables
Reference a variable by typing `{` and selecting it from the searchable menu. Variables work inside playbook instructions, API tool URLs and headers, condition steps, response messages, and more. If you're in a place where you need to use a variable, type `{` and it the menu will pop up.
![Using Vars]()
## Setting variable values
| Method | How it works |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Set step**](/documentation/build/steps/set) | Assign a value directly in a workflow |
| [**Code step**](/documentation/build/steps/code) | Set values using JavaScript logic |
| **Tool responses** | Capture the response from an [API tool](/documentation/build/tools/api-tool) or [function](/documentation/build/tools/function-tool) and store it in a variable |
| **Playbook exit conditions** | Variables attached as [exit conditions](/documentation/build/playbooks) on a playbook are filled by the agent during the conversation, then passed back when the playbook completes via a [playbook step](/documentation/build/steps/playbook) |
## Persisting variables across sessions
When you create or edit a variable, you can choose whether its value persists across sessions for the same user. This lets you decide, per variable, whether your agent remembers a value when someone returns and starts a new session with the same `user_id`, or starts fresh each time.
To set this, open the **Variables** tab in the sidebar, create or select a variable, and switch **Persist across sessions** on or off.
* **On**: the variable keeps its value when the same user starts a new session, so your agent can pick up where it left off (eg: greeting a returning customer by name or remembering their plan tier).
* **Off**: the variable resets to its default value at the start of each new session, so it only lasts for the duration of a single session.
Turn this off for values that should only apply to the current session, such as a one-time verification code, a temporary selection, or the user's progress through a flow. Keep it on for long-lived details you want your agent to remember across visits, like a user's name or their preferences.
## Built-in variables
Every project has access to built-in variables that are automatically set when a conversation begins or when certain events occur.
| Variable | Description | Example |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `user_id` | The user's unique ID, set via the [chat widget](/documentation/deploy/widget/embedding-the-chat-widget) or [API](/api-reference/api-overview). For [phone](/documentation/deploy/phone/connect-a-phone-number) integrations, this is the caller's phone number. | `example_user` or `+16471234567` |
| `last_utterance` | The previous message sent by the user | `My name is Braden and I like cookies.` |
| `last_response` | The agent's most recent response | `Hello, I'm an agent! How can I help today?` |
| `last_event` | The last [event](/documentation/build/behaviour) the user triggered (object, not string) | `{"type":"event","payload":{"event":{"name":"buySyrup"}}}` |
| `vf_memory` | The last ten user inputs and agent responses as a string, including tool calls | `agent: Hey what's up?`
`nuser: I want to order maple syrup.` |
| `vf_now` | Current date and time. Timezone configurable in **Settings** → **General** | `Monday, Jan 1, 2025, 16:37` |
| `vf_date` | Current date | `Jan 1, 2025` |
| `vf_time` | Current time | `16:37` |
| `vf_month` | Current month | `January` |
| `vf_day` | Current day of the month | `1` |
| `vf_year` | Current year | `2025` |
| `vf_user_timezone` | The user's timezone. Defaults to project timezone if unavailable | `America/Toronto` |
| `sessions` | Number of times this user has opened the agent | `8` |
| `timestamp` | [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) of when the conversation began | `873700668` |
| `vf_transcript_id` | The unique ID of the current conversation's [transcript](/documentation/measure/transcripts). Can be passed to the [Get transcript](/api-reference/transcript/get-transcript) API to retrieve the full conversation history. | `65f2a1b8c9d4e5f6a7b8c9d0` |
| `locale` | The user's [locale](https://learn.microsoft.com/en-us/globalization/locale/standard-locale-names), detected from their browser | `en-CA` |
| `platform` | The platform your agent is running on | `voiceflow` |
# Choosing a framework
Source: https://docs.voiceflow.com/documentation/build/framework/choosing-a-framework
Choose the agent framework that's best for your use case.
## Agentic vs. Conversation flow
When you create a project, you choose a framework. This shapes how your agent handles conversations and the tools you use to build it.
### Agentic (recommended)
The agent uses playbooks, workflows, tools, and reasoning to navigate conversations autonomously. It decides what to do next based on the user's input, your instructions, and the conversation context.
![Agentic Framework Docs]()
You can still build fully deterministic workflows in the agentic framework - the difference is that routing to and from those workflows is handled by an intelligent agent that you control through instructions, not by manual flow logic. This gives you the precision of workflows where you need it, with the flexibility of AI routing everywhere else.
### Conversation flow
You design the conversation path in the visual builder, with or without AI. The agent follows it step by step with no autonomous decision-making, unless defined by you. Every branch, every transition, every fallback is explicitly defined by you.
![Conversational Flow Framework Docs]()
This works for simple, predictable use cases. But as complexity grows, manual routing becomes a liability. Adding a new playbook means rewiring exit conditions across multiple flows. Edge cases multiply. Touching one path can quietly break another. Most teams that start with conversation flow for its upfront simplicity eventually hit a ceiling - the maintenance cost overtakes the control it was supposed to provide.
If you're unsure, start with the **Agentic** framework. You get the same deterministic control where you need it, plus AI-powered routing that scales with your agent's complexity. You can change your framework at any time from the framework tab.
# Initialization workflow
Source: https://docs.voiceflow.com/documentation/build/framework/initialization-workflow
Run a workflow before your agent takes control of the conversation.
The initialization workflow is the first thing that runs when a conversation starts - before your agent sees any messages. It gives you a controlled, deterministic space to handle setup: load user data, authenticate, set variables, or send a static greeting. Once the workflow completes, control passes to your agent and the conversation continues normally.
If you don't set an initialization workflow, conversations begin directly with your agent.
## Setting an initialization workflow
Open the **Framework** tab in the sidebar. Click the **Add workflow** on the initialization node and select an existing workflow, or click **create** to build a new one.
![Init Workflow]()
Once set, this workflow runs automatically at the start of every conversation. When the workflow ends - or when any step has an empty output port - the conversation navigates directly to your agent. You don't need to explicitly route to the agent; any unconnected port does this automatically.
## Common patterns
### Loading context
The most common use case. Make API calls at the start of a conversation to fetch user data - account info, order history, subscription tier etc. - and store it in variables. Your agent and playbooks have the context they need from the very first turn.
**Predictive conversations** - Run these calls asynchronously to load data in the background while the conversation is already happening. Fetch a customer's recent orders during authentication, pull account details while the agent greets the user. By the time the agent needs the data, it's already there - no loading state, no awkward pause. Your agent can open with "I see you have an order arriving later today — is that what you're calling about?" instead of asking the customer to state their intention.
### Static start message
If you want your agent to open with a specific greeting rather than generating one, add a text response step to your initialization workflow. Turn on **Wait for user input** after the message so the workflow pauses for the user to respond before handing off to the agent - otherwise the agent will immediately start talking over your greeting.
### Authentication
Gate the conversation behind identity verification. Check a user token, validate credentials via API, or collect an account number before your agent has access to any sensitive tools or data.
### Onboarding
Collect required information upfront - name, language preference, reason for contact - using a structured flow before the agent takes over. This is useful when you need specific variables set before any playbook can run effectively.
# Global prompt
Source: https://docs.voiceflow.com/documentation/build/global-prompt
The always-on layer that shapes how your agent behaves across every conversation turn.
![Global Prompt Docs]()
## What is the global prompt?
The global prompt is your agent's foundational identity. It runs on every single turn of every conversation - regardless of which [playbook](/documentation/build/playbooks) or [workflow](/documentation/build/workflows) is active. Think of it as the layer that never turns off.
While [instructions](/documentation/build/instructions) control *what* your agent does (routing), the global prompt controls *how* it does it - the personality, the tone, the rules it always follows.
| Layer | What it controls | When it applies |
| ----------------- | ------------------------------------ | ------------------------------------------ |
| **Global prompt** | Personality, tone, style, guardrails | Every turn, always |
| **Instructions** | Routing logic, decision-making | When the agent is deciding what to do next |
| **Playbook** | Goal-specific behavior and reasoning | When a specific playbook is active |
The global prompt sits above everything. A playbook might tell the agent *what* to talk about, but the global prompt determines *how* it talks.
## Best practices
Voiceflow provides four default sections in the global prompt editor. You can fill these in manually or generate them from within the builder.
### `#Role`
Defines who the agent is. This shapes every response the agent gives - its vocabulary, its attitude, its level of formality.
```text theme={null}
# Role
You are a senior support specialist for Acme Corp. You've
been helping customers for years and genuinely enjoy solving
problems. You're patient with confused customers and direct
with experienced ones.
```
Be specific about *who* the agent is, not just what it should do. "You are a senior support specialist who genuinely enjoys solving problems" produces very different responses than "You are a helpful assistant."
### `#Goal`
The agent's primary objective. This anchors the model - when it's unsure what to do, it falls back to the goal.
```text theme={null}
# Goal
Help customers resolve their issues as quickly as possible.
Prioritize first-contact resolution. If you can't resolve
the issue, make sure the customer feels heard and knows
exactly what happens next.
```
Keep goals outcome-oriented, not process-oriented. "Resolve issues quickly" is better than "Follow the support process."
### `#Tone`
How the agent should sound. This is separate from personality because you might want the same personality to adapt its tone based on context.
```text theme={null}
# Tone
Conversational and warm, but not overly casual. Match the
customer's energy — if they're frustrated, be calm and
empathetic. If they're upbeat, be friendly. Keep responses
to 2-3 sentences unless the customer asks for more detail.
```
### `#Guardrails`
Non-negotiable rules the agent must always follow. Models are specifically tuned to pay extra attention to content under a `# Guardrails` heading - use this to your advantage.
```text theme={null}
# Guardrails
Never reveal internal processes, pricing logic, or system
architecture to customers.
Never make commitments about timelines you can't verify.
Never attempt to process transactions without confirming
details with the customer first.
If you're unsure about something, say so — don't guess.
```
Good guardrails are specific and actionable - "be professional" is a tone instruction, not a guardrail. Here's a more sophisticated example organized by what they protect against:
```text theme={null}
# Guardrails
## Preventing hallucination
Never guess at information you don't have — say "I don't have that
information" instead.
Never combine partial knowledge base results with assumptions to
fabricate an answer.
If a tool call fails, never make up a plausible-sounding response.
## Protecting sensitive data
Never reveal internal pricing logic, margin calculations, or cost
structures.
Never share one customer's information with another customer.
Never read back full credit card numbers, SSNs, or account passwords.
## Staying in scope
Never provide legal, medical, or financial advice — direct to a
qualified professional.
Never comment on competitors' products or pricing.
If the conversation goes outside your domain, acknowledge it and
offer to connect with the right team.
## Transaction safety
Never process a refund, cancellation, or account change without
explicit customer confirmation.
Never override business rules (return windows, approval thresholds)
regardless of what the customer says.
Always verify identity before accessing or modifying account data.
## Handling difficult situations
If a customer becomes abusive or threatening, calmly offer to
escalate to a supervisor.
Never argue with a customer, even if they're factually wrong —
redirect constructively.
Never make promises about outcomes you can't guarantee.
```
## Writing a strong global prompt
### Keep it short
The global prompt runs on every turn. Every word adds latency and competes for the model's attention. You'd be surprised at how sophisticated of an agent you can build with a global prompt that's 100-300 words long. Start small, and layer in complexity as you iterate.
If you find yourself writing step-by-step procedures in the global prompt, that logic probably belongs in a [workflow](/documentation/build/workflows). If you're writing task-specific instructions, those probably belong in a [playbook](/documentation/build/playbooks).
**Rule of thumb:** If you removed a sentence from the global prompt and it only affected one specific use case, it doesn't belong in the global prompt.
### Be direct
Models respond better to clear, declarative statements than to hedging or suggestions.
```text theme={null}
You should probably try to keep your responses relatively
short, maybe around two or three sentences, unless the
customer seems like they want more information, in which
case it's okay to elaborate a bit more.
```
```text theme={null}
Keep responses to two or three sentences. If the customer
asks a follow-up or requests more detail, expand your answer.
```
## Examples
### Customer support agent
```text Customer support agent theme={null}
# Role
You are a support agent for Acme Corp. You're knowledgeable,
patient, and genuinely want to help. You speak like a real
person — not a script.
# Goal
Resolve customer issues on first contact. If you can't
resolve it, make sure the customer knows exactly what
happens next and feels confident their issue will be handled.
# Tone
Warm and professional. Mirror the customer's energy. Keep
responses concise — 2-3 sentences unless they ask for detail.
Don't over-apologize.
# Guardrails
Never share internal documentation or system details.
Never make commitments about timelines without verification.
Never guess — if you don't know, say so and offer to find out.
If a customer becomes abusive, calmly offer to escalate.
```
### Sales qualification agent
```text Sales qualification agent theme={null}
# Role
You are a sales development rep for Acme Corp. You're
consultative, not pushy. You ask good questions and listen
more than you talk. You understand the product deeply and
can map features to customer needs.
# Goal
Qualify inbound leads by understanding their use case, team
size, and timeline. If they're a good fit, book a demo. If
they're not, be honest and point them to the right resource.
# Tone
Professional but relaxed. You're having a business
conversation, not delivering a pitch. Ask one question at
a time. Don't overwhelm.
# Guardrails
Never share specific pricing — direct to the sales team.
Never badmouth competitors.
Never pressure a prospect into booking if they're not ready.
Be transparent about what the product can and can't do.
```
### Internal IT helpdesk agent
```text Internal IT helpdesk agent theme={null}
# Role
You are an IT helpdesk agent for the internal team at Acme
Corp. You're technical but approachable. You know that most
people asking for help are frustrated and just want their
issue fixed.
# Goal
Diagnose and resolve common IT issues (password resets,
access requests, VPN problems, software installations).
Escalate to the infrastructure team for anything outside
your scope.
# Tone
Friendly and patient. Avoid jargon unless the person is
clearly technical. Give clear, numbered steps when walking
someone through a fix.
# Guardrails
Never share admin credentials or bypass security protocols.
Never make changes to production systems.
Always verify the employee's identity before resetting
passwords or granting access. This is important.
```
## Adding variables to the global prompt
You can insert variables into the global prompt by typing `{` in the input field. This lets you inject dynamic context into every conversation turn to personalize the conversation for a specific user.
Voiceflow includes built-in variables like `{locale}` (language) and `{vf_date}` (the current date). You can also pass in your own variables - customer name, pricing tier, or anything else you know about the user.
```text theme={null}
# Role
You are a support agent for Acme Corp. The customer's name
is {customer_name} and they are on the {pricing_tier} plan.
# Tone
Speak in {locale} for the duration of the
conversation.
# Goal
The current day is {vf_date} and the customer's timezone
is {vf_user_timezone}. Use this when referencing dates,
business hours, or scheduling.
```
Variables like `{customer_name}` or `{pricing_tier}` aren't built-in - they need to be set before the global prompt runs. The most common way to do this is with an [initialization workflow](/documentation/build/workflows) that runs at the start of each conversation. Initialization workflows let you do basic checks and pull context about the user before the agent starts talking - so when the conversation begins, it feels personalized from the very first message.
For example, an initialization workflow that identifies the user, pulls their recent orders, and checks delivery windows could populate variables that power a global prompt like this:
```text theme={null}
# Role
You are a friendly support agent for a furniture company.
The customer's name is {customer_name}.
# First message
If the customer has an upcoming delivery: {upcoming}, proactively
surface it. Their next delivery is {item_name}, arriving
{delivery_date} between {delivery_window}. Greet them by
name and ask if they need help with this order.
Use the card tool to show them what's scheduled for delivery.
```
In this case, instead of a generic "How can I help you?" - the agent opens with something like this:
![Starting Message Docs 2]()
### Variable Consistency
The global prompt and instructions should remain as static and consistent as possible.
Large language models cannot reuse the existing conversation cache ([KV-caching](https://huggingface.co/blog/not-lain/kv-caching)) if a variable changes between turns in the global prompt or instructions. This causes every response to become slower and more expensive.
For dynamic or frequently changing variables, create a tool that allows the agent to fetch them on demand instead.
## Common mistakes
| Mistake | Why it's a problem | Fix |
| ---------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------- |
| Putting step-by-step procedures in the global prompt | Runs on every turn, adds latency, clutters the model's attention | Move to a [workflow](/documentation/build/workflows) |
| Task-specific instructions in the global prompt | Only relevant to one playbook, wastes tokens on every other turn | Move to a [playbook](/documentation/build/playbooks) |
| Vague personality ("be helpful and friendly") | Every agent sounds the same, no differentiation | Be specific about *who* the agent is |
| Too many guardrails | Model over-indexes on restrictions, becomes overly cautious | Keep guardrails to hard boundaries only |
| Repeating the global prompt in every playbook | Wastes tokens, can cause over-emphasis | Trust that the global prompt is always active |
| Using variables that change every turn | Every turn is re-processed from scratch, slower and more expensive | Create a tool that allows the agent to fetch the data |
## Default guidelines
```text Chat default guidelines expandable theme={null}
Your responses are displayed as text in a chat interface.
Structure:
1. One idea per paragraph. Separate with blank lines.
2. Never use bold, italics, headers, or markdown emphasis.
3. Bullets only for 3+ parallel items. Prose otherwise.
4. Emoji only if the user uses them.
Examples:
Simple answer:
User: "How do I add a teammate?"
Agent: "Go to Settings, then Workspace Members, and hit Invite. Want me to walk you through permissions too?"
Frustration:
User: "I've been trying to fix this for an hour and nothing works."
Agent: "That sounds frustrating, let's get it sorted. Can you tell me what happens when you try to publish?"
Multi-step:
User: "How do I connect my knowledge base and test it?"
Agent: "First, head to the Knowledge Base tab in your agent and upload your files or paste a URL. Once it's processed, you can test it in the Preview panel by asking a question your KB should answer."
Warm acknowledgment:
User: "I just upgraded to Pro!"
Agent: "Nice! You've got access to a lot more now. Anything specific you want to set up first?"
Out of scope:
User: "Can you help me write a blog post?"
Agent: "I'm set up to help with Voiceflow account and product questions. Is there anything I can help you with there?"
```
```text Voice default guidelines expandable theme={null}
Your responses are spoken aloud via text-to-speech. Write your
text as a spoken script, not a written message.
Structure:
1. One idea per sentence. Never exceed two clauses in a single
sentence.
2. Avoid nested clauses, parenthetical asides, or complex phrasing
that is hard to follow when heard.
3. Do not use any visual formatting: no bullet points, numbered
lists, markdown, bold, or italics.
4. Do not reference anything visual: "click here", "see below",
"as shown", links, or URLs spoken as links.
Punctuation:
5. Use commas for soft pauses between related thoughts.
6. Use periods to end complete thoughts. Do not string multiple
thoughts together with commas where periods belong.
7. Use question marks only for genuine questions.
8. Do not use exclamation marks, colons, semicolons, ampersands,
slashes, parentheses, quotation marks, asterisks, or underscores.
Text normalization:
9. Write all numbers as spoken words in running text: "three to
five business days" not "3-5 business days". Digits are acceptable
only when dictating back identifiers like order numbers or phone
numbers.
10. Write abbreviations as full spoken words: "doctor" not "Dr.",
"street" not "St.", "number" not "No.", "department" not "dept."
11. Acronyms spoken as words, write normally: "NASA". Acronyms
spelled out letter by letter, add spaces: "A P I" not "API".
12. Phone numbers in spoken groups: "five fifty-five, one
twenty-three, forty-five sixty-seven."
13. Currency as spoken words: "forty-two fifty" or "forty-two
dollars and fifty cents."
14. Dates as spoken words: "January fifteenth, twenty twenty-four."
15. Email addresses as spoken words: "support at example dot com."
16. URLs as spoken words: "example dot com slash help."
Examples:
Simple answer:
User: "How do I add a teammate?"
Agent: "Head to Settings, then Workspace Members, and hit Invite.
Want me to walk you through permissions too?"
Frustration:
User: "I've been trying to fix this for an hour and nothing works."
Agent: "That sounds frustrating, let's get it sorted. What happens
when you try to publish?"
Multi-step:
User: "How do I connect my knowledge base and test it?"
Agent: "First, open the Knowledge Base tab in your agent and upload
your files or paste a URL."
(after user confirms)
Agent: "Once it's done processing, open the Preview panel and ask
it a question your knowledge base should be able to answer."
Warm acknowledgment:
User: "I just upgraded to Pro!"
Agent: "Nice, you've got access to a lot more now. Anything
specific you want to set up first?"
Out of scope:
User: "Can you help me write a blog post?"
Agent: "I'm set up to help with Voiceflow account and product
questions. Is there anything I can help you with there?"
Numbers and data:
User: "What's my current bill?"
Agent: "Your current bill is forty-two dollars and fifty cents, due
on January fifteenth. Want me to look into any of the charges?"
```
## Frequently asked questions
Yes. The global prompt is active on every turn.
100-1000 words for most agents. If it's longer, you likely have logic that belongs in instructions, a playbook or a workflow. The global prompt should be the shortest, most universal layer.
The global prompt applies to every turn and defines who the agent is. A playbook prompt applies only when that playbook is active and defines what the agent is doing in that specific context. Think of it as: global prompt = identity, playbook = task.
Yes. Voiceflow's builder includes a prompt generation feature that scaffolds the four default sections based on your agent's configuration. You can generate and then customize from there.
Only if a tool rule applies universally (e.g., "always use the buttons tool when there's multiple options for the user"). Tool-specific instructions generally belong in the tool's trigger or the playbook instructions that uses that tool.
# Importing data sources
Source: https://docs.voiceflow.com/documentation/build/importing-data-sources
Ground your agent's responses in your own content.
![Knowledge Base Docs 1]()
The knowledge base gives your agent access to your own content - product docs, support articles, company policies, pricing pages, FAQs. When a user asks a question, the agent retrieves the most relevant content and uses it to generate an accurate, grounded response.
Instead of scripting every possible answer, you upload your content once and let the agent find what it needs.
## Adding a data source
Click 'Knowledge base' in the navigation menu, or use the shortcut Shift + K
Select the type of data you'd like to import
![Adding Data Sources Docs]()
## Data types
Voiceflow supports an array of data sources:
| Type | What it imports |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Web page(s)** | One or more URLs - paste each on a new line. Must be publicly accessible. |
| **Sitemap** | All pages from a site via sitemap URL. Ideal for full help centers or doc sites. |
| **Docs** | `.pdf`, `.txt`, or `.docx` files up to 10 MB. Only text content is imported. |
| **Table** | `.csv` or `.xlsx` files up to 10 MB. Each row is a chunk; column headers become field names. |
| **Plain text** | Paste raw content directly. |
| **Zendesk** | Import articles directly from your Zendesk knowledge base. |
| **Shopify** | Import product catalogues, inventory data and SKU info. |
You an also import and manage data sources through the [Knowledge base API](/api-reference/knowledge-base-api/knowledge-base-api-overview).
## Refresh rate
For URL and integration data sources, set a refresh rate to keep your knowledge base in sync with the source. You can do this on import, or retroactively by pressing the checkbox next to the data source or folder.
| Option | Best for |
| ----------- | ---------------------------------------------- |
| **Never** | Static content that won't change |
| **Daily** | Frequently updated content (blogs, news sites) |
| **Weekly** | Occasionally updated content (support centers) |
| **Monthly** | Stable content (policies, pricing pages) |
## LLM chunking strategies
When your agent queries the knowledge base, it finds chunks of content most similar to the user's question. LLM chunking strategies use AI to split your content into optimized chunks - improving retrieval quality and helping your agent find useful answers.
![Smart Chunking]()
| Strategy | Description | Best for |
| ------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
| **Smart chunking** | Breaks content into logical sections grouped by topic | Complex documents with varied topics (policy docs, course catalogs) |
| **FAQ optimization** | Generates sample questions each section could answer | Product info, help center content |
| **Remove HTML and noise** | Cleans up messy formatting to make text easier to process | Blog posts, markdown-heavy docs, CMS exports |
| **Add topic headers** | Adds brief summaries at the start of each section | Long documents needing context (research papers, onboarding guides) |
| **Summarize** | Keeps only key points and removes filler | Dense, lengthy content (legal agreements, strategy briefs) |
LLM chunking strategies consume credits on each sync. If your content doesn't change often, reduce your refresh rate to avoid unnecessary credit usage. No credits are consumed when syncing without an LLM chunking strategy selected.
Chunking strategies aren't one-size-fits-all. Experiment with different combinations on each data source to find what gets your agent the best results.
## Metadata
Attach metadata to any data source to filter what gets returned when your agent [queries the knowledge base](/documentation/build/querying-the-knowledge-base). Useful when you have multiple brands, product lines, locales, or subscription tiers and your agent needs to make sure the right information reaches the right users.
For example, if you have different policies for enterprise and self-serve customers, tag each data source with `plan: enterprise` or `plan: self-serve` and filter queries accordingly.
Click **+** in the **Metadata** section of the import config to add key-value pairs:
![Meta Data Docs]()
## Knowledge base and environments
Every environment in your project shares the same knowledge base, but each environment decides which documents from the shared set it uses, and stores its own metadata for those documents.
Changes to the knowledge base go live when you publish the environment, just like any other change to your agent.
Here's a few important things to keep in mind:
* **Content edits apply everywhere the document is used.** When you edit a knowledge base document and publish, this edit will be applied to all environments. When an environment is published, this edit will become visible to users interacting with that environment. Other environments that use the same document will pick up the new content the next time each of them publishes.
* **Metadata can be different on each environment.** The same document can carry different metadata on different environments, which is useful for testing how different metadata affects what the agent retrieves.
* **Integrations only need to be set up once.** After you connect Shopify or Zendesk as knowledge base sources on one environment, you can use the same connection from every other environment.
When you create a new environment by cloning an existing one, the new environment starts with the same set of documents as the one you cloned from.
## Troubleshooting imports
If an import fails, hover over the error icon for details. Failed files are handled gracefully - they won't break your project and the rest of your import will still process.
![Error Importing Docs]()
## Developers
The Knowledge base API gives you programmatic access to the documents that power your agent’s knowledge base. You can use it to [create](/api-reference/kbpublicapidocument/create-document), [retrieve](/api-reference/kbpublicapidocument/get-document), [update](/api-reference/kbpublicapidocument/update-document-metadata), and [delete](/api-reference/kbpublicapidocument/delete-document) documents, as well as manage their metadata and individual chunks.
# Instructions
Source: https://docs.voiceflow.com/documentation/build/instructions
Defines how the agent routes requests and decides which tools to use
![Agent Instructions Docs 1]()
## What are agent instructions?
Instructions are the decision-making layer of your agent. Where the global prompt defines *how* your agent behaves, instructions define *when* it does things.
When a user message comes in, the agent reads its instructions and picks the most appropriate way to handle it. Instructions are written in plain language, not code.
| Layer | What it controls | When it applies |
| ----------------- | ----------------------------- | ---------------------------------- |
| **Global prompt** | Personality, tone, guardrails | Every agentic turn, always |
| **Instructions** | Routing, tool selection | When deciding what to do next |
| **Playbook** | Goal-specific behavior | When a specific playbook is active |
## Writing agent instructions
Instructions work best when they're clear about which tool handles which type of request. Think of it like a brief for a team - each member needs to know what they own.
Every playbook, workflow, and tool has a name and a trigger. You can layer supporting context on top in the agent instructions, or playbook instructions.
* **Name** - what it is. Short and literal.
* **Trigger** - what it does *and* when the AI agent should use it. This is the primary signal the agent reads when deciding whether to call a tool or route into a playbook.
* **Instructions** - any additional context, routing reminders, phrasing rules, or ordering that apply on top of the trigger.
| | Good | Bad |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Name** | Order Status | Handle order related things |
| **Trigger** | Looks up the status of an existing order by order ID or email. Use when the customer asks about an existing order, a delivery, or tracking info. | Helps customers with orders |
| **Instructions** | Route to Order Status for any order-related question. If the customer then wants to return or exchange the item, hand off to the Returns workflow. | N/A |
![LLM Description Docs 1]()
We recommend putting both the *what* and the *when* in the trigger. Agent instructions are only in context when the agent is routing at the top level - once a playbook is active, only the global prompt and that playbook's own instructions are visible. If a playbook needs to jump to another playbook or decide which tool to call, it reads the names and descriptions. Any "when to use this" guidance that lives only in agent instructions won't reach those decisions. The instructions field is still useful for routing reinforcement and supporting context; it just shouldn't be the only place the "when" lives:
```text Simple agent insturctions example theme={null}
# Routing
Route to the Order Status playbook if the customer is asking
about an existing order, delivery, or tracking information.
Route to the Returns workflow if the customer wants to return,
exchange, or get a refund on a product.
Route to the Product Info playbook if the customer is asking
about product details, availability, or compatibility.
If the customer's request doesn't fit any tool, let them
know what you can help with and ask them to rephrase, or use the knowledge
base to provide accurate information.
```
### Adding a start message
If you want to define an agentic start message in your agent, you can add it to agent instructions.
```text theme={null}
# Starting Message
Greet the user and offer assitance, use buttons to show the user
quick options of what they can do.
# Tools
```
![Starting Message Docs]()
The above instruction would result in something like the chat above. The agent has followed the instructions and greeted the user, while also using the buttons tool to deliver dynamic options based on tools available.
If you want to deliver a very specific start message, you can instruct your agent to do so, or use the [initialization workflow](/documentation/build/framework/initialization-workflow) to design something truly deterministic with a [message step](/documentation/build/steps/message).
## Testing instructions
From the agent tab, press 'Run' in the top right, or use the shortcut Shift + R
Type or talk to your agent from the message input
Check logs the logs section and state viewer to see if your agent is routing correctly
![Clean Shot2026 03 11at14 18 36@2x]()
If your agent doesn't route make sure you're following best practices for tool name and trigger. From there, try improving the instructions for that tool.
# Overview
Source: https://docs.voiceflow.com/documentation/build/overview
Build AI agents with playbooks, workflows, and powerful customization options.
The Build section covers everything you need to create production-ready agents - from defining their behavior and logic to connecting external tools and knowledge sources.
## Key concepts
| **Goal** | **Docs** | **Description** |
| --------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Define global prompt, instructions, and skills | [Agent](/documentation/build/global-prompt) | Design how your agent responds and what skills it has to get things done |
| Create agentic, goal based conversations
with tool calling | [Playbooks](/documentation/build/playbooks) | Give your agent flexible reasoning to navigate open-ended conversations |
| Handle complex, multi-step processes - with or without AI | [Workflows](/documentation/build/workflows) | Design precise, step-by-step conversation flows with the visual builder |
| Add knowledge to your agent | [Knowledge base](/documentation/build/importing-data-sources) | Upload documents and data to ground your agent's responses |
| Connect external tools | [Tools](/documentation/build/tools/api-tool) | Enable your agent to call APIs, integrations, functions and MCP servers |
| Store and manage data | [Variables](/documentation/build/data/variables) | Use variables to capture, store, and pass data through conversations |
| Manage sensitive data | [Secrets](/documentation/build/data/secrets) | Securely store API keys and credentials for use in tools and integrations |
| Select agent framework | [Framework](/documentation/build/framework/choosing-a-framework) | Select between agentic (recommended) or conversational flow framework |
### Agent
Control how your agent thinks, responds and routes users:
* [Global prompt](/documentation/build/global-prompt): Applied to every turn to shape how the agent responds, independent of routing or skills. This usually includes `# Personality`, `# Goal`, `# Tone`, and `# Guardrails`.
* [Instructions](/documentation/build/instructions): Defines how the agent routes requests and decides which skills to use.
### Playbooks & workflows
Playbooks and workflows control what your agent can do for users - things like checking an order status, booking a demo, processing a return, or resetting a password.
* [Playbooks](/documentation/build/playbooks): Autonomous reasoning for open-ended conversations - your agent decides how to navigate based on context, intent, and goals.
* [Workflows](/documentation/build/workflows): Visual workflow builder for more deterministic, multi-step conversation flows with branching, conditions, and integrations.
Workflows can use playbooks & other AI-powered steps, so you can build agentic experiences with deterministic control where it matters. You can also build fully scripted interactions with scripted messages, buttons, conditions, and other non-AI steps.
This is a **critical decision** you'll make when building AI agents in Voiceflow:
| Use a **playbook** when... | Use a **workflow** when... |
| ------------------------------------------------ | ------------------------------------------------ |
| **Flexibility** matters more than predictability | **Predictability** matters more than flexibility |
| The conversation is **open-ended** | The process has strict **business logic** |
| The agent needs to reason about what to do | The steps are the same every time |
| There are many possible paths | There's one, or a few correct paths |
There’s no universally correct choice - selecting a playbook or a workflow comes down to your specific use case and the needs of your business.
If you're unsure, we recommend starting with a playbook as it provides more flexibility and is easier to iterate on as you learn what your customers actually need. You can always introduce workflows later to handle specific conversations that benefit from a more structured approach.
### Knowledge base
Extend your agent with external data and integrations that sync automatically:
* [Import data sources](/documentation/build/importing-data-sources): Upload URLs, sitemaps, and documents to ground responses in real information via RAG.
* [Connect to external data sources](/documentation/build/importing-data-sources): Connect your knowledge base to Zendesk, Shopify, Kustomer, Salesforce, and more.
### Tools
Tools can be used in playbooks or workflows:
* [API tools](/documentation/build/tools/api-tool): Connect to external REST APIs to fetch data or trigger actions.
* [Function tools](/documentation/build/tools/function-tool): Write custom JavaScript logic that runs during conversations.
* [Integration tools](/documentation/build/tools/overview): Pre-built connectors for Salesforce, HubSpot, Zendesk, Twilio, and more.
* [MCP tools](/documentation/build/tools/mcp-tool): Use Model Context Protocol servers to extend agent capabilities.
* [Global tools](/documentation/build/tools/global-tools): Added at the agent level, and accessibly throughout your agent.
* [System tools](/documentation/build/tools/system-tools): Update the internal state of conversations and show native UI artifacts.
### Data management
Capture and use data throughout conversations:
* [Variables](/documentation/build/data/variables): Store user inputs, API responses, and conversation state to personalize interactions.
* [Secrets](/documentation/build/data/secrets): Securely manage API keys and credentials used by tools and integrations.
## Next steps
Define global prompt, instructions, and skills (playbooks & workflows).
Create agentic, goal based conversations\
with tool calling.
Handle complex, multi-step processes - with or without AI.
Add knowledge to your agent & connect to tools like Zendesk & Shopify.
# Playbooks
Source: https://docs.voiceflow.com/documentation/build/playbooks
Goal-based AI that navigates conversations toward an outcome.
![Playbooks Docs]()
Playbooks are goal-based. You define an outcome - resolve a support ticket, qualify a lead, process a return - and the agent navigates the conversation to get there.
What makes playbooks powerful is the tools they can use along the way. While the agent is talking to your customer, it can be looking up their order in Shopify, creating a ticket in Zendesk, updating a deal in Salesforce, or calling your own internal APIs - all in real time.
Unlike [workflows](/documentation/build/workflows), which follow a fixed sequence of steps, playbooks let the agent decide how to reach the goal based on context. You write the instructions - the agent handles the conversation.
Playbooks can be triggered directly by your [agent](/documentation/build/global-prompt), from within a workflow using the [playbook step](/documentation/build/steps/playbook), or chained together using a [crew step](/documentation/build/steps/crew).
## Tools
Playbooks can use tools to take action during a conversation:
![Integrations Docs]()
* [**Integrations**](/documentation/build/tools/overview) - pre-built connectors to tools your team already uses, like Zendesk, Salesforce, Shopify, HubSpot, Gmail, and more.
* [**API tool**](/documentation/build/tools/api-tool) - connect to any REST API with a custom request. Use this for internal systems or any service without a pre-built integration.
* [**MCP tool**](/documentation/build/tools/mcp-tool) - connect to any MCP server and expose its tools directly to the playbook.
* [**Function tool**](/documentation/build/tools/function-tool) - run custom JavaScript logic mid-conversation, useful for data transformation, calculations, or lightweight processing without an external call.
* [**System tools**](/documentation/build/tools/system-tools) - call the knowledge base, forward calls, end the conversation, display buttons, cards or carousels, search the web.
Tools work best when their names and triggers give the model enough signal to know what they do and when to use them - the same principle as naming/describing the playbook itself.
* **Name** - what the tool is. Short and literal. "Lookup Order", not "Order tool".
* **Trigger** - what the tool does *and* when the agent should use it. Include both.
* **Playbook instructions** - any additional context: ordering, error handling, or how the tool fits into the larger conversation.
Put the "when" in the tool's description, not just in your instructions. Once a playbook is active, agent-level instructions are no longer in context - only the playbook's own instructions are. A tool's trigger that covers both what and when travels with the tool wherever it's used.
## Creating playbooks
From the **Agent** tab, click **+** in the right editor. Select an existing playbook or create a new one.
![Adding Playbooks Docs]()
You can also create playbooks from within a workflow using the [playbook step](/documentation/build/steps/playbook), or from the playbook CMS tab.
Give your playbook a clear name and trigger. The trigger should cover both what the playbook does and when the agent should route into it - this is what other playbooks, workflows, and the top-level agent read when deciding whether to call it. ![Create Playbook Docs 1]()
You'll be taken to the playbook editor to write or generate instructions. Playbooks added from the agent tab are automatically attached to your agent. Click **×** in the top right (or 'esc' on keyboard) to return to the agent tab at any time.
Use the **Tools** panel on the right to add any [integrations](/documentation/build/tools/overview), [APIs](/documentation/build/tools/api-tool), [MCPs](/documentation/build/tools/mcp-tool), [functions](/documentation/build/tools/function-tool) or [system tools](/documentation/build/tools/system-tools) your playbook needs to achieve its goal.
From the agent tab, press 'Run' in the top right, or use the shortcut Shift + R then initiate the playbook by typing or speaking a message.
If your playbook isn't performing the way you expect, start by improving the instructions - they're almost always the culprit. From there, make sure your tools have clear names and triggers so the playbook knows when and how to use them. Changing the model should be a last resort, but can prove helpful given the goal at hand.
## Writing good instructions
Instructions are the core of every playbook. They tell the agent what to do, and when to use its tools. Write in plain language - markdown formatting is supported.
The quality of your instructions directly affects the quality of your agent. Vague instructions produce inconsistent behavior. Specific instructions produce reliable, predictable agents.
**Instead of:**
```text theme={null}
Help customers check their order status, use the order lookup tool.
```
**Write:**
```text theme={null}
# Goal
Give {customer_name} a clear, accurate status update on
their order. Handle common order situations directly where
possible, and set clear expectations when you can't.
# Looking up an order
Ask for their order number or the email used at checkout.
Use the Order Lookup tool to retrieve the order before
saying anything about its status.
If the lookup returns multiple orders, list them with the
item name and order date and ask which one they're referring
to.
# Delivering the status
Share the item name, current status, and estimated delivery
date. Be direct — don't pad the response.
# Handling common situations
**Order is delayed:** Acknowledge it without over-apologizing.
Give the revised ETA from {delivery_eta} if available. If
no ETA is in the system, say so and offer to follow up when
it updates.
**Order shows delivered but customer didn't receive it:**
Confirm the delivery address on file. Ask if they've checked
with neighbors or in a safe spot. If it's still missing,
let them know this needs to go to the support team and
collect the details before handing off.
**Order was cancelled:** Explain why if the system shows
a reason. Confirm whether a refund was issued and the
expected timeline.
**Partial shipment:** Let them know which items have shipped
and which are still pending. Give separate ETAs if available.
**Wrong item received:** Apologize once, confirm what they
ordered vs what arrived, and let them know the support team
will sort it — collect the details before handing off.
# If the order can't be found
Double-check the order number or email. If still nothing,
let the customer know and offer to connect them with the
support team.
```
You can edit instructions manually or click the AI button to open the prompt editor, which helps you generate and refine your playbook from scratch.
## Model settings
Click **Model** in the top right corner of the playbook editor to configure:
* **AI model** - which model powers this playbook (eg: Claude Sonnet 4.6)
* **Temperature** - lower for consistency, higher for variation
* **Max tokens** - maximum response length
By default, playbooks inherit the model settings from your agent. Override them here if a specific playbook needs different behavior - for example, a lower temperature for a compliance-sensitive flow, or a more capable model for complex reasoning tasks.
## Entry conditions and required variables
Entry conditions and required variables can only be applied when a playbook is routed to directly by the [agent](/documentation/build/global-prompt). They're not available when the playbook is called via a [playbook step](/documentation/build/steps/playbook) inside a [workflow](/documentation/build/workflows).
Entry conditions and required variables control when the [agent](/documentation/build/global-prompt) can route into a playbook. Until they're met, the playbook stays unavailable, so the agent won't hand off to it no matter what the customer says. This gives you precise, rule-based control over when each playbook becomes reachable.
### Entry conditions
Entry conditions are deterministic checks that must evaluate to true before the playbook can be routed to. If the checks don't pass, the playbook stays unavailable for routing. For example, you might only make a checkout playbook reachable once the`{cart_total}` [variable](/documentation/build/data/variables) is greater than zero, or gate an account management playbook behind `{is_authenticated}` being true.
![Entry conditions]()
### Required variables
You can also require that specific [variables](/documentation/build/data/variables) have a value before the agent can route in. Until every required variable is filled, the playbook stays unavailable. For example, you could require the `{account_id}` variable to be set before the agent can hand off to an account management playbook, so it never starts without the information it needs.
![Required variables]()
## Exit conditions
Exit conditions only apply when a playbook is used via a [playbook step](/documentation/build/steps/playbook) inside a [workflow](/documentation/build/workflows). When triggered directly by the agent, exit conditions are ignored as routing is handled by the agent.
Playbooks can have **exit conditions** - the criteria that must be met before the agent considers the playbook complete.
You can add **required variables** to any exit condition. These variables must have a value before the condition can trigger - even if the conversation seems resolved, the playbook won't exit until they're filled.
For example, a Lead Capture playbook with an exit condition of "User is qualified" might require `{company_size}`, `{use_case}`, and `{email}`. The agent will keep the conversation going until all three are collected, then exit.
![Required Vars Docs]()
# Querying the knowledge base
Source: https://docs.voiceflow.com/documentation/build/querying-the-knowledge-base
To give your agent access to the knowledge base, open the **Agent** and make sure the **knowledge base** toggle is on in [system tools](/documentation/build/tools/system-tools). When on, your agent will automatically use this tool when it needs information to answer a question.
![KB Toggle Docs 1]()
When on at the agent level, individual [playbooks](/documentation/build/playbooks) can also query the knowledge base. You can override query settings at the playbook level without impacting the agent or other playbooks.
## Configuring the knowledge base tool
When you enable the knowledge base system tool in your agent, you can configure how it queries your content.
![Knowledge Base Tool Config Docs]()
### Trigger
Describes what this tool does and when the agent should use it. By default this is pre-filled with an opinionated description, however, you can reset it to a simpler default, or override it to your use-case. You can also add examples in your agent or playbook instructions showing when to use - or avoid - this tool for better retrieval accuracy.
```text Opinionated default we apply to new projects theme={null}
Use this tool when answering any question about your company, product, service,
or purpose, unless the answer has already been retrieved in the current
conversation.
Never answer these questions from your own knowledge - only use information
retrieved from this tool or web search. Before searching, reformat the user's
query for retrieval by extracting key terms and intent, stripping filler, and
including relevant conversation context.
If no results are found, try web search (if available) before saying you don't
have information. Never mention the knowledge base, or your use of it, to users.
```
```text Simple default you can reset to theme={null}
Searches an external knowledge base to retrieve relevant information,
supplementing or replacing the language model's internal context.
```
### Custom query
By default, the agent uses the user's last message as the search query. Use a custom query to override this - useful when you want to search on a specific variable or a reformulated version of the user's input. To insert a variable, type `{` in the input.
### Query re-writing
When enabled, the model rewrites the user's last message before searching based on your instructions - improving retrieval for conversational or ambiguous inputs. Useful when users don't phrase questions the way your content is written.
```text Query re-writing example theme={null}
Search for the underlying user intent rather than the user's exact words.
For example:
- "it won't let me log in" = "login error troubleshooting"
- "my thing never showed up" = "missing order or delivery issue"
- "how much is it" = "pricing and plan information"
```
### Chunk limit
Controls how many content chunks are returned per query (1-10, default 3). Higher values return more context but increase latency and token usage. Start at 3 and increase if the agent is missing relevant information.
### Meta data filtering
Unfamiliar with adding meta data in the knowledge base? [Learn more](/documentation/build/importing-data-sources)
Filter which data sources are queried based on metadata tags. Useful when you have content for different plans, regions, or product lines and want to make sure the agent only retrieves what's relevant for the current user.
Meta data filtering lets you apply values manually, or let the agent/playbook apply query values at runtime based on the conversation history.
You can add a variable to the default value field by typing`{` .
![Meta Data Filtering Docs 1]()
### Tool messages
Customize what the user sees while the knowledge base tool is running. You can set scripted messages for four states:
* **Start** - shown when the tool begins querying
* **Complete** - shown when results are returned
* **Fail** - shown when the query returns nothing or errors
* **Delay** - shown if the query takes longer than expected (you set the delay threshold)
![Tool Messages Docs]()
Each state supports multiple message variants - the agent picks one randomly to avoid repetition. You can also set conditional variants that trigger based on variables or context, giving you fine-grained control over what the user sees depending on the situation.
### Show source URL(s)
This feature is only available in **chat** projects.
When enabled, the agent includes the source URL alongside its response so users can verify or read more. Recommended for help centers and documentation.
![Show Source Url Kb Docs 1]()
## Developers
The Knowledge base API gives you programmatic access to the documents that power your agent’s knowledge base. You can use it to [create](/api-reference/kbpublicapidocument/create-document), [retrieve](/api-reference/kbpublicapidocument/get-document), [update](/api-reference/kbpublicapidocument/update-document-metadata), and [delete](/api-reference/kbpublicapidocument/delete-document) documents, as well as manage their metadata and individual chunks.
# API
Source: https://docs.voiceflow.com/documentation/build/steps/api
Make HTTP requests to external APIs at a specific point in your workflow.
![Cover Placeholder]()
The API step lets you execute an [API tool](/documentation/build/tools/api-tool) in your workflow. API tools make HTTP requests to external services, allowing you to fetch data, submit information, or integrate with any REST API. Use this step when you need to interact with third-party services that don't native native integrations as part of your workflow logic, like retrieving customer data, checking inventory, or sending notifications.
## Using the API step
Drag the API step onto the canvas and connect it to the step before it. Click on the step to select which API tool to run.
Select an existing API tool from the dropdown, or create a new one by clicking **New API tool**. Once selected, you'll see the input variables that the tool accepts.
### Configuration
* **Input variables**: Provide values for each input variable the API tool expects. Enter specific text, numbers, or use variables from your workflow. Each input variable has a description explaining what information it needs.
* **Capture response**: Optionally save the API's response to a [variable](/documentation/build/data/variables). If the response contains structured data (like JSON), you can specify an object path to extract specific information (eg: `data.user.email` to get just the email from a larger response object).
* **Async execution**: Toggle this on to allow your workflow to continue immediately without waiting for the API call to complete. When off, the workflow waits for the API response before moving to the next step. This can be useful when working with APIs that your workflow isn't reliant on, like analytics APIs.
# Buttons
Source: https://docs.voiceflow.com/documentation/build/steps/buttons
Display clickable buttons for users to interact with.
For agentic button generation where buttons are dynamically created based on conversation context, use the [buttons system tool](/documentation/build/tools/system-tools) inside a [Playbook](/documentation/build/playbooks) instead of the Buttons step.
![Cover Placeholder]()
The Buttons step shows clickable buttons in your chat interface. Each button can either trigger a specific path in your workflow or open a URL. Use this step when you want to present clear options to users, like choosing between different services, confirming a selection, or navigating to external resources.
## Using the Buttons step
Drag the Buttons step onto the canvas and connect it to the step before it. Click on the step to add and configure your buttons.
Click the **+** icon to add a button. Enter a button label using text or a variable. You can add multiple buttons by clicking **Add another**.
## Using the Buttons step
Drag the Buttons step onto the canvas and connect it to the step before it. Click on the step to add and configure your buttons.
Click the **+** icon to add a button. Enter a button label using text or a variable. Each button creates a connection point on the step that you can connect to other steps in your workflow. Click **Add another** to create multiple buttons.
### Configuration
* **Button**: Enter the text that appears on the button. You can use variables by wrapping them in curly braces (eg: `{product_name}`).
* **URL**: Optionally add a URL that opens when the button is clicked. Choose whether it opens in a new tab or the existing tab. The workflow will still continue down the button's connected path even when a URL is set.
### Additional settings
* **No match**: When enabled, handles situations where the user's response doesn't match any button label. Your agent can send a message or follow a path in situations where the user's response is invalid.
* **No reply**: When enabled, handles situations where the user doesn't respond within a specified time. Your agent can either send messages periodically or follow a path after the specified time.
* **Listen for other triggers**: When enabled, allows your agent to recognize and respond to [events](/documentation/build/behaviour), [DTMF inputs](/documentation/build/behaviour), and route to Playbooks attached to your [Agent](/documentation/build/instructions) while waiting for a button selection. When disabled, the agent only responds to button clicks.
# Call forward
Source: https://docs.voiceflow.com/documentation/build/steps/call-forward
Transfer calls from your agent to a live representative or another phone number.
This feature is only available on **phone** projects.
![Callforwardingstepcover]()
The Call forward step lets you hand off active phone conversations to real people or other phone systems. When your agent reaches this step during a call, it transfers the caller to the phone number you specify, creating a smooth transition from AI to human support or other automated systems.
## Using the Call forward step
Drag the Call forward step into a workflow and connect it to the step before it. Click on the step to configure where calls should be forwarded.
### Configuration
The Call forward step requires a phone number and supports optional extensions:
* **Phone number**: Enter the destination phone number in international format (eg: +1234567890). You can forward to standard phone numbers, international numbers, or SIP addresses.
* **Extension**: Add an extension to navigate phone menus after the call connects. This uses DTMF tones to automatically bypass IVR systems and enter menu options or extensions. The syntax depends on your telephony provider:
* **Voiceflow-provided number, Telnyx, and Twilio**: Use `w` for a 0.5 second pause or `W` for a 1 second pause between digits. Example: `1W23` presses 1, waits 1 second, then presses 2 and 3.
* **Vonage**: Use `p` for a 0.5 second pause between digits. Example: `1pp23` presses 1, waits 1 second, then presses 2 and 3.
* **CallerID passthrough:** On forwarded inbound calls, show the *original caller's* number as the caller ID instead of the agent's number.
> **Note:** Not supported on Vonage numbers.
* **Inbound:** When caller **A** reaches agent **B** and the call forwards to **C**, **C** normally sees the call from **B**. With passthrough on, **C** sees **A**'s phone number instead.
* **Outbound:** When agent **B** calls user **A** and forwards to **C**, **C** always sees **B** - passthrough has no effect here. This is a carrier regulatory restriction.
# Card
Source: https://docs.voiceflow.com/documentation/build/steps/card
Display a card with an image, text, and buttons.
For agentic card generation where cards are dynamically created based on conversation context, use the [cards system tool](/documentation/build/tools/system-tools) inside a [Playbook](/documentation/build/playbooks) instead of the Card step.
![Cover Placeholder]()
The Card step shows a visual card in your chat interface. Cards combine an image, title, description, and buttons in a single interactive element. Use this step when you want to present information visually, like displaying product details, showing profile summaries, or highlighting key features with actions users can take.
## Using the Card step
Drag the Card step onto the canvas and connect it to the step before it. Click on the step to configure your card's content.
Add an image by either uploading a file or providing a URL. Enter a title and description for your card, using text or variables. Then add buttons that users can click to continue the conversation.
### Configuration
* **Image**: Upload an image file or provide a URL. Supported formats include .png, .jpg, and .gif.
* **Card title**: Enter the heading text that appears on the card. You can use [variables](/documentation/build/data/variables) by wrapping them in curly braces (eg: `{product_name}`).
* **Card description**: Enter descriptive text that appears below the title. You can use variables and basic formatting.
* **Buttons**: Add clickable buttons to your card. Each button creates a connection point that you can connect to other steps in your workflow. Optionally add URLs to buttons. Unlike the [Buttons step](/documentation/build/steps/buttons), card buttons persist after the user clicks them, so users can return to the card and make another selection.
### Additional settings
* **No match**: When enabled, handles situations where the user's response doesn't match any button label. Your agent can send a message or follow a path in situations where the user's response is invalid.
* **No reply**: When enabled, handles situations where the user doesn't respond within a specified time. Your agent can either send messages periodically or follow a path after the specified time.
# Carousel
Source: https://docs.voiceflow.com/documentation/build/steps/carousel
Display multiple cards in a scrollable carousel.
For agentic carousel generation where cards are dynamically created based on conversation context, use the [carousel system tool](/documentation/build/tools/system-tools) inside a [Playbook](/documentation/build/playbooks) instead of the Carousel step.
![Cover Placeholder]()
The Carousel step shows multiple cards in a horizontal carousel that users can scroll through. Each card can contain an image, title, description, and buttons. Use this step when you want to present multiple options visually, like showing a product catalog, displaying service packages, or highlighting different features users can explore.
## Using the Carousel step
Drag the Carousel step onto the canvas and connect it to the step before it. Click on the step to add and configure your cards.
Click the **+** icon next to **Cards** to add a new card to your carousel. Configure each card's image, title, description, and buttons. You can add multiple cards to create a scrollable gallery.
### Configuration
Each card in the carousel can be configured with:
* **Image**: Upload an image file or provide a URL. Supported formats include .png, .jpg, and .gif.
* **Card title**: Enter the heading text that appears on the card. You can use variables by wrapping them in curly braces (eg: `{product_name}`).
* **Card description**: Enter descriptive text that appears below the title. You can use variables and basic formatting.
* **Buttons**: Add clickable buttons to each card. Each button creates a connection point that you can connect to other steps in your workflow. Optionally add URLs to buttons. Carousel buttons persist after the user clicks them, so users can return to the carousel and make another selection.
### Additional settings
* **No match**: When enabled, handles situations where the user's response doesn't match any button label. Your agent can send a message or follow a path in situations where the user's response is invalid.
* **No reply**: When enabled, handles situations where the user doesn't respond within a specified time. Your agent can either send messages periodically or follow a path after the specified time.
# Code
Source: https://docs.voiceflow.com/documentation/build/steps/code
Run JavaScript code in your workflow.
![Cover Placeholder]()
The Code step lets you write and execute JavaScript snippets directly in your workflow. Use it for tasks like parsing data, manipulating variables, performing calculations, or adding conditional logic that determines which path your workflow follows next.
The Code step is best suited for short code snippets. If you'd like to build reusable functions, use the [Function step](/documentation/build/steps/function) instead.
## Using the Code step
Drag the Code step onto the canvas and connect it to the step before it. Click on the step to open the code editor where you can write your JavaScript code.
All of your agent's variables are automatically available in the code editor. You can reference and modify them directly without using curly braces. For example, to increment a `score` variable by 1, simply write `score = score + 1`.
## Configuring paths
The Code step includes two paths:
* **Default path**: The workflow follows this path when your code runs successfully.
* **Failure path**: The workflow follows this path if your code encounters an error during execution. Toggle this path on to handle errors gracefully.
You can also add up to 10 custom paths to route users based on your code's logic. Name each custom path, then use `return [path_name]` in your code to direct the workflow to that specific path. If your code doesn't return a path name, the workflow continues through the `Default` path.
## Limitations
* The Code step cannot make requests to external servers or call external APIs. Use the [API step](/documentation/build/steps/api) or [Function step](/documentation/build/steps/function) for these tasks.
* The Code step does not support importing JavaScript modules.
* Variables created inside the Code step only exist while the step is running. To use a variable after the Code step finishes, [create it as a variable inside your project first](/documentation/build/data/variables) before referencing it in your code.
# Condition
Source: https://docs.voiceflow.com/documentation/build/steps/condition
Route your workflow based on variable values or logic.
![Cover Placeholder]()
The Condition step lets you create different paths in your workflow based on whether specific conditions are met. You might use it to check if a user is logged in, verify that a form is complete, or route users differently based on their account type.
## Using the Condition step
Drag the Condition step onto the canvas and connect it to the step before it. Click on the step to set up your conditions and paths.
### Configuration
* **Paths**: Create paths that your workflow can follow. For each path, define conditions by selecting a variable, choosing a comparison operator (eg: is, contains, greater than), and entering a value to compare against. Use **Match all** for AND logic or **Match any** for OR logic when adding multiple conditions to a path.
* **Else path**: Toggle this on to add a fallback path when no conditions are met.
# Crew
Source: https://docs.voiceflow.com/documentation/build/steps/crew
Coordinate multiple playbooks to work together seamlessly.
![Crew Step Cover]()
The Crew step lets you group multiple playbooks together so they can hand off tasks between each other directly. Because routing happens within the step itself rather than through a separate routing agent, crews reduce latency and make for a smoother user experience. You might use a Crew step for customer support, where you can have separate playbooks for sales, billing, legal, and general inquiries, each handing off to the next as needed.
## Using the Crew step
Drag the **Crew step** onto the canvas and connect it to a workflow. Once added, configure your root playbook and any subagents.
Each playbook in the crew is aware of the strengths of other playbooks and can hand off tasks to them. With the Crew step, coordinating complex tasks that involve back-and-forth between multiple playbooks becomes seamless.
The root playbook is simply the first playbook triggered when the workflow enters the Crew step. There is no functional difference between the root playbook and other playbooks beyond this. The trigger on the crew configuration panel refers to the root playbook and tells the LLM when to return control back to it.
When prompting a playbook to hand off to another playbook in the crew, use the exact name of the target playbook.
### Exit conditions
Exit conditions are global within a Crew step. Any exit conditions set on individual playbooks inside the crew are ignored. Instead, the exit conditions you define on the Crew step itself apply to all playbooks in the crew equally.
### Configuration
* **Root playbook**: The playbook that is triggered first when the workflow enters the Crew step. Configure its trigger to help the LLM understand when to return control to it.
* **Other playbooks**: Additional playbooks available within the crew. Each playbook's trigger tells the LLM what the playbook does, so write these clearly and specifically to ensure accurate handoffs.
* **Exit conditions**: Conditions that end the crew and move the workflow forward. These apply globally to all playbooks in the crew.
* **Listen for other triggers**: Works identically to the same setting on a standard Agent step.
# End
Source: https://docs.voiceflow.com/documentation/build/steps/end
End your agent's conversation and optionally send a closing message.
![Cover Placeholder]()
The End step ends the conversation between your agent and the user. When your workflow reaches this step, the conversation session closes immediately: voice agents will hang up the call, and chat agents will close the session. You can optionally configure a final message to send before ending the conversation, giving users a clear signal that the interaction is complete.
## Using the End step
Drag the End step onto the canvas and connect it to the point in your workflow where the conversation should end. Click on the step to configure an optional end message.
### Configuration
* **End message**: Send a final message to the user before the conversation ends. You can write a static message or use a prompt to generate dynamic closing messages using AI.
# Function
Source: https://docs.voiceflow.com/documentation/build/steps/function
Run custom code as a function tool in your workflow.
![Cover Placeholder]()
The Function step lets you execute a [function tool](/documentation/build/tools/function-tool) at a specific point in your workflow. Function tools are reusable pieces of custom code that perform specific tasks, like data transformations, API calls, or complex calculations. Use this step when you need to run custom logic that goes beyond what built-in steps can do.
## Using the Function step
Drag the Function step onto the canvas and connect it to the step before it. Click on the step to select which function tool to run.
Select an existing function tool from the dropdown, or create a new one by clicking **New function tool**. Once selected, you can map the function's outputs to variables in your workflow.
### Configuration
* **Output variables**: Map each output from the function to a [variable](/documentation/build/data/variables) in your agent. Click on an output variable and select which variable should receive that data. Any outputs you don't map won't be saved.
* **Async execution**: Toggle this on to allow your workflow to continue immediately without waiting for the function to complete. When off, the workflow waits for the function to finish before moving to the next step. This is useful for functions that take a long time to run but that your agent doesn't rely on, such as analytics collection functions.
### Function Code
When the workflow reaches a Function step, the runtime resolves the step's input mappings into `args.inputVars `
# Integration
Source: https://docs.voiceflow.com/documentation/build/steps/integration
Use a third-party integration tool in your workflow.
![Cover Placeholder]()
The Integration step lets you call any [third-party integration tool](/documentation/build/tools/overview) at a specific point in your workflow. Use it to interact with external services like [Gmail](/documentation/build/tools/gmail-tool), [Salesforce](/documentation/build/tools/salesforce-tool), or [Zendesk](/documentation/build/tools/zendesk-tool), triggering actions such as sending emails, updating records, or fetching data when your workflow reaches this step.
## Using the Integration step
Drag the Integration step onto the canvas and connect it to the step before it. Click on the step to select which integration tool to use.
First, choose the integration you want to use (eg: [Gmail](/documentation/build/tools/gmail-tool), [Google Sheets](/documentation/build/tools/google-sheets-tool), [Zendesk](/documentation/build/tools/zendesk-tool)). Then, select the specific tool from that integration (eg: "Send email" for Gmail, or "Get customer" for Shopify). If the integration isn't connected yet, you'll need to connect it before you can use its tools. You can then configure each input variable for your tool call (eg: the email address that you'd like to send an email to) - if you'd prefer to set these agentically, use the integration via a [Playbook](/documentation/build/playbooks) instead.
### Configuration
* **Input variables**: Provide the required information for the tool to work. Each tool has different required inputs. For example, Gmail's "Send email" tool needs a recipient address, subject, and body. Click on each input to enter a value or select a variable.
* **Capture response**: Save the tool's response to a variable for use later in your workflow. Click **+ Add** to create a new variable that will store the response data. You can specify an object path to capture specific parts of the response.
# Listen
Source: https://docs.voiceflow.com/documentation/build/steps/listen
Capture the user's response and save it to a variable.
While the Listen step is a great way to collect information during scripted flows, most of the time, it's better to use a [Playbook step](/documentation/build/steps/playbook) to capture user input. The Playbook step allows you to have two-way conversations inside a workflow, meaning you can build a much more powerful agent.
![Cover Placeholder]()
The Listen step pauses your workflow and waits for the user to respond. When they do, their entire message is saved to a variable that you can use later in your agent. Use it when you need to collect open-ended input like feedback, descriptions, or any freeform text response during a scripted flow.
## Using the Listen step
Drag the Listen step onto the canvas and connect it to the step before it. Click on the step to configure where the user's response should be saved.
### Configuration
* **Save entire reply to**: Select or create a variable where the user's complete message will be stored. This variable can be referenced later in your workflow.
* **No reply**: Toggle this on to handle situations when the user doesn't respond within a set timeframe. Configure how long to wait and what message to send as a reminder.
* **Listen for other triggers**: Toggle this on to allow your agent to respond to other triggers while waiting for the user's reply. When off, the agent focuses only on capturing the user's input at this step.
# MCP
Source: https://docs.voiceflow.com/documentation/build/steps/mcp
Use an MCP tool at a specific point in your workflow.
![MCP tool]()
The MCP step lets you execute an [MCP tool](/documentation/build/tools/mcp-tool) in your workflow. MCP tools connect to external services through the Model Context Protocol, a standardized way for AI agents to interact with third-party applications. Use this step when you need to perform actions in external systems as part of your workflow, like sending Slack messages or managing data in other platforms.
## Using the MCP step
Drag the MCP step onto the canvas and connect it to the step before it. Click on the step to select which MCP tool to run.
Select an existing MCP tool from the dropdown, or create a new one by clicking **New MCP tool**. Once selected, you'll see the input variables that the tool requires.
### Configuration
* **Input variables**: Provide values for each required input. Enter specific text, numbers, or use variables from your workflow. Each input variable has a description explaining what information it needs.
* **Capture response**: Optionally save the tool's response to a [variable](/documentation/build/data/variables). If the response contains structured data (like JSON), you can specify an object path to extract specific information (eg: `data.user.email` to get just the email from a larger response object).
# Message
Source: https://docs.voiceflow.com/documentation/build/steps/message
Send a message to the user.
![Message step]()
The Message step sends a single message to the user. You can write a static message with optional variants, or use AI to generate a dynamic message based on the conversation context. Use this step when you need to provide information, confirm an action, or give feedback without expecting a back-and-forth conversation.
## Using the Message step
Drag the Message step onto the canvas and connect it to the step before it. Click on the step to write your message or configure an AI prompt.
### Configuration
The Message step supports two modes:
* **Scripted**: Write a pre-defined message and optionally variants to test different versions of your message with users. You can format text with bold, italics, underline, and include links or emojis.
* **Prompt**: Use AI to generate a single message using a prompt. For multi-turn conversational interactions, use the [Playbook step](/documentation/build/steps/playbook) instead.
Enable the **Wait for user input setting** to pause the workflow after sending the message and wait for the user to respond before continuing.
# Operator
Source: https://docs.voiceflow.com/documentation/build/steps/operator
Route your workflow with LLM-powered conditional logic, no code required.
![Operatorstepcover]()
The Operator step is a **silent**, LLM-powered step that evaluates conditions and routes your workflow accordingly. Unlike traditional code-based conditionals, it uses an LLM to interpret the conditions you define, giving it the flexibility to evaluate variable values, user input, and session state without requiring exact string matches or rigid logic. It can also draw on any tools you configure to help it evaluate conditions more accurately. The Operator step produces no output visible to the user: it simply evaluates once and directs the conversation down the appropriate path.
## Using the Operator step
Drag the **Operator step** onto the canvas and connect it to the preceding step in your workflow. Once added, configure your prompt and connect each exit path to the next step in your flow.
### Configuration
The Operator step is configured through a prompt, tools, and a set of exit conditions that you define.
* **Prompt**: Write a prompt to guide the LLM on how to evaluate your routing logic and provide any additional context it needs to route accurately.
* **Tools**: The Operator step has access to tools to help it evaluate conditions. See the Integration tools documentation for more details.
* **Exit conditions**: Each exit condition represents a named path the workflow can take. You can write a trigger for each one, giving the LLM instructions on when to route to that path. You can also specify required variables, meaning the LLM can only exit to that path if those variables are filled.
If the LLM is uncertain which condition to route to, it will retry a few times before selecting the closest match. In practice this resolves quickly, but keeping your conditions clear and distinct will minimise ambiguity.
# Playbook
Source: https://docs.voiceflow.com/documentation/build/steps/playbook
Add agentic playbooks to your deterministic workflows.
![Cover Placeholder]()
The Playbook step lets you call a [Playbook](/documentation/build/playbooks) from within your workflow. Playbooks are agentic AI components that respond dynamically to users based on instructions, rather than following a fixed sequence of steps. Use this step when you want your workflow to hand off to an intelligent, flexible conversation before returning to your deterministic logic.
## Using the Playbook step
Drag the Playbook step onto the canvas and connect it to the step before it. Click on the step to select which playbook to run.
Select an existing playbook from the dropdown, or create a new one by clicking **New playbook**. Once selected, you can configure how the playbook behaves within your workflow and define exit conditions that create paths back to your workflow.
### Configuration
* **Listen for other triggers**: When enabled, allows your agent to recognize and respond to [events](/documentation/build/behaviour), [DTMF inputs](/documentation/build/behaviour), and switch to your [Agent](/documentation/build/global-prompt) while the playbook is active. When disabled, the playbook focuses solely on its instructions.
* **Playbook talks first**: When enabled, the playbook sends its first response immediately upon entering the step. When disabled, the playbook waits for user input before responding.
* **Exit every conversational turn**: When enabled, the playbook returns control to the workflow after each message exchange with the user, creating a connection point labeled **Exit conversational turn**. When disabled, the playbook continues handling the conversation until an exit condition is met.
### Exit conditions
Exit conditions let your playbook hand off control to other parts of your workflow when specific situations arise. Each exit condition creates a connection point on the step that you can connect to other steps in your workflow. For example, you might create an exit condition called "Speak to human" that triggers when a user requests human assistance, then connect it to a Call forward step. [Learn more about exit conditions](/documentation/build/playbooks).
# Set
Source: https://docs.voiceflow.com/documentation/build/steps/set
Set or update variable values in your workflow.
![Set step]()
The Set step lets you set or update the value of [variables](/documentation/build/data/variables) during your workflow. Use it to store user preferences, save important pieces of context, or reset variables at specific points in your conversation flow.
If you'd like to set the value of a variable using code, use the [Code step](/documentation/build/steps/code) instead.
## Using the Set step
Drag the Set step onto the canvas and connect it to the step before it. Click on the step to configure which variables to set and their values.
### Configuration
* **Variables to set**: Add one or more variables to update. For each variable, choose how to set its value:
* **Value**: Enter a specific text or number value directly.
* **Prompt**: Use AI to generate the variable's value based on a prompt you write.
* **Properties to set**: Add one or more [transcript properties](/documentation/measure/transcripts) to attach custom metadata to the conversation transcript. Unlike variables, properties aren't used during the conversation. They're saved to the transcript for later filtering and analysis.
* **Parallel execution**: Toggle this on to allow the workflow to continue immediately without waiting for all variables to be set. When off, the workflow waits for all variables to be set before moving to the next step.
# Workflow
Source: https://docs.voiceflow.com/documentation/build/steps/workflow
Call another workflow from your current workflow.
![Cover Placeholder]()
The Workflow step lets you jump from one workflow to another workflow within your agent. When the called workflow finishes, your agent returns to the original workflow and continues from where it left off. Use this step to organize complex logic into reusable workflows or to break down large conversational flows into smaller, manageable pieces.
## Using the Workflow step
Drag the Workflow step onto the canvas and connect it to the step before it. Click on the step to select which workflow you want to call.
### Configuration
* **Select workflow**: Choose an existing workflow from the dropdown to call when your agent reaches this step. You can also create a new workflow directly from this menu by clicking **New workflow**.
# Airtable tool
Source: https://docs.voiceflow.com/documentation/build/tools/airtable-tool
Create, read, update, and delete records in your Airtable bases.
![Airtable Tool]()
The Airtable tool lets your agent interact with your Airtable data during a conversation. Use it to log leads, look up product information, update form responses, or manage any records your workflow requires.
## Using the Airtable tool
Add the Airtable tool to your agent from **Tools** → **Add tool** → **Airtable**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Airtable tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Create record** | Add a new record to a table. |
| **Get record** | Retrieve a single record by its ID. |
| **List records** | Retrieve multiple records from a table, optionally filtered by conditions or specific fields. |
| **Update record** | Modify fields in an existing record. Only specified fields are modified. |
| **Delete record** | Remove a record from a table. |
# API tool
Source: https://docs.voiceflow.com/documentation/build/tools/api-tool
Make HTTP requests to external APIs.
![API Tools Docs 1]()
The API tool lets your agent call external APIs during a conversation. Use it to fetch data from third-party services, submit information to webhooks, or integrate with any REST API. Unlike the [Function tool](/documentation/build/tools/function-tool), the API tool requires no JavaScript code, making it accessible to less-technical builders.
## Creating an API tool
You can add, or create an API tool directly from within a [playbook](/documentation/build/playbooks).
![API Playbook Docs]()
You can also create API tools from within a workflow using the [API step](/documentation/build/steps/api), or from the tools CMS tab.
Define your HTTP request:
| Field | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Method** | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |
| **URL** | The endpoint to call. Use curly braces for variables (e.g. `https://api.example.com/users/{user_id}`) |
| **Headers** | Key-value pairs like `Authorization` or `Content-Type` |
| **Parameters** | Query parameters appended to the URL |
| **Body** | Request body for `POST`, `PUT`, and `PATCH` requests - choose from **Form data**, **URL encoded**, or **Raw** (e.g. JSON) |
Optionally define input variables that can be passed in by a [playbook](/documentation/build/playbooks) or an [API step](/documentation/build/steps/api). Use them in your URL, headers, or parameters by wrapping them in curly braces. Add a description to each so the agent knows what to pass.
Click **Run** in the top right corner to test your API call. Click **Variables** to enter test values, then **Run** to execute. The response panel shows the JSON body, status code, size, and response time (e.g. `200 OK · 11.3 kB · 354ms`). Use **Show raw** for the unformatted response, or the **Headers** tab to inspect response headers.
## Testing the API tool
Click **Run** in the top right corner of the API tool editor to test your API call. Click **Variables** to enter test values for your input variables, then click **Run** to execute the request.
The response panel displays the JSON response body along with the status code, response size, and response time (eg: `200 OK · 11.3 kB · 354ms`). Click **Show raw** to see the unformatted response, or use the **Headers** tab to inspect the response headers.
## Using the API tool
There are two ways to use an API tool:
### In a playbook
Add the API tool to a playbook's Tools editor. The agent will call it autonomously when it determines the tool is needed based on the conversation context, the tool's description, and your playbook instructions. For example, an "Order Lookup" API tool added to an order status playbook: the agent decides when to call it, passes the right input variables, and uses the response to answer the customer.
![API Playbook Docs]()
Give the tool a clear name and description that covers both what it does and when the agent should use it. The tool description is always in context when the agent considers calling a tool, so the "when" belongs here.
Use playbook instructions for supporting context - ordering, error handling, or how the tool fits into the larger flow.
### In a workflow
Drag an [API step](/documentation/build/steps/api) onto the canvas and select the API tool you want to call. Input variables are mapped explicitly in the step config: the agent doesn't decide whether to call it, the workflow executes it at that point in the flow every time.
Use this when the API call is part of a fixed process - for example, always verifying identity before accessing account data, or always sending a confirmation after a booking is made.
![API Step Docs 1]()
## Running API tools asynchronously
Both API tools in workflows or playbooks can run async. The async toggle is available at the instance level, not tool level allowing you to use the same tool, with different config.
![Async Docs 1]()
When you run an API tool async, it will immediately continue the conversation without waiting for the results of the API tool to return.
### Fire and forget
Use async when you don't need the API response to continue the conversation. The call fires in the background and the agent moves on immediately.
This is ideal for logging and side effects - sending an event to an analytics platform, writing to a CRM, triggering a webhook, or any operation where the agent doesn't need to reference the result. The user gets a faster experience because the conversation never pauses for a background task.
### Async with deferred response
Use async when the API call is slow or not immediately relevant, but the response still matters. The call fires in the background and the agent continues the conversation naturally. When the response arrives, it's captured and the agent can reference it on the next turn.
For example, during your [initialization workflow](/documentation/build/framework/initialization-workflow), you authenticate the user and simultaneously fire an async call to fetch their recent orders. By the time authentication completes and the agent takes over, the order data is already available. The agent can open the conversation with "I see you have a recent order for a queen mattress arriving Thursday — is that what you're calling about?" instead of asking the user to explain why they're reaching out.
![Starting Message Docs 2]()
This pattern is powerful for predictive experiences - preloading context the agent will likely need so the conversation starts ahead of the user. It also works for long-running operations, large dataset searches, or any third-party service with unpredictable latency. Instead of the user waiting on a loading state, the agent keeps moving and weaves the result in when it's ready.
# Function tool
Source: https://docs.voiceflow.com/documentation/build/tools/function-tool
Run custom JavaScript during a conversation.
![The Function tool configuration panel in the Voiceflow editor]()
The Function tool lets your agent run custom JavaScript mid-conversation. Use it for data transformation, calculations, formatting, or any lightweight processing that doesn't require an external API call.
## Creating a Function tool
You can add, or create a Function tool directly from within a [playbook](/documentation/build/playbooks).
![Function Playbook Docs]()
You can also create Function tools from within a workflow using the [Function step](/documentation/build/steps/function), or from the tools CMS tab.
Add the variables your function needs as inputs. These are passed in by a [playbook](/documentation/build/playbooks) or a [Function step](/documentation/build/steps/function) and are accessible inside your code. Add a description to each so the agent knows what to pass.
Write your JavaScript function code in the editor. Return your output by setting the output variable values - these are passed back to the conversation.
Add output variables for any values your function should return to the agent. These are available in the conversation after the function runs.
Click **Run** in the top right corner to test. Click **Variables** to enter test values for your inputs, then **Run** to execute. The output panel shows your returned values and any console logs.
## Using the Function tool
There are two ways to use a Function tool:
### In a playbook
Add the Function tool to a playbook's Tools editor. The agent calls it autonomously when the conversation requires it - based on the tool's description, your playbook instructions, and the conversation context.
![Function Playbook Docs]()
For example, a "Calculate Shipping Cost" function added to an order playbook - the agent passes in the order weight and destination, runs the calculation, and uses the result in its response.
Give the tool a clear name and description that covers both what it does and when the agent should use it. Use playbook instructions to layer on any supporting context.
### In a workflow
Drag a [Function step](/documentation/build/steps/function) onto the canvas and select the Function tool you want to run. Input variables are mapped explicitly in the step config - the function runs at that point in the flow every time.
Use this when the logic is part of a fixed process - for example, always formatting a date before displaying it, or always calculating a total before confirming an order.
![Functions Step Docs]()
## Running Function tools asynchronously
Both Function tools in workflows or playbooks can run async. The async toggle is available at the instance level, not tool level allowing you to use the same tool, with different config.
![Async Function Docs 1]()
When you run an API tool async, it will immediately continue the conversation without waiting for the results of the API tool to return.
### Fire and forget
Use async when you don't need the Function response to continue the conversation. The call fires in the background and the agent moves on immediately.
This is ideal for logging and side effects - sending an event to an analytics platform, writing to a CRM, triggering a webhook, or any operation where the agent doesn't need to reference the result. The user gets a faster experience because the conversation never pauses for a background task.
### Async with deferred response
Use async when the Function call is slow or not immediately relevant, but the response still matters. The call fires in the background and the agent continues the conversation naturally. When the response arrives, it's captured and the agent can reference it on the next turn.
For example, during your [initialization workflow](/documentation/build/framework/initialization-workflow), you authenticate the user and simultaneously fire an async call to fetch their recent orders. By the time authentication completes and the agent takes over, the order data is already available. The agent can open the conversation with "I see you have a recent order for a queen mattress arriving Thursday — is that what you're calling about?" instead of asking the user to explain why they're reaching out.
![Starting Message Docs 2]()
This pattern is powerful for predictive experiences - preloading context the agent will likely need so the conversation starts ahead of the user. It also works for long-running operations, large dataset searches, or any third-party service with unpredictable latency. Instead of the user waiting on a loading state, the agent keeps moving and weaves the result in when it's ready.
## How function code works
Function code runs remotely in a secure, isolated sandbox. On each execution, the runtime sends your code and input values to the sandbox, and executes it.
It receives `args`, and returns an object describing what the runtime should do next:
```javascript theme={null}
export default async function main(args) {
const { user_name } = args.inputVars;
return {
outputVars: { user_email: `${user_name}@example.com` },
trace: [{ type: 'text', payload: { message: `Hello, ${user_name}!` } }],
next: { path: 'success' },
};
}
```
Functions run on ES6 JavaScript using the V8 engine. Browser APIs (e.g. `window`, `document`) and module imports (`require`, `import`) are not supported.
### Accessing input variables
`args.inputVars` contains one key per **input variable** declared on the function. Input values come from the Function step's input mappings, or are generated by the agent when called from a playbook.
```javascript theme={null}
const { order_id, customer_email } = args.inputVars;
```
### The return value
Your function communicates back exclusively through its return value - nothing else persists between runs. An invalid malformed return value fails the step.
```typescript theme={null}
{
outputVars?: Record;
next?: { path: string }; // function step only
trace?: Array<{ type: string; payload?: unknown }>;
}
```
#### `outputVars`: setting variables
Maps the function's declared **output variables** to values. Keys must match declared output variables and values must be plain data (`string`, `number`, `boolean`, or `null`).
```javascript theme={null}
return {
outputVars: { order_total: 129.99, order_status: 'shipped' },
};
```
#### `next`: choosing a path
Paths are only applied in function steps, not within a playbook or agent.
Selects which of the function's declared **paths** the workflow follows. The `path` value must exactly match a declared path code - returning an unknown code fails the step.
```javascript theme={null}
return {
next: { path: 'found' },
};
```
* If the function declares paths but your code returns no `next`, the workflow stops.
* If the function declares no paths, `next` is ignored and the step continues through the default port.
**Advanced:** `next` also accepts `{ listen: true }` to pause on the step and wait for the user's next input or event - used to build interactive [chat widget extensions](/documentation/deploy/widget/web-chat-extensions).
#### `trace`: sending messages and custom events
An array of [trace](/api-reference/trace-types) objects appended to the agent's response, in order. Every trace needs a `type` and`payload`.
```javascript theme={null}
return {
trace: [{ type: 'text', payload: { message: 'Your order has shipped! 🎉' } }],
};
```
### Making API requests with `fetch`
Functions include a global `fetch` for HTTP requests. It's similar to the standard Fetch API, with one key difference: **the response body is fetched and parsed**, and returned as a plain object - there are no `.json()` or `.text()` methods to call.
```javascript theme={null}
export default async function main(args) {
const response = await fetch('https://api.example.com/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: args.inputVars.user_id }),
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const order = response.json; // a property, not a method
return {
outputVars: { order_id: order.id },
next: { path: 'success' },
};
}
```
The second argument supports the standard options (`method`, `headers`, `body`). The resolved response object contains:
| Property | Description |
| ---------------------- | ----------------------------------------------------------- |
| `ok` | `true` when the status is 2xx |
| `status`, `statusText` | HTTP status code and message |
| `json` | The parsed body, when the response's `Content-Type` is JSON |
| `text` | The body as a string, for all other content types |
| `headers` | Response headers - each key maps to an **array** of values |
| `url`, `redirected` | Final URL and whether any redirects were followed |
By default, the body lands in `response.json` when the `Content-Type` header indicates JSON, and in `response.text` otherwise. To force a specific format, pass a third argument: `fetch(url, init, { parseType: 'json' | 'text' | 'arrayBuffer' | 'blob' })`.
* Response bodies are limited to **1 MB** - larger responses throw an error.
* Requests are bounded by the function's overall timeout; streaming responses and WebSockets are not supported.
* A network failure, timeout, or oversized response throws - uncaught, this fails the step and routes it down the error path.
# Global tools
Source: https://docs.voiceflow.com/documentation/build/tools/global-tools
Give your agent tools that are available everywhere, across all playbooks and workflows.
![Global Tools Docs 2]()
Global tools are [APIs](/documentation/build/tools/api-tool), [integrations](/documentation/build/tools/overview), [MCPs](/documentation/build/tools/mcp-tool), and [functions](/documentation/build/tools/function-tool) that you add directly at the agent level. Once added, they're available at the agent level, and in any playbook throughout your AI agent - without needing to add them individually to each one.
## Adding a global tool
Open the **Agent** tab and find the **Global tools** section in the right editor. Click the **+** to open the tool configuration panel - the same experience you'd use inside a playbook. From here you can connect an API, add an MCP server, connect an integration, or define a function.
## When are global tools are available for my agent to use?
Global tools are only available when your agent is in an agentic context - that is, when the LLM is actively reasoning and deciding what to do. This includes the global agent, [playbooks](/documentation/build/playbooks), and [crews](/documentation/build/steps/crew).
They are not available when the user is on a scripted step inside a workflow, such as a [buttons](/documentation/build/steps/buttons) or [listen](/documentation/build/steps/listen) step. Because the flow is deterministic at that point, the agent isn't making free-form decisions and global tools aren't accessible. If you need a tool during a scripted sequence, add it to that workflow directly via a [tool step](/documentation/build/steps/api).
A simple way to think about it: if the LLM is in control, global tools are available. If the step is scripted, they're not.
## Getting the most out of global tools
Add a tool globally when it's something your agent should be able to use anywhere. A few examples of good candidates:
* A CRM lookup that any playbook might need to identify the customer
* A ticketing API your agent uses across multiple support flows
* A shared function that formats or transforms data consistently
If a tool is only relevant in one specific playbook, it's better to add it there instead. Global tools work best when the capability is genuinely cross-cutting.
The primary lever for controlling when a global tool fires is the tool's own trigger - write it to cover both what the tool does and when the agent should use it. Because global tools are available inside every playbook, that trigger travels with the tool everywhere. Use your global prompt or instructions to layer on cross-cutting rules on top. For example:
* "Always look up the customer record before responding to account-related questions"
* "Only call the ticketing API if the user has confirmed the issue in their own words"
## Keeping it simple
If your agent is straightforward - a few tools and a clear purpose - you can consider not using playbooks or workflows at all. Simply add your tools globally and let the agent handle everything from the top level, guided by your [global prompt](/documentation/build/global-prompt) and [instructions](/documentation/build/instructions).
This works well for agents with a small, well-defined toolset where the LLM can reliably decide when and how to use each tool without additional structure. Adding playbooks and workflows is useful for more complex agents that need distinct behaviours or scripted sequences, but they're not a hard requirement.
# Gmail tool
Source: https://docs.voiceflow.com/documentation/build/tools/gmail-tool
Send emails from your agent using your connected Gmail account.
![Gmail Cover]()
The Gmail tool lets your agent send emails during a conversation. Use it to send confirmation emails, follow-up messages, support ticket summaries, or any other automated communication your workflow requires.
## Using the Gmail tool
Add the Gmail tool to your agent from **Tools** → **Add tool** → **Gmail**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Gmail tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| -------------- | --------------------------------------------------------------------------------- |
| **Send email** | Send an email to one or more recipients. Attachments are not currently supported. |
# Google Sheets tool
Source: https://docs.voiceflow.com/documentation/build/tools/google-sheets-tool
Read data from and write data to a Google Sheet.
![Google Sheets]()
The Google Sheets tool lets your agent interact with your spreadsheets during a conversation. Use it to log form submissions, pull dynamic data like product lists or pricing, track support cases, or maintain customer records.
## Using the Google Sheets tool
Add the Google Sheets tool to your agent from **Tools** → **Add tool** → **Google Sheets**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Google Sheets tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| -------------------------- | --------------------------------------------------- |
| **Add to sheet** | Append a new row of data to an existing sheet. |
| **Create new spreadsheet** | Create a new spreadsheet in your Google account. |
| **Get rows** | Retrieve one or more rows from a sheet. |
| **Get sheet** | Retrieve details and structure of a specific sheet. |
| **Update sheet** | Update data in existing cells or rows. |
# Hubspot tool
Source: https://docs.voiceflow.com/documentation/build/tools/hubspot-tool
Create contacts, leads, and tickets in your HubSpot CRM.
![Hubspot tool cover]()
The HubSpot tool lets your agent interact with your CRM during a conversation. Use it to capture lead information, create support tickets when customers report issues, or add new contacts when users share their details.
## Using the HubSpot tool
Add the HubSpot tool to your agent from **Tools** → **Add tool** → **HubSpot**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Hubspot tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ------------------ | -------------------------------------- |
| **Create contact** | Add a new contact to your HubSpot CRM. |
| **Create lead** | Create a new lead in your HubSpot CRM. |
| **Create ticket** | Log a new support or service ticket. |
# Make tool
Source: https://docs.voiceflow.com/documentation/build/tools/make-tool
Connect your agent to hundreds of apps through Make scenarios.
This feature requires a paid [Make account](https://make.com/pricing). Using this tool with a free Make account will cause it to fail.
![Make tool cover]()
The Make tool lets your agent trigger scenarios in your Make account during a conversation. Use it to orchestrate complex automations across hundreds of apps, such as sending follow-up emails, syncing data to multiple services, or notifying your team when specific events occur.
## Using the Make tool
Add the Make tool to your agent from **Tools** → **Add tool** → **Make**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Make tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **Run scenario** | Trigger a scenario in your Make account. You can pass data from Voiceflow to your scenario. |
When you connect a Make scenario, Voiceflow automatically detects and displays the input variables required by your scenario.
# MCP tool
Source: https://docs.voiceflow.com/documentation/build/tools/mcp-tool
Connect your agent to MCP servers and use their tools.
Voiceflow supports hosted MCP servers accessible from the internet. Local MCP servers are not supported. You can use a service like [Zapier MCP](https://zapier.com) to build a hosted server.
MCP (Model Context Protocol) is a standardized way for AI agents to connect to external services. Unlike API tools where you configure individual endpoints, an MCP server can expose multiple tools at once - each with its own description, parameters, and context that helps your agent understand how and when to use them.
## Creating an MCP tool
You can add MCP tools from a server, or connect to a new server directly from within a [playbook](/documentation/build/playbooks).
![MCP Playbook Docs]()
You can also add MCP servers from within a workflow using the [MCP step](/documentation/build/steps/mcp), or from the tools CMS tab. Servers can be managed centrally in Settings → MCP servers.
Enter your server details:
![Create MCP Docs]()
| Field | Description |
| ----------------------- | ------------------------------------------------------------------------ |
| **Server name & image** | A friendly label shown inside Voiceflow and optional image |
| **Server URL** | The root URL of your hosted MCP server |
| **Headers** | Optional key-value pairs for authentication (API keys, tokens) |
| **Image** | Optional icon displayed next to the tool in playbooks and workflow steps |
Once connected, Voiceflow fetches the available tools from your server. Select the ones you want your agent to have access to - you don't have to enable all of them and can refresh the server when you choose to access new tools.
Each tool from an MCP server comes with a name, description, and parameters defined on the server itself. If your agent isn't using a tool correctly, check the tool descriptions on your server - they're what the model reads to decide when and how to call them.
## Using the MCP tool
There are two ways to use an MCP tool:
### In a playbook
Add MCP tools to a playbook's Tools editor. The agent calls the individual tools autonomously based on the conversation context, your playbook instructions, and the tool descriptions from the server. For example, a CRM MCP server might expose "lookup contact", "create ticket", and "update deal stage" tools. Add the individual tools to a support playbook and the agent will call the right tool at the right time.
Give the tools a clear name and description inside Voiceflow that covers both what the tool is for and when the agent should reach for it.
### In a workflow
Drag an [MCP step](/documentation/build/steps/mcp) onto the canvas and select the specific tool you want to call. Input variables are mapped explicitly in the step config: the workflow executes it at that point in the flow every time.
Use this when the MCP call is part of a fixed process - for example, always logging a ticket after a complaint, or always syncing a record after a form is completed.
# Overview
Source: https://docs.voiceflow.com/documentation/build/tools/overview
Pre-built integrations to the platforms you already use.
![Integrations Section Docs]()
Integration tools are pre-built connectors that let your agent interact with external platforms without configuring raw API requests. Each integration comes with ready-made tools - like creating a ticket in Zendesk, updating a lead in Salesforce, or sending an SMS in Twilio - so you can connect your agent to the tools your team already uses.
## Available integrations
| Integration | What your agent can do |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| [**Airtable**](/documentation/build/tools/airtable-tool) | Read, create, and update records in your bases |
| [**Gmail**](/documentation/build/tools/gmail-tool) | Send emails and create drafts |
| [**Google Sheets**](/documentation/build/tools/google-sheets-tool) | Read and write rows in spreadsheets |
| [**HubSpot**](/documentation/build/tools/hubspot-tool) | Create and update contacts, deals, and tickets |
| [**Make**](/documentation/build/tools/make-tool) | Trigger scenarios and pass data to automations |
| [**Salesforce**](/documentation/build/tools/salesforce-tool) | Create and update contacts, leads, and cases; add comments to cases |
| [**Shopify**](/documentation/build/tools/shopify) | Look up orders, products, and customers; cancel and update orders; update customer info |
| [**Twilio**](/documentation/build/tools/twilio-tool) | Send SMS messages |
| [**Zendesk**](/documentation/build/tools/zendesk-tool) | Create, find, and update tickets; add comments; look up users, groups, and organizations |
Voiceflow regularly adds new integrations based on customer demand. Need something we're missing? [Book a demo](https://www.voiceflow.com/demo)
## Setting up an integration
You can add, or connect an integration tools directly from within a [playbook](/documentation/build/playbooks).
![Adding Integration Tool Docs 1]()
You can also add integration tools from within a workflow using the [Integration step](/documentation/build/steps/integration), or from the tools CMS tab. Integrations can be managed centrally in Settings → Integrations.
Follow the OAuth flow or enter API credentials to connect your account. Each integration has its own authentication method.
Choose which actions you want your agent to have access to. You don't need to enable everything - only add what's relevant to your use case.
## Using integration tools
There are two ways to use an integration tool:
### In a playbook
Add integration tool to a playbook's Tools editor. The agent will call it autonomously when it determines they're needed based on the conversation context, the tool's description, and your playbook instructions.
![Integrations Playbook Docs]()
Give your tool a clear name and description - together they tell your AI agent what the tool does and when to use it. For extra guidance on when to call it, add that to your instructions.
### In a workflow
Drag an integration step onto the canvas and select the specific tool you want to run. Input variables are mapped explicitly in the step config - the agent doesn't decide whether to call it, the workflow executes it at that point in the flow every time.
Use this when the action is part of a fixed process - for example, always creating a Salesforce case after collecting a complaint, or always sending a confirmation email through Gmail after a booking is made.
![Integration Step Docs]()
# Salesforce tool
Source: https://docs.voiceflow.com/documentation/build/tools/salesforce-tool
Manage leads, contacts, and cases in your Salesforce CRM.
![Salesforce tool cover]()
The Salesforce tool lets your agent interact with your CRM during a conversation. Use it to create leads when users express interest, log support cases, update contact information, or add notes to existing cases for better team visibility.
## Using the Salesforce tool
Add the Salesforce tool to your agent from **Tools** → **Add tool** → **Salesforce**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Salesforce tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ------------------------- | -------------------------------------------- |
| **Create lead** | Create a new lead in Salesforce. |
| **Create contact** | Add a new contact record to Salesforce. |
| **Create case** | Create a new customer service case. |
| **Update lead** | Update details for an existing lead. |
| **Update contact** | Edit information for an existing contact. |
| **Update case** | Modify fields or status of an existing case. |
| **Add comment to a case** | Append a comment to an existing case. |
# Shopify tool
Source: https://docs.voiceflow.com/documentation/build/tools/shopify
Manage customers, orders, and products in your Shopify store.
![Shopifycover]()
The Shopify tool lets your agent interact with your Shopify store during a conversation. Use it to look up order status, find customer information, search your product catalog, or update records when customers request changes.
## Using the Shopify tool
Add the Shopify tool to your agent from **Tools** → **New tool** → **Shopify**. You can also add tools directly from inside a [Playbook](/documentation/build/playbooks) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Shopify tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ---------------- | ------------------------------------------------------------- |
| **Get products** | Search for products on Shopify matching a specified criteria. |
| **Update order** | Update information about an order on Shopify. |
| **Get order** | Search for orders on Shopify matching a specified criteria. |
| **Cancel order** | Cancel a Shopify order. |
## Importing Shopify products into your Knowledge Base
You can import your Shopify product catalog into Voiceflow's [Knowledge base](/documentation/build/importing-data-sources). This lets your agent answer questions about your products, including details like descriptions, pricing, and availability, without needing to call the Shopify API for every query.
To import your Shopify products, go to **Knowledge base** → **Add data source** → **Shopify** inside your project.
# System tools
Source: https://docs.voiceflow.com/documentation/build/tools/system-tools
Built-in tools your agent can use automatically.
![System Tools Docs]()
System tools are native capabilities built directly into Voiceflow that your agent can use without additional setup. Unlike other tools, system tools appear as toggles in the [Agent](/documentation/build/global-prompt) tab and inside [Playbooks](/documentation/build/playbooks). When enabled, your agent decides when to use them based on the conversation context and your instructions.
## Enabling system tools
Open the **Agent** tab or a **Playbook** to see the **System tools** section in the right editor. Toggle a tool on to make it available, or off to disable it. When a system tool is enabled, your agent will automatically use it when appropriate.
## Available system tools
### Knowledge base
The knowledge base tool lets your agent search your [knowledge base](/documentation/build/importing-data-sources) to answer questions. When enabled, your agent will automatically query your knowledge base when it needs information it doesn't already have. This system tool has advances configuration that you can learn about [here](/documentation/build/querying-the-knowledge-base).
### Buttons
The buttons tool allows your agent to generate clickable button options in its responses. Use buttons to offer users quick choices without requiring them to type. When a user clicks a button, it's treated as if they typed the button's label.
### Call forward
The call forward tool forward the active call to a phone number or SIP address. Available in **voice** projects only. Configure a destination phone number (with optional extension) or a SIP endpoint. When enabled, your agent can transfer the call to a live agent or external line when the conversation requires human support.
### Cards
The card tool enables your agent to display rich cards with titles, descriptions, images, and action buttons. Cards are useful for presenting structured information like products, articles, or options.
### Carousels
The carousel tool lets your agent show multiple cards in a horizontally scrollable carousel. Use carousels when you need to present several options or items at once.
### Web search
The web search tool gives your agent the ability to search the web for current information. This is useful when users ask questions that require up-to-date information beyond what's in your knowledge base.
### Skip turn
The skip turn tool lets the agent stay quiet and wait for the user instead of replying. Use it when the user asks for a moment - things like "hold on," "give me a sec," "let me think," or "one moment" - so the agent doesn't talk over them or fill the pause with something unnecessary.
### End
The end tool allows your agent to end the conversation when appropriate. When enabled, your agent can determine when a conversation has reached a natural conclusion and close the session.
## Getting the most out of system tools
System tools come with opinionated descriptions that cover both what they do and when the agent should use them - in most cases you won't need to touch them. You can shape usage further in two places:
* **Edit the Trigger** on a system tool (at the agent or playbook level) to tighten up when it should or shouldn't fire.
* **Add instructions** in your global prompt or playbook for cross-cutting rules that go beyond a single tool.
A few examples of instruction-level rules:
* "Always offer buttons when presenting more than two options"
* "Search the knowledge base before falling back to web search"
* "Only forward calls if the customer explicitly asks to speak to someone"
* "Use cards when showing product details, carousels when showing multiple products"
### Local overrides
System tools enabled at the **agent level** are available across all playbooks by default. Inside a playbook, you can customize a tool's settings and trigger to fit that specific context - but you can't disable a tool that's already enabled at the agent level.
You can, however, **enable** a tool inside a playbook that's turned off at the agent level. For example, you might keep web search off globally but enable it in a single research-focused playbook.
# Twilio tool
Source: https://docs.voiceflow.com/documentation/build/tools/twilio-tool
Send SMS messages from your agent using your Twilio account.
![Twilio tool cover]()
The Twilio tool lets your agent send text messages during a conversation. Use it to send confirmation codes, appointment reminders, order updates, or follow-up information to your users.
## Using the Twilio tool
Add the Twilio tool to your agent from **Tools** → **Add tool** → **Twilio**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Twilio tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ------------ | ------------------------------------------------ |
| **Send SMS** | Send a text message to a specified phone number. |
# Zendesk tool
Source: https://docs.voiceflow.com/documentation/build/tools/zendesk-tool
Manage support tickets, users, and organizations in Zendesk.
![Zendesk tool cover]()
The Zendesk tool lets your agent interact with your Zendesk account during a conversation. Use it to create and update support tickets, look up users, add comments to ongoing cases, or search for existing tickets based on custom criteria.
## Using the Zendesk tool
Add the Zendesk tool to your agent from **Tools** → **Add tool** → **Zendesk**. You can also add tools directly from inside a [Playbook](/documentation/build/steps/playbook) or [Integration step](/documentation/build/steps/integration). Once added, you can call the Zendesk tool from inside a [Playbook](/documentation/build/playbooks) or [Workflow](/documentation/build/workflows).
### Actions
| Action | Description |
| ----------------------- | -------------------------------------------------------------------------------- |
| **Create ticket** | Create a new support ticket with a subject, description, tags, and other fields. |
| **Update ticket** | Modify an existing ticket's priority, status, tags, or other fields. |
| **Add ticket comment** | Append a public or private comment to an existing ticket. |
| **Find ticket(s)** | Search for tickets by user ID, status, or other criteria. |
| **Find latest comment** | Retrieve the most recent comment on a specific ticket. |
| **Find user** | Search for users by email, name, or other identifiers. |
| **Find group** | Look up support groups by ID or name. |
| **Update organization** | Edit an organization's details such as domain, name, or notes. |
For actions that support custom fields, Voiceflow automatically detects and displays the available fields from your Zendesk account.
## Syncing Zendesk Help Center with your Knowledge Base
You can also connect your Zendesk Help Center to Voiceflow's [Knowledge base](/documentation/build/importing-data-sources). This lets your agent answer questions using your existing help articles, product guides, FAQs, and support policies.
To connect your Zendesk Help Center, go to **Knowledge base** → **Add data source** → **Zendesk** inside your project.
# Workflows
Source: https://docs.voiceflow.com/documentation/build/workflows
Deterministic control with AI reasoning baked in wherever you need it.
![Workflow Docs 2]()
Workflows let you build structured, step-by-step logic for your agent. Unlike playbooks, which let the model reason freely toward a goal, workflows follow a defined path - every step executes in order, exactly as you designed it.
Workflows aren't purely scripted. You can embed [playbooks](/documentation/build/steps/playbook), [operators](/documentation/build/steps/operator), [set steps](/documentation/build/steps/set), and [crews](/documentation/build/steps/crew) anywhere in the flow, giving you deterministic control with AI reasoning baked in wherever you need it.
## Creating workflows
From the **Agent** tab, click **+** in the right editor. Select an existing workflow or create a new one.
![Adding Workflows Docs]()
You can also create workflows from within a workflow using the [workflow step](/documentation/build/steps/workflow), or from the workflow CMS tab.
Give your workflow a clear name and trigger. The trigger should cover both what the workflow does and when the agent should route into it - this is what the top-level agent and other playbooks read when deciding whether to call it. ![Create Workflow Docs 1]()
On creation, you'll be taken to the canvas to start building. Workflows added from the agent tab are automatically attached to your agent. Click **×** in the top right to return to the agent tab at any time.
Press 'Run' in the top right, or use the shortcut Shift + R then initiate the workflow. When initiated from on the canvas, your workflow will run in isolation. When initiated from the agent tab, workflow can be called and will run with all previous state.
When running a workflow in Voiceflow, you can see the full logs in real-time, along with canvas follow along. This makes it super easy to de-bug and improve your workflows quickly.
## Steps
Steps are the building blocks of workflows, organized into four categories:
| Category | What it does |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Agentic** | Embed AI reasoning mid-flow using [playbook](/documentation/build/steps/playbook), [crew](/documentation/build/steps/crew), and [operator](/documentation/build/steps/operator) steps |
| **Scripted** | Send [messages](/documentation/build/steps/message), [cards](/documentation/build/steps/card), [carousels](/documentation/build/steps/carousel), [buttons](/documentation/build/steps/buttons), and capture input with [listen](/documentation/build/steps/listen) steps |
| **Tools** | Connect to external services via [integrations](/documentation/build/steps/integration), [APIs](/documentation/build/steps/api), [MCP servers](/documentation/build/steps/mcp), and [functions](/documentation/build/steps/function) |
| **Logic** | Control execution with [set](/documentation/build/steps/set), [conditions](/documentation/build/steps/condition), [code](/documentation/build/steps/code), [workflow](/documentation/build/steps/workflow), [end](/documentation/build/steps/end) and handoff steps |
## Actions
Actions let you keep your canvas clean without losing any functionality.
![Actions Docs]()
To add an action, click any port and then click on empty canvas space to expose the step menu. This is also the fastest way to add steps without dragging from the sidebar.
## Nesting workflows
Workflows can call other workflows using the [workflow step](/documentation/build/steps/workflow). This lets you break complex processes into smaller, reusable pieces - build once, use across multiple workflows. For example, an identity verification workflow can be called from your returns flow, your account management flow, and your payment flow without duplicating the logic in each one.
![Nesting Workflows Docs]()
Workflows only run if they're added to the agent, or referenced directly inside a workflow. If a workflow exists in your project but isn't connected to either, the agent will never use it.
## Entry conditions and required variables
Entry conditions and required variables can only be applied when a workflow is routed to directly by the [agent](/documentation/build/global-prompt). They're not available when the workflow is called via a [workflow step](/documentation/build/steps/workflow) inside another workflow.
Entry conditions and required variables control when the agent can route into a workflow. Until they're met, the workflow stays unavailable, so the agent won't hand off to it no matter what the customer says. This gives you precise, rule-based control over when each workflow becomes reachable.
### Entry conditions
Entry conditions are deterministic checks that must evaluate to true before the workflow can be routed to. If the checks don't pass, the workflow stays unavailable for routing. For example, you could gate a support ticket escalation workflow so only users whose `{account_type}` [variable](/documentation/build/data/variables) is set to `enterprise` are able to escalate tickets to their account manager.
![Clean Shot 2026 06 24 At 18 17 52@2x]()
### Required variables
You can also require that specific variables have a value before the agent can route in. Until every required variable is filled, the workflow stays unavailable. For example, require `{order_id}` before the agent can hand off to a returns workflow, so it never starts without the information it needs.
![Clean Shot 2026 06 24 At 18 21 16@2x]()
# Merging
Source: https://docs.voiceflow.com/documentation/deploy/environments/merging
Bring another environment's changes into Main once you're ready to make them the default.
![Merge Diff]()
Merging replaces `Main`'s live version with the live version of the source [environment](/documentation/deploy/environments), and adds a new entry to `Main`'s version history.
#### Things to know before you merge to Main
* Merges use the source environment's live version, not its draft. Publish that environment first if you want its current edits in the merge.
* Merges replace, they don't combine. Whatever is on the source environment replaces what's on `Main` entirely. Any changes made to `Main` after the source environment was created are overwritten.
If Main has live changes since you created your environment, clone a fresh environment from Main, apply your changes there, and merge that. This avoids overwriting recent work.
## Merging to main
To merge a branch into `Main`, click the more button button on the environment's row in **Settings** → **Environments**.
![Clean Shot 2026 04 29 At 13 09 52@2x]()
The merge modal shows a side-by-side comparison of `Main`'s live version and the source environment's live version. Check **delete environment after merging** if you no longer need it, then click **Merge** to confirm. The new live version appears at the top of `Main`'s version history with a description noting the merge source.
If you leave **delete environment after merging** unchecked, the environment stays in **Settings** → **Environments** with its own version history intact, which is useful when you want to keep iterating on it and merge into `Main` again later.
Checking **delete environment after merging** discards the environment and its version history, including any unpublished draft changes that weren't part of the merge. Publish the environment before merging if you want those changes included.
## Reverting a merge
A merge is a new version on `Main`, so reverting `Main` to the previous version undoes it. Open the [version history](/documentation/deploy/environments/version-history) for `Main`, pick the pre-merge version, and click **Revert**.
![Revert]()
# Environments
Source: https://docs.voiceflow.com/documentation/deploy/environments/overview
Work on multiple versions of your agent in parallel, conduct A/B tests with traffic splits, and roll changes back with confidence.
![Envs Docs]()
Environments are independent copies of your AI agent. This makes it safe to test a change in isolation, compare two versions of your agent against each other (A/B test), or roll out a new version gradually. Environments are independent copies of your AI agent. This makes it safe to test a change in isolation, compare two versions of your agent against each other (A/B test), or roll out a new version gradually.
Each environment has its own [draft version](/documentation/deploy/environments/publishing), **live version,** and independent [version history](/documentation/deploy/environments/publishing#version-history-and-reverting). Every project starts with a single environment called `Main`, which is what your users connect to by default.
## Key concepts
| Concept | What it is |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Environment** | An independent copy of your agent. |
| **Draft version** | An auto-saved working version of the environment, updated as you make edits. |
| **Live version** | The most recently published version of the environment that's [receiving traffic](/documentation/deploy/environments/traffic-split), if configured. |
| **Traffic splitting** | Control what % of live traffic is reaching which environment. |
| **Merging** | Promoting a specific environment to Main. |
| **Version history** | Snapshots of an environments versions over time. |
## Best practices
Use the following workflow for any meaningful change to your agent. `Main` keeps serving users throughout, and you can roll back at any step.
Create a new environment cloned from `Main` and name it after the change(s) you're making.
Work on the new environment and save ⇧⌘S or [publish versions](/documentation/deploy/environments/publishing) as you go.
Once you're happy with the changes, open [**edit traffic split**](/documentation/deploy/environments/traffic-split) and send a small percentage of live traffic to the new environment.
Compare this environment to `Main` using your KPIs in [Analytics](https://docs.voiceflow.com/documentation/measure/analytics), [Evaluations](https://docs.voiceflow.com/documentation/measure/evaluations) and [Transcripts](https://docs.voiceflow.com/documentation/measure/transcripts).
If this environments proves to be performing better than Main, [merge](/documentation/deploy/environments/merging) the environment to `Main`. Delete the environment on merge to keep your project clean.
Repeat this process to continually improve your agent over time.
Each project supports up to 10 environments, including Main. If you're close to the limit, merge or delete the ones you no longer need.
## Managing environments
You can manage a project's environments from **Settings** → **Environments** when editing a project. Or click the environment name in the left menu under the project name and press 'view all'.
![Clean Shot 2026 04 29 At 13 09 52@2x]()
### Creating an environment
Click **New environment** in the top right. Give the environment a name, pick an environment to **Clone from**, and click **Create**.
![New Env]()
Most of content from the environment that you chose to clone from will be copied into your new environment - see below for the exceptions.
| Data type | Behaviour when cloning |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflows, playbooks, and tools | Cloned into the new environment. |
| Agent configuration (model, instructions, guardrails) | Cloned into the new environment. |
| Widget settings | Cloned into the new environment. |
| Variables | Cloned into the new environment. |
| Knowledge base documents | The contents of each knowledge base document are shared project-wide. The list of documents included in the original environment is cloned into the new environment. This means that adding or removing documents in the knowledge base is environment-specific, but modifying a document affects all environments that contain that document. |
| Knowledge base metadata | Environment specific. Adding or removing metadata from a document only affects a specific environment. |
| Knowledge base [integrations](/documentation/build/importing-data-sources) (Shopify and Zendesk) | Shared project-wide. |
| Phone numbers | Shared project-wide, but assigned to a specific environment. |
| Secrets | Shared project-wide, with [per-environment overrides](/documentation/build/data/secrets) available for both draft and live versions of each environment. |
| Evaluations | Shared project wide. Results can be filtered to a specific environment and version. |
| Analytics | Shared project wide. Data can be filtered to a specific environment and version. |
### Switching between environments
Use the environment switcher at the top of the sidebar of any page inside your project to switch between environments. You can edit any environment, including ones your users are currently interacting with. Edits only affect the draft version until you [publish your environment](/documentation/deploy/environments/publishing).
![Env Switching]()
### Cloning to new environment
Press the dropdown arrow next to the publish button, and select **Clone environment** to clone the current draft version to a new environment.
![Env Clone]()
### Discarding changes
Press the dropdown arrow next to the publish button, and select **Discard changes** to open a diff view where you can confirm the selection.
![Envdiscard]()
### Aliases
Every environment has a short, URL-safe **alias** used in API calls, the chat widget, and any other programmatic reference. `Main`'s alias is `main`. Aliases don't change when you rename an environment, so integrations keep working.
Copy an environment's alias from the **Alias** column in **Settings** → **Environments**.
### Legacy projects
Projects created before environments launched use three fixed environments (Development, Staging, and Production) with aliases `development`, `staging`, and `production`. These keep working until you opt into migration.
After migrating, update integrations that use the legacy aliases, including the [chat widget snippet](/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads). If you're making use of the [start session API endpoint](/api-reference/v4interact/start-session-specific-environment), you'll also need to update this to point to the `main` environment, rather than `production`.
# Publishing
Source: https://docs.voiceflow.com/documentation/deploy/environments/publishing
Preview your changes before publishing, see every version, and roll back when you need to.
![Publish]()
Each [environment](/documentation/deploy/environments/overview) has a draft version that auto-saves as you edit. Publishing promotes the draft to the live version. Every publish and restore is recorded in version history, giving you a clear record of changes over time.
## Publishing a new version
Click **Publish** in the top right corner while editing your project to open the diff view:
![Publish Diff]()
The publish view shows a side-by-side diff view of the current live version and your draft version. Give the new version a name (a version number is filled in for you), add a description of what changed, and click **Publish**. The new version replaces whatever was previously live and happens near instantly.
**Tip:** we recommend that you always add a version description. Without one, it's hard to track what changed across versions if you ever need to revert a change.
# A/B testing
Source: https://docs.voiceflow.com/documentation/deploy/environments/traffic-split
Split traffic across multiple environments at once for A/B testing and gradual rollouts.
![Traffic Splitting 2]()
Traffic splitting allows you to assign a percentage of incoming traffic to different [environments](/documentation/deploy/environments). Allowing for A/B testing, and gradual rollouts.
Individual users stay on the same environment across sessions so their experience is consistent.
## When to use a traffic split
Use a traffic split when you want to measure a meaningful change before it reaches everyone, or compare two approaches head-to-head in production. For small, well-understood edits - copy tweaks, typos, minor prompt updates - you can simply edit `Main` and publish.
Once an environment has been validated as the winner, you should [merge it back into ](/documentation/deploy/environments/merging)`Main` rather than leave it running under a traffic split.
Use the Main environment as the source of truth for your agent. Once a change is ready - or an A/B test resolves in favour of the new environment - merge it back into Main, rather than leaving another environment serving 100% of traffic indefinitely.
## Editing traffic split
Click **Edit traffic split** in the top right of **Settings** → **Environments**. Add a row for each environment you want to include, set its percentage, and click **Deploy**. Percentages must add up to 100%. Removing an environment from the traffic split prevents users from automatically being routed to it but doesn't remove the environment from your project.
When a traffic split is changed, the new settings will only be enforced for new sessions. Existing sessions will continue on their current environment.
## Recommended rollout
Create a new environment cloned from `Main` and name it after the change(s) you're making.
Work on the new environment and save ⇧⌘S or [publish versions](/documentation/deploy/environments/publishing) as you go.
Once you're happy with the changes, open [**edit traffic split**](/documentation/deploy/environments/traffic-split) and send a small percentage of live traffic to the new environment.
Compare this environment to `Main` using your KPIs in [Analytics](https://docs.voiceflow.com/documentation/measure/analytics), [Evaluations](https://docs.voiceflow.com/documentation/measure/evaluations) and [Transcripts](https://docs.voiceflow.com/documentation/measure/transcripts).
If this environments proves to be performing better than the live version of Main, [merge](/documentation/deploy/environments/merging) the environment to `Main`. Delete the environment on merge to keep your project clean.
Repeat this process to continually improve your agent over time.
## Considerations
* Users are automatically routed to an environment based on your specified traffic split. You can't pick specific users or cohorts to land on a particular environment. If you need cohort-based routing, pass a specific environment alias when your users connect (for example, in your [chat widget](/documentation/deploy/widget/embedding-the-chat-widget) snippet) instead of relying on this feature.
* Traffic split applies to every way your users connect to your agent (chat widget, phone, API, custom clients). If you need different routing per channel, point each channel at a specific [environment alias](/documentation/deploy/environments/overview#aliases).
![Traffic Splitting 2]()
# Version history
Source: https://docs.voiceflow.com/documentation/deploy/environments/version-history
Open the version history from the history icon next to an environment in **Settings** → **Environments**.
![Version History 2]()
Each entry shows the version number, description, author, and publish time. The **Live** label marks the version your users currently interact with.
Click any version to open a comparison against the live version of the environment. From there you can:
* Click **Revert** to make the selected version live again. A new version is added to the history with a description noting which version you reverted from.
* Click **Clone to new environment** to create a new environment starting from the selected version.
![Revert]()
Reverting only affects the environment you revert on; other environments are unchanged.
# Connecting a phone number
Source: https://docs.voiceflow.com/documentation/deploy/phone/connect-a-phone-number
Connect a phone number to your agent to enable voice calls over the phone.
![Cover Placeholder]()
You can connect phone numbers to your agent from the **Phone numbers** tab in the sidebar. Voiceflow supports numbers from multiple providers, or you can provision a number directly through Voiceflow. Once connected, your number can receive [inbound calls](/documentation/deploy/phone/inbound-calling) and make [outbound calls](/documentation/deploy/phone/outbound-calling) through your agent.
## Adding a phone number
Open **Phone numbers** in the sidebar and click **Create number**. Select your provider and enter the required credentials.
* **Voiceflow number**: Voiceflow can provision a US or Canadian phone number for you. Select an area code and optionally give it a name. The number of Voiceflow numbers included depends on your [plan](https://voiceflow.com/pricing).
* **Twilio**: You'll need your phone number, Account SID, and Auth Token from your [Twilio console](https://console.twilio.com/).
* **Vonage**: You'll need your phone number, API Key, and API Secret from your [Vonage dashboard](https://dashboard.nexmo.com/).
* **Telnyx**: You'll need your phone number and API Key from your [Telnyx portal](https://portal.telnyx.com/).
## Assigning an existing number
If you've already connected a phone number to another project in your workspace, you can reuse it. Click **Assign existing number** to see all available numbers in your workspace and assign one to the current project.
## Routing calls to an environment
By default, a phone number linked to an agent routes each incoming call according to the [traffic split](/documentation/deploy/environments/traffic-split) configured in **Settings** → **Environments**, so the A/B tests and gradual rollouts you've set up for the rest of your agent apply to phone calls too.
If you'd rather point a phone number to a specific environment, this can be configured when linking the phone number or from the **Phone numbers** tab. Phone numbers can be pointed at the live or draft version of any environment. Once assigned, every call to that number goes to the version you selected, regardless of the traffic split.
![Clean Shot 2026 04 30 At 23 54 29@2x]()
Routing a phone number to a draft is useful for testing changes by phone before publishing them. Switch back to **Published** when you're ready for callers to get the live experience again.
## Enabling call recording
You are responsible for complying with laws related to call recording and consent in your region.
You can record calls for quality assurance and compliance. Open **Transcripts** → **Transcript settings** and enable **Save call recordings**. Recordings are stored by Voiceflow and [linked to the call's transcript](/documentation/measure/transcripts).
Call recording is only available for phone calls. Voice conversations through the [chat widget](/documentation/deploy/widget/embedding-the-chat-widget) cannot be recorded.
## Removing a phone number
To remove a number from your project, click the three dots menu next to it and select **Remove**. The phone number will remain linked to your Voiceflow account and can still be reused in other projects using the **Assign existing number** button at the top of the **Phone numbers** tab.
To fully unlink a phone number from your Voiceflow account, go to **Voiceflow Dashboard** → **Phone numbers**, then click the three dots menu next to the phone number and select **Delete**.
# Inbound calling
Source: https://docs.voiceflow.com/documentation/deploy/phone/inbound-calling
Receive phone calls and route them to your agent automatically.
Once a phone number is [connected to your project](/documentation/deploy/phone/connect-a-phone-number), incoming calls are automatically routed to your agent.
## How it works
When someone calls your connected phone number, Voiceflow routes the call based on how the number is configured:
* **Assigned to an environment:** every call goes to that environment, using either its **Published** (live) version or its **Draft**, depending on which you picked when assigning.
* **Unassigned:** calls follow the [traffic split](/documentation/deploy/environments/traffic-split) configured in **Settings** → **Environments**, just like chat sessions and API conversations.
To change a number's assignment, click the environment label next to the number in the **Phone numbers** tab. See [Routing calls to an environment](/documentation/deploy/phone/connect-a-phone-number#routing-calls-to-an-environment) for the full flow.
![Phone Env Change]()
## Caller identification
When a call comes in, the caller's phone number is automatically set as the `user_id` [variable](/documentation/build/data/variables). This lets you identify returning callers and personalize conversations based on their information.
## Testing draft changes by phone
While you're working on a change, point a non-production phone number at the environment's **draft** **version**. Calls to that number use your unpublished work, so you can dial in and verify the change yourself before publishing. A phone number that real callers use should never be pointed at a draft.
## Testing changes with real callers
When you want to validate a change against `Main` using real call data, use a [traffic split](/documentation/deploy/environments/traffic-split). Clone `Main`, make and publish your change in the new environment, then route a small percentage of phone traffic to it. Compare the results in [Analytics](/documentation/measure/analytics) and [Transcripts](/documentation/measure/transcripts), and once you're confident, [merge the environment](/documentation/deploy/environments/merging) back into `Main`.
# Outbound calling
Source: https://docs.voiceflow.com/documentation/deploy/phone/outbound-calling
Programmatically trigger your agent to call any phone number.
In some regions, automated outbound calls without consent may violate local regulations. You are responsible for ensuring compliance with all relevant laws.
Outbound calling lets your agent initiate phone calls programmatically. You can use this to automate voice interactions like welcome calls, appointment reminders, or follow-ups, triggered from tools like Zapier or your own backend scripts.
Outbound calling is supported for Twilio, Vonage, and Telnyx phone numbers. Voiceflow phone numbers currently don't support outbound calling.
## Making an outbound call
To trigger an outbound call, send a `POST` request to your agent's outbound API endpoint. You can find this endpoint by opening **Phone numbers** in the sidebar, then clicking **View** in the **Outbound call API** column for your number.
The modal displays a ready-to-use curl command with your agent's endpoint and required headers. You can also test the call directly from this modal by entering a phone number and clicking **Call**.
## API reference
### Endpoint
```
POST https://runtime-api.voiceflow.com/v1/phone-number//outbound
```
### Headers
| Header | Value |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `Authorization` | Your [Dialog Manager API key](https://docs.voiceflow.com/reference/how-to-get-your-voiceflow-project-api-key) |
| `Content-Type` | `application/json` |
### Request body
```json theme={null}
{
"to": "+15551234567",
"variables": {
"user_name": "Jane",
"account_type": "Premium"
},
"amd": true
}
```
| Field | Description |
| ----------- | ---------------------------------------------------------------------------- |
| `to` | The phone number to call in E.164 format (eg: `+15551234567`). |
| `variables` | Optional. A JSON object containing variables to inject when the call starts. |
| `amd` | Optional. Set to `true` to enable answering machine detection. |
## Concurrency limits
Outbound calls share the same concurrency pool as inbound calls. The number of simultaneous calls you can make depends on your [plan limits](https://voiceflow.com/pricing).
# Customize widget
Source: https://docs.voiceflow.com/documentation/deploy/widget/custom-web-chat-styling
Customize the Voiceflow web chat widget's styling, modality, and file upload settings to match your brand and product requirements.
## Customizing your widget
Your widget should match your brand. From the **Widget** settings page, scroll down to configure your agent's colors, icons, launcher style, interface type, and more. You can also add placeholder text and privacy policy links. Customers on a Business plan can disable Voiceflow branding.
## Choosing a modality
The widget supports two modalities: chat and voice. You can configure this in **Widget** → **Modality & Interface** → **Modality**.
**Chat modality** is the default. Users type messages and see responses as text. This works well for most web use cases. With chat modality, you can optionally enable voice features:
* **Dictation** allows users to input text using speech-to-text.
* **Voice output** lets users hear responses using the text-to-speech model configured in your project settings.
* **Voice mode** enables hands-free conversation. Once the user presses the voice button, they can speak naturally without pressing it again for each message.
**Voice modality** makes the conversation behave like a phone call. Message history isn't displayed to the user, and they don't need to press a button to speak. Users can interrupt the agent by speaking while it responds. The written transcript is still saved for your records.
Voice features consume credits. [Learn more about credits](/documentation/account-management/billing/credits-pricing-table).
## Enabling file uploads
You can let users attach files to their messages so your agent can read and act on their contents. When a user uploads a file, Voiceflow extracts its contents using an LLM and keeps them available to your agent for the rest of the conversation, so the agent can answer questions about a document, summarize it, or use its details to complete a task.
To turn file uploads on, open **Widget** → **Modality & Interface** and enable **Allow file attachments**. You can then set a **Max files per conversation** limit.
Processing uploaded files consumes credits. [Learn more about credits](/documentation/account-management/billing/credits-pricing-table).
### Supported files and limits
* **Maximum file size:** 5 MB per file.
* **Supported formats:** PDF, JPEG, JPG, PNG, and WEBP.
* **Multiple files:** users can attach more than one file in a single turn.
* **Files per conversation:** you must set a cap on the total number of files a user can upload across a conversation. The maximum (and default) is 10 files per conversation, and you can lower this limit.
Voiceflow extracts up to roughly 16,000 tokens of text from each file. For very large documents (eg: a long PDF), any content beyond this limit is truncated, so your agent only sees the earlier portion of the file.
### How users upload files
Users attach files directly from the widget's message input. Before sending, they can preview images in a lightbox, download them, or remove any file they added by mistake. If a user adds more files than your per-conversation limit allows, they can't send their message until they remove enough files to fit within the cap.
![Widget file upload]()
### File storage and privacy
By default, uploaded files are stored in a private Voiceflow storage bucket and are never publicly accessible. Voiceflow reaches each file through a temporary, pre-signed URL that is authenticated against the user's session. When a file appears in a [transcript](/documentation/measure/transcripts), access is authenticated based on whether the viewer can open that transcript.
Uploaded files are deleted automatically when their associated transcript is deleted, so a file's lifetime always matches its transcript.
PII redaction does not currently apply to uploaded files. If you have [PII redaction](/documentation/build/data/pii-redaction) enabled, the contents of uploaded files are not redacted. Avoid file uploads in flows that handle sensitive personal information until this is supported.
### Bringing your own storage
The widget always stores uploaded files in Voiceflow's secure storage bucket. At this time, using your own storage bucket is not supported directly in the widget. If your use case requires files to be stored outside of Voiceflow, you can build a custom integration using the [API](/api-reference/api-overview), which supports passing file URLs in your requests on the latest streaming and non-streaming interact endpoints.
Send a `file` action with a URL Voiceflow can fetch for each file:
```json theme={null}
{
"action": {
"type": "file",
"payload": {
"text": "Please review this receipt",
"files": [
{
"url": "https://example.com/files/receipt.pdf",
"mimeType": "application/pdf",
"filename": "receipt.pdf",
"size": 245760
}
]
}
}
}
```
The `text` field is optional. You can include multiple files in the `files` array. Voiceflow fetches each file from the URL you provide, extracts its contents, and makes them available to your agent for the rest of the conversation.
We recommend keeping files in private storage and passing short-lived, pre-signed GET URLs. That lets Voiceflow download the file only for the time needed to process it, without making the object permanently public.
When you bring your own storage, uploaded files are not shown in [transcripts](/documentation/measure/transcripts). Voiceflow does not store a lasting copy of the file, so it can't reliably reopen the URL later.
## Configuring security settings
Three **Security** options are available at the bottom of the widget settings page:
* **Approved domains** restricts the widget to work only on specified websites.
* **Legal disclaimer** displays a message users must accept before chatting. Enable this if your company policy or local regulations require it.
* **Chat transcript saving** controls whether conversations are saved as [transcripts](/documentation/measure/transcripts). Disable this when processing sensitive information.
Please note that these settings are only configurable on workspaces with a Business or Enterprise plan.
## Publishing changes
Any changes to widget settings require you to [publish a new version of your agent](/documentation/deploy/environments/publishing) before they take effect in production.
## Developer customization
If you're a developer, you can extend the widget's functionality through the [chat widget API](/documentation/deploy/widget/web-chat-api), custom styling, and [extensions](/documentation/deploy/widget/web-chat-extensions).
For most use cases, the built-in widget customization options in **Widget** settings are sufficient. But if you need more visual control, you can customize the widget's appearance with your own CSS or by passing additional configuration options in the `chat.load()` function.
### Using built-in styling options
You can control the widget's appearance directly in your `chat.load()` configuration using the `assistant` object. Here's an example with the available styling parameters:
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
assistant: {
title: 'Support Chat',
description: 'How can I help you today?',
image: 'https://example.com/avatar.png',
color: '#3D82E2',
launcher: 'https://example.com/launcher-icon.png',
stylesheet: 'https://example.com/custom-styles.css'
}
});
```
### Visual & behavioural overrides
These override the remote publishing configuration fetched from the Voiceflow API. All fields are optional but local overrides take priority over remote settings.
### Widget Type
| **Property** | **Type** | **Description** |
| :----------- | :------------------------ | :--------------- |
| `type` | `'chat'` or `'voice'` | Widget type |
| `renderMode` | `'widget'` or `'popover'` | Chat render mode |
### Header
| **Property** | **Type** | **Description** |
| :----------------- | :-------- | :---------------------- |
| `header.hideImage` | `boolean` | Hide the header image |
| `header.imageUrl` | `string` | Custom header image URL |
| `header.title` | `string` | Custom header title |
### Welcome banner
| **Property** | **Type** | **Description** |
| :------------------- | :-------- | :---------------------- |
| `banner.hide` | `boolean` | Hide the welcome banner |
| `banner.title` | `string` | Banner title |
| `banner.description` | `string` | Banner description |
| `banner.imageUrl` | `string` | Banner image URL |
### Agent avatar
| **Property** | **Type** | **Description** |
| :---------------- | :-------- | :---------------------- |
| `avatar.hide` | `boolean` | Hide the agent avatar |
| `avatar.imageUrl` | `string` | Custom avatar image URL |
### Input
| **Property** | **Type** | **Description** |
| :----------------- | :------- | :--------------------------- |
| `inputPlaceholder` | `string` | Input field placeholder text |
### Launcher
| **Property** | **Type** | **Description** |
| :------------------ | :-------------------- | :-------------------------- |
| `launcher.type` | `'icon'` or `'label'` | Launcher button style |
| `launcher.label` | `string` | Text label for the launcher |
| `launcher.imageUrl` | `string` | Custom launcher image URL |
### Footer
| **Property** | **Type** | **Description** |
| :---------------- | :-------- | :------------------- |
| `footer.hide` | `boolean` | Hide the footer link |
| `footer.linkText` | `string` | Footer link text |
| `footer.linkUrl` | `string` | Footer link URL |
### Appearance
| **Property** | **Type** | **Description** |
| :----------- | :-------- | :------------------------------------------------------ |
| `color` | `string` | Primary brand color (see Color section below) |
| `palette` | `Palette` | Full color palette override (see Palette section below) |
| `fontFamily` | `string` | Font family name (use `'inherit'` for page font) |
### Position
| **Property** | **Type** | **Description** |
| :--------------- | :-------------------- | :-------------------------------------------------------- |
| `side` | `'left'` or `'right'` | Widget position side |
| `spacing.side` | `string` | Distance from the side edge (see Spacing section below) |
| `spacing.bottom` | `string` | Distance from the bottom edge (see Spacing section below) |
### AI disclaimer
| **Property** | **Type** | **Description** |
| :------------------ | :-------- | :--------------------- |
| `aiDisclaimer.hide` | `boolean` | Hide the AI disclaimer |
| `aiDisclaimer.text` | `string` | Disclaimer text |
### Behavior
| **Property** | **Type** | **Description** |
| :------------------ | :----------------------------- | :---------------------------------- |
| `streamingDisabled` | `boolean` | Disable streaming message animation |
| `persistence` | `'localStorage'` or `'memory'` | Session persistence strategy |
### External additions
| **Property** | **Type** | **Description** |
| :----------- | :--------------- | :------------------------ |
| `stylesheet` | `string` | Custom CSS stylesheet URL |
| `extensions` | `AnyExtension[]` | Custom extensions |
## Color, Palette, and Spacing
### `color`
**Type:** `string` (any valid CSS color parseable by chroma-js)
**Default:** `#387dff`
The primary brand color used throughout the widget (buttons, links, active states, header accents). The value is parsed by chroma-js, which supports multiple formats:
| **Format** | **Example** | **Notes** |
| :-------------- | :------------------------- | :----------------------- |
| Hex (6-digit) | `#387dff` | Most common, recommended |
| Hex (3-digit) | `#38f` | Shorthand hex |
| Hex with alpha | `#387dff80` | 8-digit hex with alpha |
| Named CSS color | `tomato`, `cornflowerblue` | CSS named colors |
| RGB | `rgb(56, 125, 255)` | CSS rgb() function |
| HSL | `hsl(220, 100%, 61%)` | CSS hsl() function |
When `color` is provided without a `palette`, the widget auto-generates a full 10-shade palette using HSL interpolation. The `color` value becomes shade 500 (the base), and lighter/darker shades are computed by varying the lightness.
**Examples:**
```javascript theme={null}
// Default blue
assistant: { color: '#387dff' }
// Brand red
assistant: { color: '#dc2626' }
// Using a named color
assistant: { color: 'tomato' }
// Dark green
assistant: { color: 'hsl(150, 60%, 30%)' }
```
### `palette`
**Type:** Object with 10 required shade keys (all hex strings)
**Default:** Auto-generated from `color` via HSL interpolation
A full color palette that gives you precise control over every shade the widget uses. If provided, this overrides the auto-generated palette entirely. All 10 shades are required.
| **Key** | **Role** | **Typical Usage** |
| :------ | :------------- | :------------------------------------ |
| `50` | Lightest | Subtle backgrounds, hover states |
| `100` | Very light | Light backgrounds |
| `200` | Light | Secondary backgrounds, borders |
| `300` | Medium-light | Inactive/disabled states |
| `400` | Medium | Secondary text, icons |
| `500` | Base (primary) | Primary buttons, links, active states |
| `600` | Medium-dark | Hover states on primary elements |
| `700` | Dark | Active/pressed states |
| `800` | Very dark | High-contrast text |
| `900` | Darkest | Maximum contrast |
**Example - custom blue palette:**
```javascript theme={null}
assistant: {
color: '#387dff',
palette: {
50: '#e7f5fd',
100: '#c6e4fb',
200: '#a2d2fa',
300: '#87bffb',
400: '#659ffd',
500: '#387dff',
600: '#2f68db',
700: '#264eb4',
800: '#1c368e',
900: '#0f1e61',
},
}
```
**Example - warm coral palette:**
```javascript theme={null}
assistant: {
color: '#f97316',
palette: {
50: '#fff7ed',
100: '#ffedd5',
200: '#fed7aa',
300: '#fdba74',
400: '#fb923c',
500: '#f97316',
600: '#ea580c',
700: '#c2410c',
800: '#9a3412',
900: '#7c2d12',
},
}
```
> **How auto-generation works:** When only `color` is provided, `createPalette(color)` extracts the hue (H) and saturation (S) from the color, then generates shades by varying lightness from 95% (shade 50) down to 5% (shade 900). The original color is used as-is for shade 500.
> **Tip:** When providing both `color` and `palette`, make sure `palette[500]` matches `color` for consistency. If they differ, `palette` takes priority for rendering while `color` is effectively ignored.
### `spacing`
**Type:** `{ side?: string, bottom?: string }`
**Default:** `{ side: '30', bottom: '30' }` (30 pixels each)
Controls the position of the widget relative to the viewport edges. The value is a **numeric string representing pixels** The `px` unit is appended automatically. Only effective in overlay mode.
* `spacing.side` Distance from the left or right edge (determined by the `side` property)
* `spacing.bottom` Distance from the bottom edge
**Examples:**
```css theme={null}
// Default positioning (30px from side and bottom)
assistant: {
spacing: { side: '30', bottom: '30' },
}
// Tight to the corner
assistant: {
side: 'right',
spacing: { side: '10', bottom: '10' },
}
// Large offset from the left
assistant: {
side: 'left',
spacing: { side: '60', bottom: '40' },
}
// Only override bottom spacing
assistant: {
spacing: { bottom: '80' },
}
```
## Applying custom CSS
To go beyond the built-in options, you can write CSS rules that override the widget's default styles. Chat widget elements use class names prefixed with `.vfrc-`.
For example, to change the background color of agent messages:
```css theme={null}
.vfrc-system-response .vfrc-message {
background-color: #000000;
color: #FFFFFF;
}
```
### Supported CSS classes
Voiceflow provides a list of supported CSS classes that you can modify. While the widget has additional classes beyond those listed below, modifying them is at your own risk. Only the classes listed below are officially supported.
| **Class Name** | **Element** |
| :----------------------------- | :--------------------------- |
| `vfrc-widget` | Root widget container |
| `vfrc-chat` | Chat window |
| `vfrc-launcher` | Launcher button |
| `vfrc-header` | Chat header |
| `vfrc-footer` | Chat footer |
| `vfrc-message` | Individual message |
| `vfrc-system-response` | System/agent response |
| `vfrc-user-response` | User message |
| `vfrc-chat-input` | Input text area |
| `vfrc-button` | Action button |
| `vfrc-card` | Card component |
| `vfrc-carousel` | Carousel container |
| `vfrc-image` | Image component |
| `vfrc-avatar` | Agent avatar |
| `vfrc-typing-indicator` | Typing dots |
| `vfrc-proactive` | Proactive message container |
| `vfrc-proactive__card` | Individual proactive message |
| `vfrc-proactive__close-button` | Proactive close button |
| `vfrc-prompt` | Quick reply prompt |
| `vfrc-feedback` | Feedback buttons |
```css theme={null}
/*
PAGE ELEMENTS
Customize the page that the chat bubble lives on
*/
/* .voiceflow-chat {} */
/* .vfrc-launcher {} */
/* .vfrc-chat--overlay {} */
/* .vfrc-prompt {} */
/*
CHAT WIDGET HEADER
Customize the header content, controls, and assistant information
*/
/* .vfrc-header {} */
/* .vfrc-assistant-info {} */
/* .vfrc-assistant-info--title {} */
/* .vfrc-assistant-info--description {} */
/* .vfrc-avatar {} */
/* .vfrc-icon {} */
/*
CHAT MESSAGE BODY
Customize the chat body layout and conversation metadata
*/
/* .vfrc-chat {} */
/* .vfrc-chat--dialog {} */
/* .vfrc-chat--spacer {} */
/* .vfrc-chat--session-time {} */
/* .vfrc-chat--status {} */
/* .vfrc-message {} */
/* .vfrc-timestamp {} */
/*
ASSISTANT RESPONSES
Customize assistant response message styles
*/
/* .vfrc-system-response {} */
/* .vfrc-system-response--indicator {} */
/* .vfrc-system-response--controls {} */
/* .vfrc-system-response--list {} */
/* .vfrc-system-response--actions {} */
/* .vfrc-system-response .vfrc-message {} */
/* .vfrc-system-response .vfrc-button {} */
/* .vfrc-button {} */
/* .vfrc-image {} */
/* .vfrc-image--background {} */
/* .vfrc-card--content {} */
/* .vfrc-card--header {} */
/* .vfrc-card--description {} */
/* .vfrc-carousel {} */
/* .vfrc-carousel--button {} */
/*
USER RESPONSES
Customize user response message styles
*/
/* .vfrc-user-response {} */
/* .vfrc-user-response .vfrc-message {} */
/*
FOOTER
Customize the message input field and branding
*/
/* .vf-footer {} */
/* .vfrc-input {} */
/* .vfrc-chat-input--button {} */
/* .vfrc-footer--watermark {} */
```
### Loading your stylesheet
Once you've written your CSS, you can pass it to the widget in two ways.
**Option 1: Link a hosted stylesheet**
Host your CSS file and provide the URL in the `assistant.stylesheet` property:
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
assistant: {
stylesheet: 'https://example.com/custom-styles.css'
}
});
```
**Option 2: Embed CSS as a data URL**
If you don't want to host a separate file, encode your CSS as a base64 data URL and include it inline:
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
assistant: {
stylesheet: 'data:text/css;base64,LnZmcmMtc3lzdGVtLXJlc3BvbnNlIC52ZnJjLW1lc3NhZ2UgeyBiYWNrZ3JvdW5kLWNvbG9yOiAjMDAwMDAwOyBjb2xvcjogI0ZGRkZGRjsgfQ=='
}
});
```
You can use an online tool or run `btoa()` in your browser console to encode your CSS to base64.
# Install widget
Source: https://docs.voiceflow.com/documentation/deploy/widget/embedding-the-chat-widget
Add your agent to your website in minutes.
![Widget Example]()
The quickest way to launch your agent is with the chat widget. You can deploy it to production in minutes, making it ideal for customer support, lead capture, or any use case where users interact with your agent through a website. The widget supports text and voice input, and can be displayed as a floating widget, popover, or embedded directly into your page.
## Adding the widget to your website
Before adding the widget, you'll need to [publish a version of your agent](/documentation/deploy/environments/publishing). Once published, open the **Widget** tab in the sidebar, then copy the code snippet into your website's codebase. The snippet points at your project's default environment (**Main**) by default. To point the widget at a different environment, see [Choosing which environment the widget loads](/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads). If you're not a developer and aren't sure where to add this code, [try asking ChatGPT](http://chatgpt.com/?hints=search\&q=How%20can%20I%20add%20custom%20JavaScript%20to%20a%20\[your%20website%20platform]%20website?).
Your widget should match your brand. From the **Widget** settings page, scroll down to configure your agent's colors, icons, launcher style, interface type, and more. You can also add placeholder text and privacy policy links. Customers on a Business plan can disable Voiceflow branding.
# Chat widget API
Source: https://docs.voiceflow.com/documentation/deploy/widget/web-chat-api
Customize the chat widget to meet your needs.
Voiceflow's chat widget API gives you programmatic control over the [widget's](/documentation/deploy/widget/embedding-the-chat-widget) behavior. You can customize how conversations persist, pass in user data, trigger intents, send proactive messages, and listen for events.
## Understanding the default snippet
When you copy the widget code from **Widget** in the sidebar, you get a snippet like this:
```javascript theme={null}
```
The `chat.load()` function initializes the widget. You can extend it with additional configuration options described in this guide.
## Choosing which environment the widget loads
By default, the widget respects your project's [traffic split](/documentation/deploy/environments/traffic-split): each new session is routed to an environment based on the split you've configured, so the widget works with A/B tests and gradual rollouts without any extra configuration.
To force the widget to load a specific environment, pass that environment's alias as `versionID`. Copy the alias from the **Alias** column in **Settings** → **Environments**.
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
versionID: 'my-feature'
});
```
When `versionID` is set, the widget loads that environment's live version and ignores the traffic split. If the environment has no published version yet, the widget won't render any messages.
If your project was created before environments launched and has not yet been migrated, the legacy `development`, `staging`, and `production` values continue to work as `versionID`. After migrating, update your snippet to use your new environment aliases (or remove `versionID` to use the traffic split).
## Setting the runtime URL
This feature is only available to Enterprise customers who are hosted on a Private Cloud.
The `url` property defines the runtime endpoint the widget communicates with. Private Cloud customers should replace the default URL with their dedicated runtime endpoint provided by Voiceflow.
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://your-private-cloud-endpoint.com'
});
```
## Configuring chat persistence
Chat persistence determines whether users return to an ongoing conversation or start fresh when they reload the page, open a new tab, or come back later. Configure this with the `persistence` property inside the `assistant` object.
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
assistant: {
persistence: 'localStorage'
}
});
```
| Option | Behavior |
| ---------------- | ----------------------------------------------------------------------------- |
| `localStorage` | Default. Conversations persist across page reloads and browser sessions. |
| `sessionStorage` | Conversations persist across page reloads but reset when all tabs are closed. |
| `memory` | Conversations reset on every page reload or new tab. |
## Passing a custom user ID
You can assign a unique ID to each user with the `userID` property. This ID becomes available in your agent as the built-in `{user_id}` variable, which is useful for identifying users across sessions and personalizing interactions.
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
userID: 'user_12345'
});
```
## Passing custom variables
You can pre-fill variables when the widget loads using the `launch.event.payload` field. These values populate the `last_event` system variable and can be accessed using [Code step](/documentation/build/steps/code).
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
launch: {
event: {
type: 'launch',
payload: {
user_name: 'Mary',
user_email: 'mary@example.com'
}
}
}
});
```
These values can be accessed using a Code step in the format shown below. Many users use an [initialization workflow](/documentation/build/framework/initialization-workflow) to run logic based on these values.
```javascript theme={null}
user_name = last_event.payload.user_name
user_email = last_event.payload.user_email
```
Note that the Code step can't create new [variables](/documentation/build/data/variables). You'll need to create `user_name` and `user_email` as variables in your project first. Also, `last_event` is updated on each user interaction (eg: when the widget loads, an intent triggers, or a button is clicked), so capture these values at the start of the conversation.
## Annotating transcripts with metadata
You can pass user profile information that appears in your [Transcripts](/documentation/measure/transcripts). This metadata is for labeling conversations in the UI only and isn't available to your agent's logic.
```javascript theme={null}
window.voiceflow.chat.load({
verify: { projectID: 'YOUR_PROJECT_ID' },
url: 'https://general-runtime.voiceflow.com',
user: {
name: 'Mary',
image: 'https://example.com/avatar.jpg'
}
});
```
## API methods
Once the widget script loads, it registers the API as `window.voiceflow.chat`. You can use these methods to control the widget programmatically.
| Method | Description | Available in overlay mode | Available in embedded mode |
| :---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------: | :------------------------: |
| `load({ config })` | Initializes the chat widget. Parses configuration, fetches remote assistant settings from the Voiceflow API. Nothing works until `load` is called. | Yes | Yes |
| `open()` | Opens the chat window. If the session is idle, also triggers the launch event (starts the conversation). Emits a `voiceflow:open` broadcast event. Only effective in overlay mode. | Yes | No |
| `close()` | Closes the chat window, interrupts audio, clears no-reply timeouts, and saves the session. Emits a `voiceflow:close` broadcast event. Only effective in overlay mode. | Yes | No |
| `destroy()` | After calling this, all methods become no-ops until `load` is called again.. | Yes | Yes |
| `show()` | Shows the widget again after it was hidden with `hide()`. Only effective in overlay mode. | Yes | No |
| `hide()` | Hides the entire widget (chat window AND launcher button) from view. Only effective in overlay mode. | Yes | No |
| `showPopover()` | Shows the chat as a popover dialog. Only effective in overlay mode. | Yes | No |
| `hidePopover()` | Hides the popover dialog with a closing animation. Only effective in overlay mode. | Yes | No |
| `isPopoverShowing()` | Returns whether the popover is currently visible (including during close animation). Only effective in overlay mode. | Yes | No |
| `interact({ action })` | Sends a simulated user action. Can trigger specific intents or events. | Yes | Yes |
| `proactive.push(...messages)` | Pushes proactive messages (speech bubbles) that appear near the launcher button before the user opens chat. Only effective in overlay mode. | Yes | No |
| `proactive.clear()` | Clears all proactive messages. Only effective in overlay mode. | Yes | No-op |
### Examples
**Open the widget automatically after 3 seconds:**
```javascript theme={null}
setTimeout(() => {
window.voiceflow.chat.open();
}, 3000);
```
**Trigger an intent when a button is clicked:**
```javascript theme={null}
document.getElementById('support-btn').addEventListener('click', () => {
window.voiceflow.chat.open();
window.voiceflow.chat.interact({
type: 'intent',
payload: { intent: { name: 'support_request' } }
});
});
```
## Sending proactive messages
Proactive messages appear outside the chat window before users open it. They're useful for prompting engagement, such as offering help or announcing promotions. These messages don't appear in transcripts and don't consume credits.
### Pushing messages
Use `window.voiceflow.chat.proactive.push()` to send one or more messages:
```javascript theme={null}
// Single message
window.voiceflow.chat.proactive.push({
type: 'text',
payload: { message: 'Need help? Ask me anything!' }
});
// Multiple messages
window.voiceflow.chat.proactive.push(
{ type: 'text', payload: { message: 'Welcome back!' } },
{ type: 'text', payload: { message: 'Check out our new features.' } }
);
```
### Clearing messages
Use `window.voiceflow.chat.proactive.clear()` to hide all proactive messages:
```javascript theme={null}
window.voiceflow.chat.proactive.clear();
```
### Triggering messages based on user behavior
You can trigger proactive messages when users perform specific actions. For example, show a message when someone visits a certain page:
```javascript theme={null}
if (window.location.pathname === '/pricing') {
window.voiceflow.chat.proactive.clear();
window.voiceflow.chat.proactive.push({
type: 'text',
payload: { message: 'Have questions about our plans? I can help!' }
});
}
```
## Listening for events
The widget emits events you can listen for using the `message` event listener. Voiceflow events are stringified JSON objects with a `type` beginning with `voiceflow:`.
```javascript theme={null}
window.addEventListener('message', (event) => {
if (typeof event.data === 'string' && event.data.startsWith('{"type":"voiceflow:')) {
const data = JSON.parse(event.data);
console.log(data.type);
}
});
```
| Event type | Description |
| ------------------------ | ------------------------------------------ |
| `voiceflow:open` | The widget was opened. |
| `voiceflow:close` | The widget was closed. |
| `voiceflow:interact` | The assistant responded to an interaction. |
| `voiceflow:save_session` | The conversation state was cached. |
## Allowing dangerous HTML elements
Only enable dangerous HTML if you understand XSS risks and are using your own trusted code. [Learn more about XSS vulnerabilities](https://owasp.org/www-community/attacks/xss/).
By default, certain HTML elements like `