REretellai

POST /create-conversation-flow

Changed on

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

Request

  • Base URL
    https://api.retellai.com
  • Auth
    HTTP bearer

Request body

model_temperaturenumber nullable

Deprecated, use model_config.temperature. Ignored when model_config is set.

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_cfboolean nullable

Whether this conversation flow is used for warm transfer. Can only be set at creation, and is ignored on update.

Example request

{
  "model_temperature": 0.7,
  "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

model_temperaturenumber nullable

Deprecated, use model_config.temperature. Ignored when model_config is set.

knowledge_base_idsstring[] nullable

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

start_speaker'user' | 'agent'

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_cfboolean nullable

Whether this conversation flow is used for warm transfer. Can only be set at creation, and is ignored on update.

conversation_flow_idstring required

Unique identifier for the conversation flow

versioninteger required

Version number of the conversation flow

last_modification_timestampinteger required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example response

{
  "model_temperature": 0.7,
  "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"
        }
      ]
    }
  ],
  "last_modification_timestamp": 1703413636133
}

Changes

  • de3a1d542da5Revision changes
    • warning

      removed the request property /////////////

    • warning

      removed the optional property ///////////// from the response with the status

  • 5d018ad1bc4dRevision changes
    • info

      added to the //////// request property anyOf list

    • info

      added to the //////// response property anyOf list for the response status