Post create conversation flow — retell-sdk

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

Create a new Conversation Flow that can be attached to an agent. This is used to generate response output for the agent.

post/create-conversation-flow

Request body

model_temperaturenumber nullable

Controls the randomness of the model's responses. Lower values make responses more deterministic.

tool_call_strict_modeboolean nullable

Whether to use strict mode for tool calls. Only applicable when using certain supported models.

knowledge_base_idsstring[] nullable

Knowledge base IDs for RAG (Retrieval-Augmented Generation).

start_speaker'user' | 'agent' required

Who starts the conversation - user or agent.

begin_after_user_silence_msinteger nullable

If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.

global_promptstring nullable

Global prompt used in every node of the conversation flow.

flex_modeboolean nullable

If enabled, the whole conversation flow will be converted as a Single Prompt agent.

start_node_idstring nullable

ID of the start node in the conversation flow.

default_dynamic_variablesobject nullable

Default dynamic variables that can be referenced throughout the conversation flow.

is_transfer_llmboolean nullable

Whether this conversation flow is used for transfer LLM.

Example request

{
  "model_temperature": 0.7,
  "tool_call_strict_mode": true,
  "knowledge_base_ids": [
    "kb_001",
    "kb_002"
  ],
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "start_speaker": "agent",
  "begin_after_user_silence_ms": 2000,
  "global_prompt": "You are a helpful customer service agent.",
  "tools": [
    {
      "type": "custom",
      "name": "get_customer_info",
      "description": "Get customer information from database",
      "tool_id": "tool_001",
      "url": "https://api.example.com/customer",
      "method": "GET"
    }
  ],
  "components": [
    {
      "name": "Customer Information Collector",
      "tools": [
        {
          "type": "custom",
          "name": "get_customer_info",
          "description": "Get customer information from database",
          "tool_id": "tool_001",
          "url": "https://api.example.com/customer",
          "method": "GET"
        }
      ],
      "mcps": [
        {
          "headers": {
            "Authorization": "Bearer 1234567890"
          },
          "query_params": {
            "index": "1",
            "key": "value"
          }
        }
      ],
      "nodes": [
        {
          "id": "collect_info",
          "type": "conversation",
          "instruction": {
            "type": "prompt",
            "text": "Ask the customer for their name and contact information."
          }
        }
      ],
      "start_node_id": "collect_info",
      "begin_tag_display_position": {
        "x": 100,
        "y": 200
      },
      "notes": [
        {
          "id": "note_abc123",
          "content": "Remember to handle edge cases here.",
          "display_position": {
            "x": 300,
            "y": 150
          },
          "size": {
            "width": 200,
            "height": 100
          }
        }
      ]
    }
  ],
  "start_node_id": "start",
  "default_dynamic_variables": {
    "company_name": "Retell Inc",
    "support_hours": "9 AM - 5 PM"
  },
  "begin_tag_display_position": {
    "x": 100,
    "y": 200
  },
  "notes": [
    {
      "id": "note_abc123",
      "content": "Remember to handle edge cases here.",
      "display_position": {
        "x": 300,
        "y": 150
      },
      "size": {
        "width": 200,
        "height": 100
      }
    }
  ],
  "mcps": [
    {
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      }
    }
  ],
  "nodes": [
    {
      "id": "start",
      "type": "conversation",
      "instruction": {
        "type": "prompt",
        "text": "Greet the customer and ask how you can help them."
      },
      "edges": [
        {
          "id": "edge_1",
          "transition_condition": {
            "type": "prompt",
            "prompt": "Customer wants to book appointment"
          },
          "destination_node_id": "book_appointment"
        }
      ]
    }
  ]
}

Response

Successfully created a conversation flow