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

# Handling responses

> Read Chat trace events and distinguish turn completion from conversation end.

## Event stream

[`POST /v4/interact/stream`](/docs/api-reference/v4interact/interact-non-stream) returns `text/event-stream`. Each SSE event named `trace` carries a trace object in its JSON `data`. The event named `end` carries an empty object and finishes the turn’s delivery.

<a id="trace" />

### `trace` event

A JSON trace object carried in the event’s `data` field.

```text title="SSE response example"
event: trace
data: {"type":"text","payload":{"message":"How can I help with your order?","messageID":"message-1042","slate":{"id":"text-1042","content":[{"children":[{"text":"How can I help with your order?"}]}]}}}

event: end
data: {}

```

- **Parse complete events:** preserve partial text across network reads. A network chunk can split an event or contain multiple events; dispatch after the event’s blank-line terminator.
- **Decode the payload:** parse a `trace` event’s `data` as JSON, then dispatch on the trace’s `type`.
- **Finish the turn:** wait for the SSE `end` event. If the stream closes first, follow [interrupted-stream recovery](/docs/api-reference/agent-runtime/chat/recovery#interrupted-streams).

Use an SSE-capable client that supports POST bodies and the `Authorization` header. Native browser `EventSource` does not support that request shape. The [SSE parsing standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream) defines event framing; [Sending actions](/docs/api-reference/v4interact/interact-non-stream) owns the HTTP contract.

<a id="end" />

### `end` event

The event’s JSON `data` is `{}`. It finishes delivery of one turn. It does not end the conversation; a trace whose `type` is `end` does that.

### `error` event

A runtime failure during streaming produces an SSE event named `error`, then closes the response. Its `data` contains serialized error text; it is not a trace payload. Handle it as a failed turn, rather than waiting for a successful `end` event or replaying the action automatically.

Errors raised before streaming starts return an HTTP error response instead. Check the HTTP status before parsing events; a successful HTTP status alone does not prove the streamed turn completed. See [Errors and recovery](/docs/api-reference/agent-runtime/chat/recovery#request-errors).

## Trace payloads

Dispatch on `trace.type`. The definitions below cover chat messages and conversation controls. For escalation, use [Human agent hand-off](/docs/api-reference/agent-runtime/chat/handoff).

<a id="messages-ui" />

## Messages and UI

### `text` trace

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",
    "messageID": "unique-id",
    "delay": 1000
  }
}
```

The `message` field contains the plain text content. The `slate` field contains the same content in a structured rich-text format. When present, `delay` gives the pause in milliseconds. Use the supplied value rather than assuming a fixed delay; Voice output does not inherit the project’s chat message delay.

#### text payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "ai": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "ref": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DebugTraceRef"
        }
      ]
    },
    "slate": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "content": {
          "type": "array",
          "items": {}
        }
      },
      "required": [
        "id",
        "content"
      ]
    },
    "delay": {
      "type": "number"
    },
    "voice": {
      "type": "string"
    },
    "audio": {
      "type": "object",
      "properties": {
        "src": {
          "type": "string"
        }
      },
      "required": [
        "src"
      ]
    },
    "messageID": {
      "type": "string"
    },
    "sourceUrls": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ]
      }
    }
  },
  "required": [
    "message",
    "slate",
    "messageID"
  ],
  "components": {
    "schemas": {
      "DebugTraceRef": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DebugTraceNodeRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAgentRef"
          },
          {
            "$ref": "#/components/schemas/DebugTracePromptRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAPIToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceFunctionRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceIntegrationToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceMcpIntegrationToolRef"
          }
        ]
      },
      "DebugTraceNodeRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "node"
            ],
            "x-enumNames": [
              "NODE"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "nodeType": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "nodeType",
          "diagramID"
        ]
      },
      "DebugTraceAgentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent"
            ],
            "x-enumNames": [
              "AGENT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "agentID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "agentName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "agentID",
          "diagramID"
        ]
      },
      "DebugTracePromptRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "prompt"
            ],
            "x-enumNames": [
              "PROMPT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "promptID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "promptID",
          "diagramID"
        ]
      },
      "DebugTraceAPIToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "api-tool"
            ],
            "x-enumNames": [
              "API_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "apiToolID": {
            "type": "string"
          },
          "apiToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "apiToolID"
        ]
      },
      "DebugTraceFunctionRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "x-enumNames": [
              "FUNCTION"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "functionID": {
            "type": "string"
          },
          "functionName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "functionID"
        ]
      },
      "DebugTraceIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "integration-tool"
            ],
            "x-enumNames": [
              "INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          },
          "integrationToolName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "integrationToolName"
        ]
      },
      "DebugTraceMcpIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp-integration-tool"
            ],
            "x-enumNames": [
              "MCP_INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "mcpToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "mcpToolName"
        ]
      }
    }
  }
}
```

