Traces

Traces are the output of a Voiceflow agent. Each time your application sends an action to the Conversations API, 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, Playbooks, and no-match and no-reply reprompts.

{
  "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. 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.

{
  "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. The same button handling applies as with cardV2 - pass the button’s request.type as the action.type in your next request.

{
  "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 and Playbooks or the Agent when the buttons system tool 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.

{
  "type": "choice",
  "time": 1753108390491,
  "payload": {
    "buttons": [
      {
        "name": "Order coffee",
        "request": {
          "type": "path-cmd906pp400433b7ujbsbiotm",
          "payload": {
            "label": "Order coffee"
          }
        }
      }
    ]
  }
}

To handle this button click, send:

{
  "action": {
    "type": "path-cmd906pp400433b7ujbsbiotm",
    "payload": {
      "label": "Order coffee"
    }
  }
}

Agent-generated buttons

When the buttons system tool 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:

{
  "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.

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

{
  "action": {
    "type": "no-reply"
  }
}

Additional trace types

Every remaining type value in the runtime schema. Field tables are projected from the spec; a field marked required is always present on the payload.

`log`

Diagnostic log output attached to the turn. Carries no payload properties; the envelope fields identify the event.

`path`

Reports which path the conversation took out of a step.

Field	Type	Required
`path`	string	yes

`flow`

Marks the conversation entering a flow, identified by its diagram ID.

Field	Type	Required
`diagramID`	string	yes
`name`	string	no

`goto`

Instructs the client to re-send the wrapped request on the next turn.

Field	Type	Required
`request`	BaseRequest	yes

`speak`

A spoken response for voice channels, carrying the message text and optionally a synthesized audio source and voice name.

Field	Type	Required
`ai`	boolean	no
`isPrompt`	boolean	no
`message`	string	yes
`src`	string	no
`type`	TraceSpeakType	yes
`voice`	string	no

`block`

Marks the conversation entering a block, identified by its block ID.

Field	Type	Required
`blockID`	string	yes

`debug`

Debug output for the turn, with a message and optional level, context, and metadata. Surfaced in agent logs rather than to end users.

Field	Type	Required
`context`	string	no
`level`	object	no
`message`	string	yes
`metadata`	object	no
`ref`	object	no
`type`	string	no

`stream`

A chunk of a streamed audio response: the audio source, a continuation token, and whether the stream starts, continues, or ends.

Field	Type	Required
`action`	TraceStreamAction	yes
`backgroundImage`	string	no
`description`	string	no
`iconImage`	string	no
`loop`	boolean	no
`src`	string	yes
`title`	string	no
`token`	string	yes

`visual`

Displays an image, with optional device sizing and layout options.

Field	Type	Required
`canvasVisibility`	object	no
`device`	string	no
`dimensions`	object	no
`frameType`	string	no
`image`	string	yes
`options`	object	no
`visualType`	`"image"`	no

`reasoning`

Marks model reasoning activity during the turn. Carries no payload properties.

`completion`

Marks a model completion event during the turn. Streaming clients receive the completion lifecycle described under completion event traces.

`audio`

An audio response event. Carries no payload properties.

`call-forward`

Signals that the call is being forwarded. Carries no payload properties; see the call forward step for configuration.

`live-agent-handoff`

Signals a handoff of the conversation to a live agent platform. Carries no payload properties.

`entity-filling`

Requests a value for a named entity, wrapping the intent request being filled.

Field	Type	Required
`entityToFill`	string	yes
`intent`	IntentRequest	yes

`channel-action`

A channel-specific action, named by the channel integration, with an action-defined payload.

Field	Type	Required
`name`	string	yes
`payload`	object	yes

`knowledgeBase`

Reports a knowledge base retrieval: the chunks returned and the query that produced them.

Field	Type	Required
`chunks`	object[]	yes
`query`	object	no

`realtime-agent`

Marks realtime agent activity on the turn. Carries no payload properties.

`dtmf`

Configures keypad (DTMF) input collection on a call: whether it is enabled, the timeout, the ending delimiter, and the digit cap.

Field	Type	Required
`delimiter`	DTMFDelimiter[]	yes
`enabled`	boolean	yes
`maxDigits`	number	yes
`timeoutInSeconds`	number	yes

`tool-call`

Marks a tool call made by the agent during the turn. Carries no payload properties.

`simulation-test-result`

simulation-test-result is declared in the runtime’s trace type enum with no published payload schema. Recorded as a spec defect; this entry updates automatically when upstream adds the schema.

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:

{
  "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.

{
  "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.

Conversations API

Analytics API

Knowledge base API

Project API

Webhooks

Trace types

text

cardV2

carousel

choice

Path buttons

Agent-generated buttons

no-reply

Additional trace types

`log`

`path`

`flow`

`goto`

`speak`

`block`

`debug`

`stream`

`visual`

`reasoning`

`completion`

`audio`

`call-forward`

`live-agent-handoff`

`entity-filling`

`channel-action`

`knowledgeBase`

`realtime-agent`

`dtmf`

`tool-call`

`simulation-test-result`

Custom actions

end

Completion event traces

​Trace types

​text

​cardV2

​carousel

​choice

​Path buttons

​Agent-generated buttons

​no-reply

​Additional trace types

​log

​path

​flow

​goto

​speak

​block

​debug

​stream

​visual

​reasoning

​completion

​audio

​call-forward

​live-agent-handoff

​entity-filling

​channel-action

​knowledgeBase

​realtime-agent

​dtmf

​tool-call

​simulation-test-result

​Custom actions

​end

​Completion event traces

Trace types

text

cardV2

carousel

choice

Path buttons

Agent-generated buttons

no-reply

Additional trace types

`log`

`path`

`flow`

`goto`

`speak`

`block`

`debug`

`stream`

`visual`

`reasoning`

`completion`

`audio`

`call-forward`

`live-agent-handoff`

`entity-filling`

`channel-action`

`knowledgeBase`

`realtime-agent`

`dtmf`

`tool-call`

`simulation-test-result`

Custom actions

end

Completion event traces