Trace Types

Overview

Flows in Voiceflow are a composed of a variety of elements such as steps and links. Voiceflow steps have corresponding JSON traces. Step traces are used by Web Chat — and can be used by custom integrations — to determine what should be presented to the user upon events such as conversation launch, utterance submission, and button selection.

Trace objects returned by the Dialog Manager API have a type attribute that identifies the type of element and a payload object with additional data such as a step’s response content or a button’s label. The Dialog Manager API interact endpoint returns an array of trace objects.

Below are key trace types that you will encounter.

type: text

This trace type is returned for the following Voiceflow elements:

Text Step
Response AI Step
No match re-prompt
No reply re-prompt
Global No Match
Global No Reply

Example payload:

{
  "type": "text",
  "payload": {
    "slate": {
      "id": "", // unique string generated by Voiceflow
      "content": [
        {
          "children": [
            {
              "text": "Hello there!"
            }
          ]
        },
        {
          "children": [
            {
              "text": ""
            }
          ]
        },
        {
          "children": [
            {
              "text": "Select an option or ask me a question"
            }
          ]
        }
      ],
      "messageDelayMilliseconds": 1000 // default is 1000ms between responses
    },
    "message": "Hello there!\n\nSelect an option or ask me a question",
    "delay": 1000 // default is 1000ms between responses
  }
}

type: speak

This trace type is returned for the following Voiceflow elements:

Speak Step
Audio Step
No match reprompt
No reply reprompt
Global No Match
Global No Reply

Speak Step example:

The src value for Speak steps is a data URI generated by Voiceflow.

{
  "type": "speak",
  "payload": {
    "message": "Hello there!",
    "type": "message",
    "src": "data:audio/mpeg;base64,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",
    "voice": "Ivy"
  }
}

Audio Step example:

The src value for Audio steps is a URL to the file and are generated by Voiceflow.

The message value will be an empty string for Audio steps.

{
  "type": "speak",
  "payload": {
    "message": "",
    "type": "audio",
    "src": "https://s3.amazonaws.com/com.example.audio.production/example-file.mp3"
  }
}

type: visual

This trace type is returned for the following Voiceflow elements: Image Step.

The dimentions attribute value can be null.

{
  "type": "visual",
  "payload": {
    "visualType": "image",
    "image": "https://assets-global.website-files.com/example-file.png",
    "dimensions": {
      "width": 800,
      "height": 800
    },
    "canvasVisibility": "full"
  }
}

type: cardV2

This trace type is returned for the following Voiceflow elements: Card Step.

When you encounter a trace with a button, take note of the button objects' request.type values. A request.type value is a Voiceflow-generated path ID for the next element, and will need to be included in the next request to the Dialog Manager API upon button click.

{
  "type": "cardV2",
  "payload": {
    "imageUrl": "https://assets-global.website-files.com/example-file.png",
    "description": {
      "slate": [
        {
          "children": [
            {
              "text": "This is a Card description"
            }
          ]
        }
      ],
      "text": "This is a Card description"
    },
    "buttons": [
      {
        "name": "Click for next step",
        "request": {
          "type": "", // path ID generated by Voiceflow
          "payload": {
            "actions": [],
            "label": "Click for next step"
          }
        }
      }
    ],
    "title": "This is a Card title"
  }
}

type: no-reply

This trace type is returned for the following Voiceflow elements: No Reply.

If you encounter this trace, a No Reply setting was enabled. If the user does not complete an event within the timeframe, send another request to the Dialog Manager API to fetch the corresponding step’s content.

Note: the timeout value in the trace is in seconds.

{
  "type": "no-reply",
  "payload": {
    "timeout": 10 // converted to seconds
  }
}

type: carousel

This trace type is returned for the following Voiceflow elements: Carousel Step.

This example trace is for a Carousel with two Cards:

{
  "type": "carousel",
  "payload": {
    "layout": "Carousel",
    "cards": [
      {
        "id": "", // unique string generated by Voiceflow
        "title": "This is a Carousel card title",
        "description": {
          "slate": [
            {
              "children": [
                {
                  "text": "This is a Carousel card description"
                }
              ]
            }
          ],
          "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 ID generated by Voiceflow
              "payload": {
                "label": "Click for next step",
                "actions": []
              }
            }
          }
        ]
      },
      {
        "id": "", // unique string generated by Voiceflow
        "title": "This is a second Carousel card title",
        "description": {
          "slate": [
            {
              "children": [
                {
                  "text": "This is a second Carousel card description. For this card, the image was uploaded as a png file."
                }
              ]
            }
          ],
          "text": "This is a second Carousel card description. For this card, the image was uploaded as a png file."
        },
        "imageUrl": "https://cm4-production-assets.s3.amazonaws.com/example-file.png",
        "buttons": [
          {
            "name": "Click for next step",
            "request": {
              "type": "", // path ID generated by Voiceflow
              "payload": {
                "label": "Click for next step",
                "actions": []
              }
            }
          }
        ]
      }
    ]
  }
}

type: choice

This trace type is returned for the following Voiceflow elements: Button Step.

This example trace is for a Button step with two buttons:

{
  "type": "choice",
  "payload": {
    "buttons": [
      {
        "name": "Click this button for the next step",
        "request": {
          "type": "", // path ID generated by Voiceflow
          "payload": {
            "label": "Click this button for the next step",
            "actions": []
          }
        }
      },
      {
        "name": "Go to test_intent",
        "request": {
          "type": "", // path ID generated by Voiceflow
          "payload": {
            "label": "Go to this intent",
            "actions": []
          }
        }
      }
    ]
  }
}

Custom Actions

A Custom Action trace type value will match the string entered for the corresponding Custom Action in the Creator App.

The defaultPath attribute is useful if you want to set a default path during prototyping or user testing. The value will be 0 if the Custom Action's first path is assigned as the default in the Creator App, 1 if the second path is assigned, 2 if the third path is assigned, and so on.

Example with the Action Body format set to “Text” in the Creator App:

{
  "type": "calendar",
  "payload": "{\n  \"today\": 1700096546693\n}",
  "defaultPath": 0,
  "paths": [
    {
      "event": {
        "type": "done"
      }
    },
    {
      "event": {
        "type": "cancel"
      }
    }
  ]
}

Example with the Action Body format set to “JSON” in the Creator App:

{
  "type": "calendar",
  "payload": {
    "today": 1700096585398
  },
  "defaultPath": 0,
  "paths": [
    {
      "event": {
        "type": "done"
      }
    },
    {
      "event": {
        "type": "cancel"
      }
    }
  ]
}

type: end

This trace will be returned when an End action is reached in the design.

Example for a Chat Agent:

{
    "type": "end",
    "payload": null
}

Example for a Voice Agent:

{
    "type": "end"
}