Skip to main content
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"
          }
        }
      }
    ]
  }
}
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"
  }
}

​
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.