### `cardV2` trace

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"
          }
        }
      }
    ]
  }
}
```

#### cardV2 payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "$ref": "#/components/schemas/CardTraceCard",
  "components": {
    "schemas": {
      "CardTraceCard": {
        "type": "object",
        "properties": {
          "ref": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DebugTraceRef"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Button"
            }
          },
          "imageUrl": {
            "nullable": true,
            "type": "string"
          },
          "messageID": {
            "type": "string"
          },
          "description": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              },
              "slate": {
                "type": "array",
                "items": {}
              }
            },
            "required": [
              "text"
            ]
          }
        },
        "required": [
          "title",
          "buttons",
          "imageUrl",
          "description"
        ]
      },
      "DebugTraceRef": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DebugTraceNodeRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAgentRef"
          },
          {
            "$ref": "#/components/schemas/DebugTracePromptRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAPIToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceFunctionRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceIntegrationToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceMcpIntegrationToolRef"
          }
        ]
      },
      "DebugTraceNodeRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "node"
            ],
            "x-enumNames": [
              "NODE"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "nodeType": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "nodeType",
          "diagramID"
        ]
      },
      "DebugTraceAgentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent"
            ],
            "x-enumNames": [
              "AGENT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "agentID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "agentName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "agentID",
          "diagramID"
        ]
      },
      "DebugTracePromptRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "prompt"
            ],
            "x-enumNames": [
              "PROMPT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "promptID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "promptID",
          "diagramID"
        ]
      },
      "DebugTraceAPIToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "api-tool"
            ],
            "x-enumNames": [
              "API_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "apiToolID": {
            "type": "string"
          },
          "apiToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "apiToolID"
        ]
      },
      "DebugTraceFunctionRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "x-enumNames": [
              "FUNCTION"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "functionID": {
            "type": "string"
          },
          "functionName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "functionID"
        ]
      },
      "DebugTraceIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "integration-tool"
            ],
            "x-enumNames": [
              "INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          },
          "integrationToolName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "integrationToolName"
        ]
      },
      "DebugTraceMcpIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp-integration-tool"
            ],
            "x-enumNames": [
              "MCP_INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "mcpToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "mcpToolName"
        ]
      },
      "Button": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "request": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BaseRequest"
              }
            ]
          }
        },
        "required": [
          "name"
        ]
      },
      "BaseRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "payload": {},
          "diagramID": {
            "type": "string"
          },
          "time": {
            "type": "number"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "type"
        ]
      }
    }
  }
}
```

