Skip to main content
Voiceflow’s Conversations API allows you to programatically 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, send events, read and modify session state, and inject variables - giving you full control over how your agent runs inside your own application.

​
Available endpoints

​
Actions and traces

When a user interacts 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:
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 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, update it, or delete it to reset the session — 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 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 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.