Skip to main content
POST
/
v4
/
interact
Interact (non-stream)
curl --request POST \
  --url https://general-runtime.voiceflow.com/v4/interact \
  --header 'Content-Type: application/json' \
  --header 'authorization: <api-key>' \
  --data '
{
  "action": {
    "payload": {
      "persona": "<string>"
    },
    "diagramID": "<string>",
    "time": 123,
    "metadata": {}
  },
  "variables": {},
  "state": "<unknown>",
  "config": {}
}
'
{
  "traces": [
    {
      "payload": {
        "messageID": "<string>",
        "delay": 123
      },
      "paths": [
        {
          "label": "<string>",
          "event": {
            "type": "<string>",
            "payload": "<unknown>",
            "diagramID": "<string>",
            "time": 123,
            "metadata": {}
          }
        }
      ],
      "defaultPath": 123,
      "time": 123,
      "turnID": "<string>",
      "handleID": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.voiceflow.com/llms.txt

Use this file to discover all available pages before exploring further.

Call 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 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) instead.

Authorizations

​
authorization
string
header
required

Session key returned from the start session endpoint.

Body

application/json
​
action
object
required

The user's action for this conversation turn. Most commonly, the text action is used to send a message to the agent as a user.

​
variables
object

Key-value pairs to set or update on the session before this turn is processed. Useful for injecting context like a user's name, account tier, or current page. Learn more.

​
state
any
​
config
object

Optional settings for this turn.

Response

200 - application/json
​
traces
object[]
required

An array of traces that occurred during this turn.