> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> Reference for every trace type returned by the Conversations API.

Traces are the output of a Voiceflow agent. Each time your application sends an action to the [Conversations API](/docs/api-reference/sections/running-agents), 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](/docs/documentation/build/steps/message), [Playbooks](/docs/documentation/build/steps/playbook), and no-match and no-reply reprompts.

```json
{
  "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](/docs/documentation/build/steps/card). 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.

```json
{
  "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](/docs/documentation/build/steps/card). The same button handling applies as with `cardV2` -  pass the button's `request.type` as the `action.type` in your next request.

```json
{
  "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](/docs/documentation/build/steps/condition) and [Playbooks](/docs/documentation/build/playbooks) or the Agent when the [buttons system tool](/docs/documentation/build/tools/system-tools) 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.

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

To handle this button click, send:

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

#### Agent-generated buttons

When the [buttons system tool](/docs/documentation/build/tools/system-tools) 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:

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

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

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

{/* gen:start id=traces/spec sha=54b7a274cbe7 */}

## 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 | always |
| `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"` or `"sunshine"` | 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 |
{/* gen:end id=traces/spec */}

### 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:

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

```json
{
  "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](/docs/api-reference/conversations-api/completion-events) for the full stream format.