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

`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

Messages & UI