### `carousel` trace

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": []
              }
            }
          }
        ]
      }
    ]
  }
}
```

#### carousel payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "ref": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DebugTraceRef"
        }
      ]
    },
    "cards": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TraceCarouselCard"
      }
    },
    "layout": {
      "$ref": "#/components/schemas/CarouselLayout"
    },
    "messageID": {
      "type": "string"
    }
  },
  "required": [
    "cards",
    "layout"
  ],
  "components": {
    "schemas": {
      "DebugTraceRef": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DebugTraceNodeRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAgentRef"
          },
          {
            "$ref": "#/components/schemas/DebugTracePromptRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAPIToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceFunctionRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceIntegrationToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceMcpIntegrationToolRef"
          }
        ]
      },
      "DebugTraceNodeRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "node"
            ],
            "x-enumNames": [
              "NODE"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "nodeType": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "nodeType",
          "diagramID"
        ]
      },
      "DebugTraceAgentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent"
            ],
            "x-enumNames": [
              "AGENT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "agentID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "agentName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "agentID",
          "diagramID"
        ]
      },
      "DebugTracePromptRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "prompt"
            ],
            "x-enumNames": [
              "PROMPT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "promptID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "promptID",
          "diagramID"
        ]
      },
      "DebugTraceAPIToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "api-tool"
            ],
            "x-enumNames": [
              "API_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "apiToolID": {
            "type": "string"
          },
          "apiToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "apiToolID"
        ]
      },
      "DebugTraceFunctionRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "x-enumNames": [
              "FUNCTION"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "functionID": {
            "type": "string"
          },
          "functionName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "functionID"
        ]
      },
      "DebugTraceIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "integration-tool"
            ],
            "x-enumNames": [
              "INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          },
          "integrationToolName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "integrationToolName"
        ]
      },
      "DebugTraceMcpIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp-integration-tool"
            ],
            "x-enumNames": [
              "MCP_INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "mcpToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "mcpToolName"
        ]
      },
      "TraceCarouselCard": {
        "type": "object",
        "properties": {
          "ref": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DebugTraceRef"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Button"
            }
          },
          "imageUrl": {
            "nullable": true,
            "type": "string"
          },
          "messageID": {
            "type": "string"
          },
          "description": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              },
              "slate": {
                "type": "array",
                "items": {}
              }
            },
            "required": [
              "text"
            ]
          },
          "id": {
            "type": "string"
          }
        },
        "required": [
          "title",
          "buttons",
          "imageUrl",
          "description"
        ]
      },
      "Button": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "request": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BaseRequest"
              }
            ]
          }
        },
        "required": [
          "name"
        ]
      },
      "BaseRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "payload": {},
          "diagramID": {
            "type": "string"
          },
          "time": {
            "type": "number"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "type"
        ]
      },
      "CarouselLayout": {
        "type": "string",
        "enum": [
          "List",
          "Carousel"
        ],
        "x-enumNames": [
          "LIST",
          "CAROUSEL"
        ]
      }
    }
  }
}
```

### `choice` trace

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"
        }
      }
    ]
  }
}
```

#### choice payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "ref": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DebugTraceRef"
        }
      ]
    },
    "buttons": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Button"
      }
    },
    "messageID": {
      "type": "string"
    }
  },
  "required": [
    "buttons"
  ],
  "components": {
    "schemas": {
      "DebugTraceRef": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DebugTraceNodeRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAgentRef"
          },
          {
            "$ref": "#/components/schemas/DebugTracePromptRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAPIToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceFunctionRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceIntegrationToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceMcpIntegrationToolRef"
          }
        ]
      },
      "DebugTraceNodeRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "node"
            ],
            "x-enumNames": [
              "NODE"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "nodeType": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "nodeType",
          "diagramID"
        ]
      },
      "DebugTraceAgentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent"
            ],
            "x-enumNames": [
              "AGENT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "agentID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "agentName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "agentID",
          "diagramID"
        ]
      },
      "DebugTracePromptRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "prompt"
            ],
            "x-enumNames": [
              "PROMPT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "promptID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "promptID",
          "diagramID"
        ]
      },
      "DebugTraceAPIToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "api-tool"
            ],
            "x-enumNames": [
              "API_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "apiToolID": {
            "type": "string"
          },
          "apiToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "apiToolID"
        ]
      },
      "DebugTraceFunctionRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "x-enumNames": [
              "FUNCTION"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "functionID": {
            "type": "string"
          },
          "functionName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "functionID"
        ]
      },
      "DebugTraceIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "integration-tool"
            ],
            "x-enumNames": [
              "INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          },
          "integrationToolName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "integrationToolName"
        ]
      },
      "DebugTraceMcpIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp-integration-tool"
            ],
            "x-enumNames": [
              "MCP_INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "mcpToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "mcpToolName"
        ]
      },
      "Button": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "request": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BaseRequest"
              }
            ]
          }
        },
        "required": [
          "name"
        ]
      },
      "BaseRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "payload": {},
          "diagramID": {
            "type": "string"
          },
          "time": {
            "type": "number"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "type"
        ]
      }
    }
  }
}
```

### `visual` trace

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 |

