---
title: "Interact (non-stream)"
method: POST
path: "/v4/interact"
tags: ["Conversation", "Public-Docs"]
---

# Interact (non-stream)

`POST /v4/interact`

Send an action and receive an array of traces in response.

## Request body

- object
  - `action` union, required
    - LaunchRequest — Send a launch request to start a new conversation.
      - `type` 'launch', required
      - `payload` object
        - `persona` string
      - `diagramID` string
      - `time` number
      - `metadata` object
    - TextRequest — Send the user response as a raw text payload.
      - `type` 'text', required
      - `payload` string, required
      - `diagramID` string
      - `time` number
      - `metadata` object
        - `source` string
    - object — Send one or more file attachments, with an optional text message.
      - `type` 'file', required
      - `payload` object, required
        - `text` string
        - `files` object[], required
          - `url` string, uri
          - `mimeType` string, required
          - `filename` string
          - `size` number
          - `s3Key` string
      - `diagramID` string
      - `time` number
      - `metadata` object
    - ActionRequest — Actions are self-describing operations with an associated payload.
      - `type` 'action', required
      - `payload` object
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string
      - `diagramID` string
      - `time` number
      - `metadata` object
    - IntentRequest — Trigger a specific intent from your conversation model.
      - `type` 'intent', required
      - `payload` IntentRequestPayload, required
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string
        - `data` object
        - `query` string
        - `intent` object, required
          - `name` string, required
        - `entities` IntentRequestEntity[]
          - `name` string, required
          - `value` string, required
          - `query` string
          - `verboseValue` VerboseValue[]
            - `rawText` string, required
            - `canonicalText` string, required
            - `startIndex` number, required
        - `confidence` number
      - `diagramID` string
      - `time` number
      - `metadata` object
    - EventRequest — Events are triggers with an associated payload.
      - `type` 'event', required
      - `payload` EventRequestPayload, required
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string
        - `event` object, required
          - `name` string, required
      - `diagramID` string
      - `time` number
      - `metadata` object
    - PathRequest — Continue the conversation by traveling down the specified path.
      - `type` string, required
      - `payload` object, required
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string, required
      - `diagramID` string
      - `time` number
      - `metadata` object
    - NoReplyRequest — Represents the user failing to reply, typically sent after a reasonable timeout.
      - `type` 'no-reply', required
      - `diagramID` string
      - `time` number
      - `metadata` object
    - MessageRequest — Similar to the `text` action.
      - `type` 'message', required
      - `payload` object, required
        - `message` string, required
      - `diagramID` string
      - `time` number
      - `metadata` object
    - EndRequest — Sent to indicate the conversation has been ended.
      - `type` 'end', required
      - `payload` object
        - `reason` string, required
        - `message` string
      - `diagramID` string
      - `time` number
      - `metadata` object
    - DTMFRequest — Represents the result of a dial-tone input, used for phone calls.
      - `type` 'dtmf', required
      - `payload` string, required
      - `diagramID` string
      - `time` number
      - `metadata` object
    - LiveAgentHandoffRequest — Sent to interact with a connected live agent.
      - `type` 'live-agent-handoff', required
      - `payload` union, required
        - LiveAgentHandoffMessagePayload
          - `type` 'message', required
          - `message` string, required
        - LiveAgentHandoffFileUploadPayload
          - `type` 'file_upload', required
          - `files` object[], required
            - `id` string, required
            - `name` string, required
            - `size` number, required
            - `type` string, required
            - `status` 'uploaded' | 'failed'
            - `metadata` object
        - LiveAgentHandoffContinueConversationPayload
          - `type` 'continue_conversation', required
        - LiveAgentHandoffReturnToVoiceflowPayload
          - `type` 'return_to_voiceflow', required
      - `diagramID` string
      - `time` number
      - `metadata` object
    - GeneralRequest — Represents an non-system-defined action.
      - `type` string, required
      - `payload` object
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string
      - `diagramID` string
      - `time` number
      - `metadata` object
    - AlexaIntentRequest — Legacy intent request type that `general-runtime` expects Alexa to send
      - `type` 'intent', required
      - `payload` object, required
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string
        - `data` object, required
        - `query` string
        - `intent` object, required
          - `name` string, required
        - `entities` IntentRequestEntity[], required
          - `name` string, required
          - `value` string, required
          - `query` string
          - `verboseValue` VerboseValue[]
            - `rawText` string, required
            - `canonicalText` string, required
            - `startIndex` number, required
        - `confidence` number
      - `diagramID` string
      - `time` number
      - `metadata` object
    - LegacyIntentRequest — The legacy intent request type that `general-runtime` expects from its clients.
      - `type` 'intent', required
      - `payload` object, required
        - `actions` BaseAction[]
          - `type` string, required
          - `payload` unknown, required
        - `label` string
        - `query` string
        - `intent` object, required
          - `name` string, required
        - `entities` IntentRequestEntity[], required
          - `name` string, required
          - `value` string, required
          - `query` string
          - `verboseValue` VerboseValue[]
            - `rawText` string, required
            - `canonicalText` string, required
            - `startIndex` number, required
        - `confidence` number
      - `diagramID` string
      - `time` number
      - `metadata` object
  - `variables` object — Key-value pairs to set or update on the session before this turn is processed. Useful for injecting context like a user's name, account tier, or current page. [Learn more](/documentation/build/data/variables).
  - `state` unknown
  - `config` object — Optional settings for this turn.
    - `userTimezone` string — The user's IANA timezone string (eg: `America/New_York`). Sets `{vf_user_timezone}` variable. Used to localize time-dependent agent behavior.

