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

EndpointDescription
Conversation
POST 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)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 stateFetches the current state of a user’s conversation, including stack, variables, and storage.
PUT Update conversation stateReplaces the full state of a user’s conversation (stack, variables, storage).
DEL Delete conversation stateDeletes all state and session data for a user’s conversation.
PATCH Update conversation variablesMerges the provided variables into the user’s current conversation state.
Session
POST Emit session eventSends an event to an active session. Useful for injecting actions mid-conversation.

​
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: 
{
  "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 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

Requests run against the development version of your agent by default. Set the environment parameter to staging or production to target a specific published version.