#### visual payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "$ref": "#/components/schemas/VisualTraceImage",
  "components": {
    "schemas": {
      "VisualTraceImage": {
        "type": "object",
        "properties": {
          "visualType": {
            "type": "string",
            "enum": [
              "image"
            ],
            "x-enumNames": [
              "IMAGE"
            ]
          },
          "image": {
            "nullable": true,
            "type": "string"
          },
          "device": {
            "nullable": true,
            "type": "string"
          },
          "options": {
            "type": "object",
            "properties": {
              "loop": {
                "type": "boolean"
              }
            }
          },
          "frameType": {
            "type": "string"
          },
          "dimensions": {
            "nullable": true,
            "type": "object",
            "properties": {
              "width": {
                "type": "number"
              },
              "height": {
                "type": "number"
              }
            },
            "required": [
              "width",
              "height"
            ]
          },
          "canvasVisibility": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CanvasVisibility"
              }
            ]
          }
        },
        "required": [
          "image"
        ]
      },
      "CanvasVisibility": {
        "type": "string",
        "enum": [
          "full",
          "hidden",
          "cropped"
        ],
        "x-enumNames": [
          "FULL",
          "HIDDEN",
          "CROPPED"
        ]
      }
    }
  }
}
```

<a id="conversation-control" />

## Conversation control

### `no-reply` trace

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"
  }
}
```

#### no-reply payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "timeout": {
      "type": "number"
    }
  },
  "required": [
    "timeout"
  ]
}
```

### `end` trace

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
}
```

#### end payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{}
```

### `goto` trace

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

| Field | Type | Required |
| --- | --- | --- |
| `request` | BaseRequest | yes |

#### goto payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "request": {
      "$ref": "#/components/schemas/BaseRequest"
    }
  },
  "required": [
    "request"
  ],
  "components": {
    "schemas": {
      "BaseRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "payload": {},
          "diagramID": {
            "type": "string"
          },
          "time": {
            "type": "number"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "type"
        ]
      }
    }
  }
}
```

### `entity-filling` trace

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

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

#### entity-filling payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "entityToFill": {
      "type": "string"
    },
    "intent": {
      "$ref": "#/components/schemas/IntentRequest"
    }
  },
  "required": [
    "entityToFill",
    "intent"
  ],
  "components": {
    "schemas": {
      "IntentRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "intent"
            ],
            "x-enumNames": [
              "INTENT"
            ]
          },
          "payload": {
            "$ref": "#/components/schemas/IntentRequestPayload"
          },
          "diagramID": {
            "type": "string"
          },
          "time": {
            "type": "number"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "type",
          "payload"
        ],
        "description": "Trigger a specific intent from your conversation model."
      },
      "IntentRequestPayload": {
        "type": "object",
        "properties": {
          "actions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BaseAction"
            }
          },
          "label": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": {}
          },
          "query": {
            "default": "",
            "type": "string"
          },
          "intent": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "additionalProperties": {}
          },
          "entities": {
            "default": [],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IntentRequestEntity"
            }
          },
          "confidence": {
            "type": "number"
          }
        },
        "required": [
          "intent"
        ]
      },
      "BaseAction": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "payload": {}
        },
        "required": [
          "type",
          "payload"
        ]
      },
      "IntentRequestEntity": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "verboseValue": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerboseValue"
            }
          }
        },
        "required": [
          "name",
          "value"
        ]
      },
      "VerboseValue": {
        "type": "object",
        "properties": {
          "rawText": {
            "type": "string"
          },
          "canonicalText": {
            "type": "string"
          },
          "startIndex": {
            "type": "number"
          }
        },
        "required": [
          "rawText",
          "canonicalText",
          "startIndex"
        ]
      }
    }
  }
}
```

### `channel-action` trace

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

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

#### channel-action payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "name",
    "payload"
  ]
}
```

### Non-streaming HTTP alternative

Receive the completed turn as JSON when incremental output is unnecessary.

### Read the completed turn

[`POST /v4/interact`](/docs/api-reference/v4interact/interact-non-stream) returns `application/json` with a `traces` array. Each element is a trace, not a separate HTTP response. Process the array in order once the request completes.

```json title="JSON response example"
{
  "traces": [
    {
      "type": "text",
      "payload": {
        "message": "How can I help with your order?",
        "messageID": "message-1042",
        "slate": {
          "id": "text-1042",
          "content": [{ "children": [{ "text": "How can I help with your order?" }] }]
        }
      }
    }
  ]
}
```

- **Display text:** read `payload.message`; use `payload.slate` for the structured rich-text version. See [text traces](/docs/api-reference/agent-runtime/chat/responses#text-trace).
- **Display other output:** dispatch on `type` using the [trace index](/docs/api-reference/agent-runtime/chat/responses#trace-payloads).
- **Check the HTTP status:** `402` uses the same envelope for a credit-limit debug trace. See [request lifecycle](/docs/api-reference/agent-runtime/chat/recovery#request-lifecycle).