## Response `200`

- object
  - `traces` AnyTrace[], required — An array of [traces](/trace-types) that occurred during this turn.
    - union
      - AudioTrace
        - `type` 'audio', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - object
            - `state` 'start', required
            - `messageID` string, required
            - `delay` number
          - object
            - `state` 'content', required
            - `content` string, required
            - `encoding` 'audio/mp3' | 'audio/x-mulaw' | 'audio/pcm', required
            - `duration` number
          - object
            - `state` 'end', required
      - SpeakTrace
        - `type` 'speak', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `ai` boolean
          - `message` string, required
          - `type` 'audio' | 'message', required
          - `src` string, nullable
          - `voice` string
          - `isPrompt` boolean
      - StreamTrace
        - `type` 'stream', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `src` string, required
          - `token` string, required
          - `action` 'LOOP' | 'PLAY' | 'PAUSE' | 'END', required
          - `loop` boolean
          - `title` string
          - `iconImage` string
          - `description` string
          - `backgroundImage` string
      - BlockTrace
        - `type` 'block', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `blockID` string, required
      - CardTrace
        - `type` 'cardV2', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` CardTraceCard, required
          - `ref` union
            - DebugTraceNodeRef
              - …
            - DebugTraceAgentRef
              - …
            - DebugTracePromptRef
              - …
            - DebugTraceAPIToolRef
              - …
            - DebugTraceFunctionRef
              - …
            - DebugTraceIntegrationToolRef
              - …
            - DebugTraceMcpIntegrationToolRef
              - …
          - `title` string, required
          - `buttons` Button[], required
            - `name` string, required
            - `request` BaseRequest
              - …
          - `imageUrl` string, nullable, required
          - `messageID` string
          - `description` object, required
            - `text` string, required
            - `slate` unknown[]
              - …
      - CarouselTrace
        - `type` 'carousel', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `ref` union
            - DebugTraceNodeRef
              - …
            - DebugTraceAgentRef
              - …
            - DebugTracePromptRef
              - …
            - DebugTraceAPIToolRef
              - …
            - DebugTraceFunctionRef
              - …
            - DebugTraceIntegrationToolRef
              - …
            - DebugTraceMcpIntegrationToolRef
              - …
          - `cards` TraceCarouselCard[], required
            - `ref` union
              - …
            - `title` string, required
            - `buttons` Button[], required
              - …
            - `imageUrl` string, nullable, required
            - `messageID` string
            - `description` object, required
              - …
            - `id` string
          - `layout` 'List' | 'Carousel', required
          - `messageID` string
      - ChannelActionTrace
        - `type` 'channel-action', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `name` string, required
          - `payload` object, required
      - ChoiceTrace
        - `type` 'choice', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `ref` union
            - DebugTraceNodeRef
              - …
            - DebugTraceAgentRef
              - …
            - DebugTracePromptRef
              - …
            - DebugTraceAPIToolRef
              - …
            - DebugTraceFunctionRef
              - …
            - DebugTraceIntegrationToolRef
              - …
            - DebugTraceMcpIntegrationToolRef
              - …
          - `buttons` Button[], required
            - `name` string, required
            - `request` BaseRequest
              - …
          - `messageID` string
      - CompletionTrace
        - `type` 'completion', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - object
            - `state` 'start', required
            - `ai` boolean
            - `sourceUrls` object[]
              - …
            - `delay` number
            - `messageID` string, required
            - `ref` union
              - …
          - object
            - `state` 'content', required
            - `content` string, required
          - object
            - `state` 'end', required
            - `ref` union
              - …
      - DebugTrace
        - `type` 'debug', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `ref` union
            - DebugTraceNodeRef
              - …
            - DebugTraceAgentRef
              - …
            - DebugTracePromptRef
              - …
            - DebugTraceAPIToolRef
              - …
            - DebugTraceFunctionRef
              - …
            - DebugTraceIntegrationToolRef
              - …
            - DebugTraceMcpIntegrationToolRef
              - …
          - `type` string
          - `level` 'fatal' | 'error' | 'warn' | 'info' | 'debug'
          - `message` string, required
          - `context` string
          - `metadata` object
      - DTMFTrace
        - `type` 'dtmf', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` DTMFTracePayload, required
          - `enabled` boolean, required — Enables the new DTMF collection and configuration
          - `timeoutInSeconds` number, required — How long to wait before processing the DTMF input. Set to 0 to process only after a delimiter is provided.
          - `delimiter` DTMFDelimiter[], required — Which key to use to end DTMF input. Defaults to '#'
          - `maxDigits` number, required — The maximum number of digits before we finish their input
      - EntityFillingTrace
        - `type` 'entity-filling', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `entityToFill` string, required
          - `intent` IntentRequest, required — Trigger a specific intent from your conversation model.
            - `type` 'intent', required
            - `payload` IntentRequestPayload, required
              - …
            - `diagramID` string
            - `time` number
            - `metadata` object
      - ExitTrace
        - `type` 'end', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` unknown
      - FlowTrace
        - `type` 'flow', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `name` string
          - `diagramID` string, required
      - GoToTrace
        - `type` 'goto', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `request` BaseRequest, required
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
      - LogTrace
        - `type` 'log', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
      - NoReplyTrace
        - `type` 'no-reply', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `timeout` number, required
      - PathTrace
        - `type` 'path', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `path` string, required
      - TextTrace
        - `type` 'text', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `ai` boolean
          - `message` string, required
          - `ref` union
            - DebugTraceNodeRef
              - …
            - DebugTraceAgentRef
              - …
            - DebugTracePromptRef
              - …
            - DebugTraceAPIToolRef
              - …
            - DebugTraceFunctionRef
              - …
            - DebugTraceIntegrationToolRef
              - …
            - DebugTraceMcpIntegrationToolRef
              - …
          - `slate` object, required
            - `id` string, required
            - `content` unknown[], required
              - …
          - `delay` number
          - `voice` string
          - `audio` object
            - `src` string, required
          - `messageID` string, required
          - `sourceUrls` object[]
            - `url` string, required
            - `name` string
      - ReasoningTrace
        - `type` 'reasoning', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - object
            - `state` 'start', required
          - object
            - `state` 'content', required
            - `content` string, required
          - object
            - `state` 'end', required
          - object
            - `state` 'final', required
            - `message` string, required
      - VisualTrace
        - `type` 'visual', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` VisualTraceImage, required
          - `visualType` 'image'
          - `image` string, nullable, required
          - `device` string, nullable
          - `options` object
            - `loop` boolean
          - `frameType` string
          - `dimensions` object, nullable
            - `width` number, required
            - `height` number, required
          - `canvasVisibility` 'full' | 'hidden' | 'cropped'
      - KnowledgeBaseTrace
        - `type` 'knowledgeBase', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` object, required
          - `chunks` object[], required
            - `score` number, required
            - `documentID` string, required
            - `documentData` unknown, required
          - `query` object
            - `messages` object[], required
              - …
            - `output` string, nullable, required
      - CallForwardTrace
        - `type` 'call-forward', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - CallForwardPhone
            - `addressType` 'phone', required
            - `address` string, required
            - `extension` string
            - `callerIDPassthrough` boolean
          - CallForwardSIP
            - `addressType` 'sip', required
            - `address` string, required
      - RealtimeAgentTrace
        - `type` 'realtime-agent', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - object
            - `action` 'START', required
            - `input` object, required
              - …
            - `output` object, required
              - …
          - object
            - `action` 'END', required
          - object
            - `action` 'INTERRUPTED', required
      - LiveAgentHandoffTrace
        - `type` 'live-agent-handoff', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - object
            - `conversationID` string, required
            - `message` string, required
            - `translationKey` string
            - `translationParams` object
            - `agent` object
              - …
            - `event` 'chat_started', required
            - `provider` 'ujet' | 'genesys' | 'kustomer'
            - `config` object
              - …
          - object
            - `conversationID` string, required
            - `message` string, required
            - `translationKey` string
            - `translationParams` object
            - `agent` object
              - …
            - `event` union, required
              - …
            - `downloadMessage` string
            - `continueMessage` string
            - `newConversationMessage` string
          - object
            - `conversationID` string, required
            - `message` string, required
            - `translationKey` string
            - `translationParams` object
            - `agent` object
              - …
            - `event` 'file_received', required
            - `file` object, required
              - …
          - object
            - `conversationID` string, required
            - `message` string, required
            - `translationKey` string
            - `translationParams` object
            - `agent` object
              - …
            - `event` union, required
              - …
      - ToolCallTrace
        - `type` 'tool-call', required
        - `paths` TracePath[]
          - `label` string
          - `event` BaseRequest
            - `type` string, required
            - `payload` unknown
            - `diagramID` string
            - `time` number
            - `metadata` object
        - `defaultPath` number
        - `time` number
        - `turnID` string
        - `handleID` string
        - `payload` union, required
          - object
            - `callID` string, required
            - `sound` object
              - …
            - `state` 'start', required
          - object
            - `state` 'end', required
            - `callID` string, required

---

[API](https://skmtc.net/voiceflow/apis/general-runtime.md) · [All operations](https://skmtc.net/voiceflow/apis/general-runtime/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voiceflow/general-runtime/versions/6b1c4f778c56/schema)