Traces - Voiceflow Documentation

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. Some payloads have several shapes, distinguished by a field such as state; where they do, the table says under which condition each field appears, and marks a field required only when every shape requires it.

`audio`

An audio response event. The payload’s state field selects the shape: start announces a messageID, content carries the audio in content with its encoding, and end carries the state alone.

Field	Type	Required	Present when
`content`	string	no	`state` is `content`
`delay`	number	no	`state` is `start`
`duration`	number	no	`state` is `content`
`encoding`	`"audio/mp3"` or `"audio/x-mulaw"` or `"audio/pcm"`	no	`state` is `content`
`messageID`	string	no	`state` is `start`
`state`	`"start"` or `"content"` or `"end"`	yes	always

`block`

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

Field	Type	Required
`blockID`	string	yes

`call-forward`

Signals that the call is being forwarded. The payload always carries the destination in address and its kind in addressType; a phone forward may also carry an extension and a callerIDPassthrough flag. See the call forward step for configuration.

Field	Type	Required	Present when
`address`	string	yes	always
`addressType`	`"phone"` or `"sip"`	yes	always
`callerIDPassthrough`	boolean	no	`addressType` is `phone`
`extension`	string	no	`addressType` is `phone`

`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

`completion`

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

Field	Type	Required	Present when
`ai`	boolean	no	`state` is `start`
`content`	string	no	`state` is `content`
`delay`	number	no	`state` is `start`
`messageID`	string	no	`state` is `start`
`ref`	DebugTraceRef	no	`state` is `start` or `end`
`sourceUrls`	object[]	no	`state` is `start`
`state`	`"start"` or `"content"` or `"end"`	yes	always

`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`	`"fatal"` or `"error"` or `"warn"` or `"info"` or `"debug"`	no
`message`	string	yes
`metadata`	object	no
`ref`	DebugTraceRef	no
`type`	string	no

`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`	`"#"` or `"*"`[]	yes
`enabled`	boolean	yes
`maxDigits`	number	yes
`timeoutInSeconds`	number	yes

`entity-filling`

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

Field	Type	Required
`entityToFill`	string	yes
`intent`	IntentRequest	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

`knowledgeBase`

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

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

`live-agent-handoff`

Signals a handoff of the conversation to a live agent platform. Every shape of the payload carries conversationID, message, and event; the remaining fields vary by shape, and some carry a provider naming the platform. This payload has 4 shapes; a field is listed once, and marked required only when every shape both has and requires it.

Field	Type	Required	Present when
`agent`	object	no	always
`config`	LiveAgentHandoffWidgetConfig	no	some shapes (1 of 4)
`continueMessage`	string	no	some shapes (1 of 4)
`conversationID`	string	yes	always
`downloadMessage`	string	no	some shapes (1 of 4)
`event`	`"chat_started"`	yes	always
`file`	object	no	some shapes (1 of 4)
`message`	string	yes	always
`newConversationMessage`	string	no	some shapes (1 of 4)
`provider`	`"ujet"` or `"genesys"` or `"kustomer"` or `"dixa"`	no	some shapes (1 of 4)
`translationKey`	string	no	always
`translationParams`	object	no	always

`log`

Diagnostic log output attached to the turn. The payload is always present and is a free-form object: the spec declares no named fields on it and permits any.

`path`

Reports which path the conversation took out of a step.

Field	Type	Required
`path`	string	yes

`realtime-agent`

Marks realtime agent activity on the turn. The payload’s action field selects the shape: START carries input and output, while END and INTERRUPTED carry the action alone.

Field	Type	Required	Present when
`action`	`"START"` or `"END"` or `"INTERRUPTED"`	yes	always
`input`	object	no	`action` is `START`
`output`	object	no	`action` is `START`

`reasoning`

Marks model reasoning activity during the turn. The payload’s state field selects the shape: content carries a content string, final carries a message, and start and end carry the state alone.

Field	Type	Required	Present when
`content`	string	no	`state` is `content`
`message`	string	no	`state` is `final`
`state`	`"start"` or `"content"` or `"end"` or `"final"`	yes	always

`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`	`"audio"` or `"message"`	yes
`voice`	string	no

`stream`

An audio stream event. The payload carries the source in src, a token, and an action of LOOP, PLAY, PAUSE, or END; title, description, iconImage, backgroundImage, and loop are optional.

Field	Type	Required
`action`	`"LOOP"` or `"PLAY"` or `"PAUSE"` or `"END"`	yes
`backgroundImage`	string	no
`description`	string	no
`iconImage`	string	no
`loop`	boolean	no
`src`	string	yes
`title`	string	no
`token`	string	yes

`tool-call`

Marks a tool call made by the agent during the turn. The payload always carries the callID and a state of start or end; a start may also carry a sound.

Field	Type	Required	Present when
`callID`	string	yes	always
`sound`	object	no	`state` is `start`
`state`	`"start"` or `"end"`	yes	always

`visual`

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

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

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 traces. A single completion type marks the lifecycle of an AI generation event within a stream: the payload’s state field moves through start, content, and end. See Completion events for the full stream format.

​Trace types

​text

​cardV2

​carousel

​choice

​Path buttons

​Agent-generated buttons

​no-reply

​Additional trace types

​audio

​block

​call-forward

​channel-action

​completion

​debug

​dtmf

​entity-filling

​flow

​goto

​knowledgeBase

​live-agent-handoff

​log

​path

​realtime-agent

​reasoning

​speak

​stream

​tool-call

​visual

​Custom actions

​end

​Completion event traces