Skip to main content
POST
/
create-conversation-flow
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const conversationFlowResponse = await client.conversationFlow.create({
  model_choice: { model: 'gpt-5', type: 'cascading' },
  nodes: [
    {
      id: 'start',
      instruction: { text: 'Greet the customer and ask how you can help them.', type: 'prompt' },
      type: 'conversation',
    },
  ],
  start_speaker: 'agent',
});

console.log(conversationFlowResponse.conversation_flow_id);
{
  "model_choice": {
    "type": "cascading",
    "model": "gpt-5",
    "high_priority": true
  },
  "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"
        }
      ],
      "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
      }
    }
  ],
  "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
  },
  "mcps": [
    {
      "name": "<string>",
      "url": "<string>",
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      },
      "timeout_ms": 123
    }
  ],
  "is_transfer_llm": false,
  "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"
        }
      ]
    }
  ],
  "conversation_flow_id": "<string>",
  "version": 123
}

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json

Override properties for conversation flow configuration in agent override requests.

​
model_choice
object
required

The model choice for the conversation flow.

​
start_speaker
enum<string>
required

Who starts the conversation - user or agent.

Available options:
user,
agent
Example:

"agent"

​
nodes
object[]
required

Array of nodes in the conversation flow.

  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
  • Option 6
  • Option 7
  • Option 8
  • Option 9
  • Option 10
  • Option 11
Example:
[
  {
    "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"
      }
    ]
  }
]
​
model_temperature
number | null

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

Required range: 0 <= x <= 1
Example:

0.7

​
tool_call_strict_mode
boolean | null

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

Example:

true

​
knowledge_base_ids
string[] | null

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

Example:
["kb_001", "kb_002"]
​
kb_config
object

Knowledge base configuration for RAG retrieval.

​
begin_after_user_silence_ms
integer | null

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.

Example:

2000

​
global_prompt
string | null

Global prompt used in every node of the conversation flow.

Example:

"You are a helpful customer service agent."

​
tools
object[] | null

Tools available in the conversation flow.

  • Option 1
  • Option 2
  • Option 3
Example:
[
  {
    "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
object[] | null

Local components embedded within the conversation flow.

​
start_node_id
string | null

ID of the start node in the conversation flow.

Example:

"start"

​
default_dynamic_variables
object | null

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

Example:
{
  "company_name": "Retell Inc",
  "support_hours": "9 AM - 5 PM"
}
​
begin_tag_display_position
object | null

Display position for the begin tag in the frontend.

​
mcps
object[] | null

A list of MCP server configurations to use for this conversation flow.

​
is_transfer_llm
boolean | null

Whether this conversation flow is used for transfer LLM.

Example:

false

Response

Successfully created a conversation flow

Override properties for conversation flow configuration in agent override requests.

​
conversation_flow_id
string
required

Unique identifier for the conversation flow

​
version
integer
required

Version number of the conversation flow

​
model_choice
object

The model choice for the conversation flow.

​
model_temperature
number | null

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

Required range: 0 <= x <= 1
Example:

0.7

​
tool_call_strict_mode
boolean | null

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

Example:

true

​
knowledge_base_ids
string[] | null

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

Example:
["kb_001", "kb_002"]
​
kb_config
object

Knowledge base configuration for RAG retrieval.

​
start_speaker
enum<string>

Who starts the conversation - user or agent.

Available options:
user,
agent
Example:

"agent"

​
begin_after_user_silence_ms
integer | null

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.

Example:

2000

​
global_prompt
string | null

Global prompt used in every node of the conversation flow.

Example:

"You are a helpful customer service agent."

​
tools
object[] | null

Tools available in the conversation flow.

  • Option 1
  • Option 2
  • Option 3
Example:
[
  {
    "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
object[] | null

Local components embedded within the conversation flow.

​
start_node_id
string | null

ID of the start node in the conversation flow.

Example:

"start"

​
default_dynamic_variables
object | null

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

Example:
{
  "company_name": "Retell Inc",
  "support_hours": "9 AM - 5 PM"
}
​
begin_tag_display_position
object | null

Display position for the begin tag in the frontend.

​
mcps
object[] | null

A list of MCP server configurations to use for this conversation flow.

​
is_transfer_llm
boolean | null

Whether this conversation flow is used for transfer LLM.

Example:

false

​
nodes
object[]

Array of nodes in the conversation flow.

  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
  • Option 6
  • Option 7
  • Option 8
  • Option 9
  • Option 10
  • Option 11
Example:
[
  {
    "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"
      }
    ]
  }
]