Retell AI Get Conversation Flow Component API

openapi: 3.2.0
info:
  title: Retell SDK Add Community Voice Get Conversation Flow Component API
  version: 3.0.0
  contact:
    name: Retell Support
    url: https://www.retellai.com/
    email: support@retellai.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
  description: The production server.
security:
- api_key: []
tags:
- name: Get Conversation Flow Component
paths:
  /get-conversation-flow-component/{conversation_flow_component_id}:
    get:
      description: Get a shared conversation flow component
      operationId: getConversationFlowComponent
      parameters:
      - in: path
        name: conversation_flow_component_id
        schema:
          type: string
        required: true
        description: ID of the component to retrieve
      responses:
        '200':
          description: Successfully retrieved conversation flow component
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationFlowComponentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Get Conversation Flow Component
components:
  schemas:
    CodeTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - code
        name:
          type: string
          description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        description:
          type: string
          description: Describes what this tool does and when to call this tool.
        code:
          type: string
          maxLength: 20000
          description: JavaScript code to execute in the sandbox.
        timeout_ms:
          type: integer
          minimum: 5000
          maximum: 60000
          description: The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
        response_variables:
          type: object
          additionalProperties:
            type: string
          example:
            order_id: data.order.id
          description: A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
        speak_during_execution:
          type: boolean
          description: Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool.
        speak_after_execution:
          type: boolean
          default: true
          description: Determines whether the agent would call LLM another time and speak when the result of function is obtained.
        execution_message_description:
          type: string
          description: The description for the sentence agent say during execution. Only applicable when speak_during_execution is true.
        execution_message_type:
          type: string
          enum:
          - prompt
          - static_text
          description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        enable_typing_sound:
          type: boolean
          description: If true, play a typing sound on the agent audio track while this tool is executing.
      required:
      - type
      - name
      - code
    SubagentNode:
      allOf:
      - $ref: '#/components/schemas/NodeBase'
      - $ref: '#/components/schemas/AgentOverrideConfig'
      - type: object
        required:
        - type
        - instruction
        properties:
          type:
            type: string
            enum:
            - subagent
            description: Type of the node
          instruction:
            $ref: '#/components/schemas/NodeInstructionPrompt'
          skip_response_edge:
            $ref: '#/components/schemas/SkipResponseEdge'
          always_edge:
            $ref: '#/components/schemas/AlwaysEdge'
          edges:
            type: array
            items:
              $ref: '#/components/schemas/NodeEdge'
          finetune_conversation_examples:
            type: array
            items:
              $ref: '#/components/schemas/NodeFinetuneConversationExample'
          finetune_transition_examples:
            type: array
            items:
              $ref: '#/components/schemas/NodeFinetuneTransitionExample'
          knowledge_base_ids:
            type:
            - array
            - 'null'
            items:
              type: string
            description: Knowledge base IDs for RAG (Retrieval-Augmented Generation).
          kb_config:
            type: object
            $ref: '#/components/schemas/KBConfig'
            description: Knowledge base configuration for RAG retrieval at the node level. If kb_instruction is set here, it overrides the flow-level kb_instruction.
          tool_ids:
            type:
            - array
            - 'null'
            items:
              type: string
            description: The tool ids of the tools defined in main conversation flow or component that can be used in this subagent node.
          tools:
            type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/Tool'
            description: The tools owned by this subagent node. This includes other tool types like transfer_call, agent_swap, etc.
    NumberAnalysisData:
      type: object
      required:
      - type
      - name
      - description
      properties:
        type:
          type: string
          enum:
          - number
          description: Type of the variable to extract.
          example: number
        name:
          type: string
          description: Name of the variable.
          example: order_count
          minLength: 1
        description:
          type: string
          description: Description of the variable.
          example: How many the customer intend to order.
        required:
          type: boolean
          description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
        conditional_prompt:
          type: string
          description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
    NodeInstructionPrompt:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - prompt
          description: Type of instruction
        text:
          type: string
          description: The prompt text for the instruction
    CodeNode:
      allOf:
      - $ref: '#/components/schemas/NodeBase'
      - type: object
        required:
        - type
        - code
        - wait_for_result
        properties:
          type:
            type: string
            enum:
            - code
            description: Type of the node
          code:
            type: string
            maxLength: 20000
            description: JavaScript code to execute in the sandbox.
          timeout_ms:
            type: integer
            minimum: 5000
            maximum: 60000
            description: The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
          response_variables:
            type: object
            additionalProperties:
              type: string
            example:
              order_id: data.order.id
            description: A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
          speak_during_execution:
            type: boolean
            description: Whether to speak during code execution
          instruction:
            $ref: '#/components/schemas/NodeInstruction'
          wait_for_result:
            type: boolean
            description: Whether to wait for code execution result
          enable_typing_sound:
            type: boolean
            description: If true, play a typing sound while code executes.
          edges:
            type: array
            items:
              $ref: '#/components/schemas/NodeEdge'
          else_edge:
            $ref: '#/components/schemas/ElseEdge'
          finetune_transition_examples:
            type: array
            items:
              $ref: '#/components/schemas/NodeFinetuneTransitionExample'
    AgentSwapWebhookSetting:
      type: string
      enum:
      - both_agents
      - only_destination_agent
      - only_source_agent
    EndCallTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - end_call
        name:
          type: string
          description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        description:
          type: string
          description: Describes what the tool does, sometimes can also include information about when to call the tool.
        speak_during_execution:
          type: boolean
          description: If true, will speak during execution.
        execution_message_description:
          type: string
          description: Describes what to say to user when ending the call. Only applicable when speak_during_execution is true.
        execution_message_type:
          type: string
          enum:
          - prompt
          - static_text
          description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      required:
      - type
      - name
    ExtractDynamicVariableTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - extract_dynamic_variable
        name:
          type: string
          description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        description:
          type: string
          description: Describes what the tool does, sometimes can also include information about when to call the tool.
        variables:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisData'
          description: The variables to be extracted.
      required:
      - type
      - name
      - variables
      - description
    SmsContentTemplate:
      type: object
      required:
      - type
      - template
      properties:
        type:
          type: string
          enum:
          - template
        template:
          type: string
          enum:
          - info_collection
          description: The template to use for the SMS content. "info_collection" sends a predefined message requesting information from the user.
    PressDigitNode:
      allOf:
      - $ref: '#/components/schemas/NodeBase'
      - type: object
        required:
        - type
        - instruction
        properties:
          type:
            type: string
            enum:
            - press_digit
            description: Type of the node
          instruction:
            $ref: '#/components/schemas/NodeInstructionPrompt'
          delay_ms:
            type: integer
            description: Delay in milliseconds before pressing the digit
          edges:
            type: array
            items:
              $ref: '#/components/schemas/NodeEdge'
          finetune_transition_examples:
            type: array
            items:
              $ref: '#/components/schemas/NodeFinetuneTransitionExample'
    TransferOptionColdTransfer:
      type: object
      title: Cold Transfer
      properties:
        type:
          type: string
          enum:
          - cold_transfer
          description: The type of the transfer.
        show_transferee_as_caller:
          type: boolean
          description: If set to true, will show transferee (the user, not the AI agent) as caller when transferring. Requires the telephony side to support caller id override. Retell Twilio numbers support this option. This parameter takes effect only when `cold_transfer_mode` is set to `sip_invite`. When using `sip_refer`, this option is not available. Retell Twilio numbers always use user's number as the caller id when using `sip refer` cold transfer mode.
        cold_transfer_mode:
          type: string
          enum:
          - sip_refer
          - sip_invite
          description: The mode of the cold transfer. If set to `sip_refer`, will use SIP REFER to transfer the call. If set to `sip_invite`, will use SIP INVITE to transfer the call.
          default: sip_invite
        transfer_ring_duration_ms:
          type: integer
          minimum: 5000
          maximum: 90000
          description: Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
      required:
      - type
    ConversationFlowNode:
      oneOf:
      - $ref: '#/components/schemas/ConversationNode'
      - $ref: '#/components/schemas/SubagentNode'
      - $ref: '#/components/schemas/EndNode'
      - $ref: '#/components/schemas/FunctionNode'
      - $ref: '#/components/schemas/CodeNode'
      - $ref: '#/components/schemas/TransferCallNode'
      - $ref: '#/components/schemas/PressDigitNode'
      - $ref: '#/components/schemas/BranchNode'
      - $ref: '#/components/schemas/SmsNode'
      - $ref: '#/components/schemas/ExtractDynamicVariablesNode'
      - $ref: '#/components/schemas/AgentSwapNode'
      - $ref: '#/components/schemas/MCPNode'
      - $ref: '#/components/schemas/ComponentNode'
      - $ref: '#/components/schemas/BridgeTransferNode'
      - $ref: '#/components/schemas/CancelTransferNode'
    SmsInstructionTemplate:
      type: object
      required:
      - type
      - template
      properties:
        type:
          type: string
          enum:
          - template
          description: Type of instruction
        template:
          type: string
          enum:
          - info_collection
          description: The template to use for the instruction. "info_collection" sends a predefined message requesting information from the user.
    EquationCondition:
      type: object
      required:
      - type
      - equations
      - operator
      properties:
        type:
          type: string
          enum:
          - equation
        equations:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/Equation'
        operator:
          type: string
          enum:
          - '||'
          - '&&'
    TransferOptionWarmTransfer:
      type: object
      title: Warm Transfer
      properties:
        type:
          type: string
          enum:
          - warm_transfer
          description: The type of the transfer.
        show_transferee_as_caller:
          type: boolean
          description: If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
        agent_detection_timeout_ms:
          type: number
          description: The time to wait before considering transfer fails.
        transfer_ring_duration_ms:
          type: integer
          minimum: 5000
          maximum: 90000
          description: Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
        on_hold_music:
          type: string
          enum:
          - none
          - relaxing_sound
          - uplifting_beats
          - ringtone
          description: The music to play while the caller is being transferred.
        public_handoff_option:
          type: object
          oneOf:
          - $ref: '#/components/schemas/WarmTransferPrompt'
          - $ref: '#/components/schemas/WarmTransferStaticMessage'
          description: If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
        private_handoff_option:
          type: object
          oneOf:
          - $ref: '#/components/schemas/WarmTransferPrompt'
          - $ref: '#/components/schemas/WarmTransferStaticMessage'
          description: If set, when transfer is connected, will say the handoff message only to the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
        ivr_option:
          type: object
          $ref: '#/components/schemas/WarmTransferPrompt'
          description: IVR navigation option to run when doing human detection. This prompt will guide the AI on how to navigate the IVR system.
        opt_out_human_detection:
          type: boolean
          description: If set to true, will not perform human detection for the transfer. Default to false.
        enable_bridge_audio_cue:
          type: boolean
          description: Whether to play an audio cue when bridging the call. Defaults to true.
          default: true
      required:
      - type
    TransferFailedEdge:
      allOf:
      - $ref: '#/components/schemas/NodeEdge'
      - type: object
        required:
        - transition_condition
        properties:
          transition_condition:
            type: object
            required:
            - type
            - prompt
            properties:
              type:
                type: string
                enum:
                - prompt
              prompt:
                type: string
                enum:
                - Transfer failed
                description: Must be "Transfer failed" for transfer failed edge
    SkipResponseEdge:
      allOf:
      - $ref: '#/components/schemas/NodeEdge'
      - type: object
        required:
        - transition_condition
        properties:
          transition_condition:
            type: object
            required:
            - type
            - prompt
            properties:
              type:
                type: string
                enum:
                - prompt
              prompt:
                type: string
                enum:
                - Skip response
                description: Must be "Skip response" for skip response edge
    TransferOptionAgenticWarmTransfer:
      type: object
      title: Agentic Warm Transfer
      properties:
        type:
          type: string
          enum:
          - agentic_warm_transfer
          description: The type of the transfer.
        show_transferee_as_caller:
          type: boolean
          description: If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
        on_hold_music:
          type: string
          enum:
          - none
          - relaxing_sound
          - uplifting_beats
          - ringtone
          description: The music to play while the caller is being transferred.
        transfer_ring_duration_ms:
          type: integer
          minimum: 5000
          maximum: 90000
          description: Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
        public_handoff_option:
          type: object
          oneOf:
          - $ref: '#/components/schemas/WarmTransferPrompt'
          - $ref: '#/components/schemas/WarmTransferStaticMessage'
          description: If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
        agentic_transfer_config:
          type: object
          description: Configuration for agentic warm transfer. Required for agentic warm transfer.
          properties:
            transfer_agent:
              type: object
              description: The agent that will mediate the transfer decision.
              properties:
                agent_id:
                  type: string
                  minLength: 1
                  description: The agent ID of the transfer agent. This agent must have isTransferAgent set to true and should use bridge_transfer and cancel_transfer tools (for Retell LLM) or BridgeTransferNode and CancelTransferNode (for Conversation Flow).
                agent_version:
                  type: number
                  description: The version of the transfer agent to use.
              required:
              - agent_id
              - agent_version
            transfer_timeout_ms:
              type: number
              description: The maximum time to wait for the transfer agent to make a decision, in milliseconds. Defaults to 30000 (30 seconds).
              default: 30000
            action_on_timeout:
              type: string
              enum:
              - bridge_transfer
              - cancel_transfer
              description: The action to take when the transfer agent times out without making a decision. Defaults to cancel_transfer.
              default: cancel_transfer
        enable_bridge_audio_cue:
          type: boolean
          description: Whether to play an audio cue when bridging the call. Defaults to true.
          default: true
      required:
      - type
      - agentic_transfer_config
    TransferDestination:
      oneOf:
      - $ref: '#/components/schemas/TransferDestinationPredefined'
      - $ref: '#/components/schemas/TransferDestinationInferred'
    AgentOverrideConfig:
      type: object
      properties:
        interruption_sensitivity:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        responsiveness:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        voice_speed:
          type:
          - number
          - 'null'
          minimum: 0.5
          maximum: 2
        allow_dtmf_interruption:
          type:
          - boolean
          - 'null'
          description: If set, overrides the agent-level allow_dtmf_interruption for this node only.
    ToolParameter:
      type: object
      description: The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
      required:
      - type
      - properties
      properties:
        type:
          type: string
          enum:
          - object
          description: Type must be "object" for a JSON Schema object.
        properties:
          type: object
          additionalProperties: {}
          description: The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
        required:
          type: array
          items:
            type: string
          description: List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
    NodeTool:
      allOf:
      - oneOf:
        - $ref: '#/components/schemas/CustomTool'
        - $ref: '#/components/schemas/CheckAvailabilityCalTool'
        - $ref: '#/components/schemas/BookAppointmentCalTool'
      - type: object
        required:
        - tool_id
        properties:
          tool_id:
            type: string
            description: Unique identifier for the tool
    CheckAvailabilityCalTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - check_availability_cal
        name:
          type: string
          description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        description:
          type: string
          description: Describes what the tool does, sometimes can also include information about when to call the tool.
        cal_api_key:
          type: string
          description: Cal.com Api key that have access to the cal.com event you want to check availability for.
        event_type_id:
          oneOf:
          - type: number
          - type: string
          description: Cal.com event type id number for the cal.com event you want to check availability for. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
        timezone:
          type: string
          description: Timezone to be used when checking availability, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
      required:
      - type
      - name
      - cal_api_key
      - event_type_id
    CustomTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - custom
        name:
          type: string
          description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        url:
          type: string
          description: Describes what the tool does, sometimes can also include information about when to call the tool.
        description:
          type: string
          description: Describes what this tool does and when to call this tool.
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
          description: Method to use for the request, default to POST.
        headers:
          type: object
          additionalProperties:
            type: string
          example:
            Authorization: Bearer 1234567890
          description: Headers to add to the request.
        query_params:
          type: object
          additionalProperties:
            type: string
          example:
            page: '1'
            sort: asc
          description: Query parameters to append to the request URL.
        parameters:
          $ref: '#/components/schemas/ToolParameter'
        response_variables:
          type: object
          additionalProperties:
            type: string
          example:
            user_name: data.user.name
          description: A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
        speak_during_execution:
          type: boolean
          description: Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
        speak_after_execution:
          type: boolean
          description: Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
        execution_message_description:
          type: string
          description: The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
        execution_message_type:
          type: string
          enum:
          - prompt
          - static_text
          description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        timeout_ms:
          type: integer
          description: The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
        args_at_root:
          type: boolean
          description: If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
        enable_typing_sound:
          type: boolean
          description: If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
      required:
      - type
      - name
      - url
    WarmTransferStaticMessage:
      type: object
      properties:
        type:
          type: string
          enum:
          - static_message
        message:
          type: string
          example: You can take it from here.
          description: The static message to be used for warm handoff. Can contain dynamic variables.
    PromptCondition:
      type: object
      required:
      - type
      - prompt
      properties:
        type:
          type: string
          enum:
          - prompt
        prompt:
          type: string
          description: Prompt condition text
    CancelTransferTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - cancel_transfer
        name:
          type: string
          description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        description:
          type: string
          description: Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it cancels the transfer, returns the original caller to the main agent, and ends the transfer agent call.
        speak_during_execution:
          type: boolean
          description: If true, will speak during execution.
        execution_message_description:
          type: string
          description: Describes what to say to user when cancelling the transfer. Only applicable when speak_during_execution is true.
        execution_message_type:
          type: string
          enum:
          - prompt
          - static_text
          description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      required:
      - type
      - name
    BookAppointmentCalTool:
      type: object
      properties:
        type:
          type: string
          enum:
          - book_appointment_cal
        name:
          type: string
        

# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-get-conversation-flow-component-api-openapi.yml