"llm_id": "..."

"version": 0

"general_prompt": "..."

"general_tools": [...]

"states": [...]

"starting_state": "..."

"last_modification_timestamp": 170...

python
pip install retell-sdk

python
import Retell from 'retell-sdk';
const client = new Retell({
 apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
}) ;
const conversationFlowResponse = await client.conversationFlow.retrieve('conversation_flow_id') ;
console.log(conversationFlowResponse.conversation_flow_id) ;

nodes[]

edges[]

components[]

start_node_id

nodes

id

type

edges

destination_node_id

requests

python
pip install retell-sdk networkx matplotlib

python
import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,  # This is the default and can be omitted
)

python
client.conversation_flow.retrieve(conversation_flow_id)

python
import networkx as nx
import matplotlib.pyplot as plt

# Retrieve the conversation flow
conversation_flow_id = "your_conversation_flow_id_here"
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

# Create a directed graph
G = nx.DiGraph()

# Add nodes from the conversation flow
for node in flow_data.nodes:
    node_label = f"{node['id']}\n({node['type']}) "
    G.add_node(node['id'], label=node_label)
    
    # Add edges based on transitions
    if 'edges' in node:
        for edge in node['edges']:
            G.add_edge(
                node['id'], 
                edge['destination_node_id'],
                label=edge.get('id', '')
            )

# Create the visualization
plt.figure(figsize=(15, 10) )
pos = nx.spring_layout(G, k=2, iterations=50)

# Draw nodes
nx.draw_networkx_nodes(G, pos, node_color='lightblue', 
                       node_size=3000, alpha=0.9)

# Draw edges
nx.draw_networkx_edges(G, pos, edge_color='gray', 
                       arrows=True, arrowsize=20)

# Draw labels
labels = nx.get_node_attributes(G, 'label')
nx.draw_networkx_labels(G, pos, labels, font_size=8)

# Draw edge labels
edge_labels = nx.get_edge_attributes(G, 'label')
nx.draw_networkx_edge_labels(G, pos, edge_labels, font_size=6)

plt.title("Conversation Flow Tree")
plt.axis('off')
plt.tight_layout()
plt.show()

destination_node_id

nodes[]

edges[]

destination_node_id

start_node_id

components[]

python
import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

# Retrieve a specific agent
agent_response = client.agent.retrieve('your_agent_id_here')
print(agent_response.agent_id)

python
import Retell from 'retell-sdk';
const client = new Retell({
 apiKey: process.env['RETELL_API_KEY'],
}) ;
const agentResponses = await client.agent.list() ;

agent_id

version

response_engine

voice_id

agent_name

version

agent_id

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

python
pip install retell-sdk networkx matplotlib

python
import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

# Get the agent details
agent = client.agent.retrieve('your_agent_id_here')

# Extract conversation flow ID from agent's response_engine
# For conversation flow agents, the response_engine will contain conversation_flow_id
conversation_flow_id = agent.response_engine.get('conversation_flow_id')

python
# Retrieve the conversation flow
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

python
import networkx as nx
import matplotlib.pyplot as plt

# Create a directed graph
G = nx.DiGraph()

# Add nodes from the conversation flow
for node in flow_data.nodes:
    node_label = f"{node['id']}\n({node['type']}) "
    G.add_node(node['id'], label=node_label)
    
    # Add edges based on transitions
    if 'edges' in node:
        for edge in node['edges']:
            G.add_edge(
                node['id'], 
                edge['destination_node_id'],
                label=edge.get('id', '')
            )

# Create the visualization
plt.figure(figsize=(15, 10) )
pos = nx.spring_layout(G, k=2, iterations=50)

# Draw nodes
nx.draw_networkx_nodes(G, pos, node_color='lightblue', 
                       node_size=3000, alpha=0.9)

# Draw edges
nx.draw_networkx_edges(G, pos, edge_color='gray', 
                       arrows=True, arrowsize=20)

# Draw labels
labels = nx.get_node_attributes(G, 'label')
nx.draw_networkx_labels(G, pos, labels, font_size=8)

# Draw edge labels
edge_labels = nx.get_edge_attributes(G, 'label')
nx.draw_networkx_edge_labels(G, pos, edge_labels, font_size=6)

plt.title(f"Conversation Flow Tree for Agent: {agent.agent_name}")
plt.axis('off')
plt.tight_layout()
plt.show()

destination_node_id

nodes[]

edges[]

destination_node_id

start_node_id

components[]

python
pip install retell-sdk networkx matplotlib

python
import os
from retell import Retell
import networkx as nx
import matplotlib.pyplot as plt

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

python
# Replace with your agent ID
agent_id = 'your_agent_id_here'

# Step 1: Retrieve agent details
agent = client.agent.retrieve(agent_id)
print(f"Agent Name: {agent.agent_name}")

# Step 2: Extract conversation flow ID from agent's response_engine
# For conversation flow agents, the response_engine contains conversation_flow_id
if hasattr(agent.response_engine, 'conversation_flow_id') :
    conversation_flow_id = agent.response_engine.conversation_flow_id
    print(f"Conversation Flow ID: {conversation_flow_id}")
else:
    print("This agent does not use a conversation flow")
    exit()

# Step 3: Retrieve the conversation flow data
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

python
# Step 4: Build and visualize the graph
G = nx.DiGraph()

# Add nodes from the conversation flow
for node in flow_data.nodes:
    node_id = node['id']
    node_type = node.get('type', 'unknown')
    node_label = f"{node_id}\n({node_type}) "
    
    G.add_node(node_id, label=node_label, type=node_type)
    
    # Add edges based on transitions
    if 'edges' in node:
        for edge in node['edges']:
            destination = edge.get('destination_node_id')
            edge_id = edge.get('id', '')
            
            if destination:
                G.add_edge(node_id, destination, label=edge_id)

# Highlight the start node
start_node = flow_data.start_node_id

# Create visualization
plt.figure(figsize=(16, 12) )
pos = nx.spring_layout(G, k=3, iterations=100, seed=42)

# Color nodes differently based on type and start node
node_colors = []
for node in G.nodes() :
    if node == start_node:
        node_colors.append('lightgreen')  # Start node
    else:
        node_colors.append('lightblue')   # Other nodes

# Draw the graph
nx.draw_networkx_nodes(G, pos, node_color=node_colors, 
                       node_size=4000, alpha=0.9, 
                       edgecolors='black', linewidths=2)

nx.draw_networkx_edges(G, pos, edge_color='gray', 
                       arrows=True, arrowsize=25, 
                       arrowstyle='->', width=2)

# Draw node labels
labels = nx.get_node_attributes(G, 'label')
nx.draw_networkx_labels(G, pos, labels, font_size=9, 
                        font_weight='bold')

# Draw edge labels
edge_labels = nx.get_edge_attributes(G, 'label')
nx.draw_networkx_edge_labels(G, pos, edge_labels, 
                             font_size=7, font_color='red')

plt.title(f"Conversation Flow Tree\nAgent: {agent.agent_name}\nFlow ID: {conversation_flow_id}", 
          fontsize=14, fontweight='bold')
plt.axis('off')
plt.tight_layout()
plt.sh

ow()

# Print summary statistics
print(f"\n=== Conversation Flow Summary ===")
print(f"Total Nodes: {len(flow_data.nodes) }")
print(f"Start Node: {start_node}")
print(f"Total Edges: {G.number_of_edges() }")

RETELL_API_KEY

'your_agent_id_here'

python
import os
from retell import Retell
import networkx as nx
import matplotlib.pyplot as plt

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

python
# Replace with your agent ID
agent_id = 'your_agent_id_here'

# Step 1: Retrieve agent details
agent = client.agent.retrieve(agent_id)
print(f"Agent Name: {agent.agent_name}")
print(f"Response Engine Type: {agent.response_engine.get('type') }")

# Step 2: Check if agent uses conversation flow
response_engine = agent.response_engine

if response_engine.get('type') == 'conversation_flow':
    conversation_flow_id = response_engine.get('conversation_flow_id')
    print(f"Conversation Flow ID: {conversation_flow_id}")
elif response_engine.get('type') == 'retell-llm':
    print("This agent uses Retell LLM, not Conversation Flow")
    print("You need an agent with response_engine type 'conversation_flow'")
    exit()
else:
    print(f"This agent uses {response_engine.get('type') }, not Conversation Flow")
    exit()

# Step 3: Retrieve the conversation flow data
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

response_engine

type

"conversation_flow"

"retell-llm"

"custom-llm"

conversation_flow_id

conversation_flow_id

python
import os
from retell import Retell
import networkx as nx
import matplotlib.pyplot as plt

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

# Replace with your agent ID
agent_id = 'your_agent_id_here'

# Step 1: Retrieve agent details
agent = client.agent.retrieve(agent_id)
print(f"Agent Name: {agent.agent_name}")

# Step 2: Access conversation_flow_id correctly
# The response_engine is a dictionary/object containing the conversation_flow_id
try:
    # Try accessing as attribute
    if hasattr(agent, 'response_engine') :
        response_engine = agent.response_engine
        
        # Check if it's a dictionary
        if isinstance(response_engine, dict) :
            conversation_flow_id = response_engine.get('conversation_flow_id')
        else:
            # Access as attribute
            conversation_flow_id = getattr(response_engine, 'conversation_flow_id', None)
        
        if not conversation_flow_id:
            print("Error: conversation_flow_id not found in response_engine")
            print(f"Response engine content: {response_engine}")
            exit()
        
        print(f"Conversation Flow ID: {conversation_flow_id}")
    else:
        print("Error: Agent does not have response_engine attribute")
        exit()
        
except Exception as e:
    print(f"Error accessing conversation_flow_id: {e}")
    print(f"Agent data: {agent}")
    exit()

# Step 3: Retrieve the conversation flow data
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

conversation_flow_id

response_engine

agent

global_prompt

global_prompt

python
import os
from retell import Retell

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

python
# Replace with your agent ID
agent_id = 'your_agent_id_here'

# Step 1: Retrieve agent details
agent = client.agent.retrieve(agent_id)

# Step 2: Extract conversation_flow_id from response_engine
response_engine = agent.response_engine

if isinstance(response_engine, dict) :
    conversation_flow_id = response_engine.get('conversation_flow_id')
else:
    conversation_flow_id = getattr(response_engine, 'conversation_flow_id', None)

# Step 3: Retrieve the conversation flow to access global_prompt
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

# Step 4: Extract global_prompt
global_prompt = flow_data.global_prompt
print(f"Global Prompt: {global_prompt}")

global_prompt

global_prompt

conversation_flow_id

response_engine

global_prompt

global_prompt

python
import os
from retell import Retell

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

# Replace with your values
agent_id = 'your_agent_id_here'
new_global_prompt = "Your new global prompt text here"

# Step 1: Get the agent and extract conversation_flow_id
agent = client.agent.retrieve(agent_id)
response_engine = agent.response_engine

if isinstance(response_engine, dict) :
    conversation_flow_id = response_engine.get('conversation_flow_id')
else:
    conversation_flow_id = getattr(response_engine, 'conversation_flow_id', None)

# Step 2: Update the conversation flow with new global_prompt
updated_flow = client.conversationFlow.update(
    conversation_flow_id,
    global_prompt=new_global_prompt
)

print(f"Global prompt updated successfully!")
print(f"New global prompt: {updated_flow.global_prompt}")

global_prompt

global_prompt

conversation_flow_id

conversation_flow

conversationFlow

python
import os
from retell import Retell

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

# Replace with your values
agent_id = 'your_agent_id_here'
new_global_prompt = "Your new global prompt text here"

# Step 1: Get the agent and extract conversation_flow_id
agent = client.agent.retrieve(agent_id)
response_engine = agent.response_engine

if isinstance(response_engine, dict) :
    conversation_flow_id = response_engine.get('conversation_flow_id')
else:
    conversation_flow_id = getattr(response_engine, 'conversation_flow_id', None)

# Step 2: Update the conversation flow with new global_prompt
# Use conversation_flow (with underscore) , not conversationFlow
updated_flow = client.conversation_flow.update(
    conversation_flow_id,
    global_prompt=new_global_prompt
)

print(f"Global prompt updated successfully!")
print(f"New global prompt: {updated_flow.global_prompt}")

client.conversationFlow.update()

client.conversation_flow.update()

python
# Replace with your agent ID
agent_id = 'your_agent_id_here'

# Step 1: Get the agent and extract conversation_flow_id
agent = client.agent.retrieve(agent_id)
response_engine = agent.response_engine

if isinstance(response_engine, dict) :
    conversation_flow_id = response_engine.get('conversation_flow_id')
else:
    conversation_flow_id = getattr(response_engine, 'conversation_flow_id', None)

# Step 2: Retrieve the conversation flow
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

# Step 3: Extract all nodes with their prompts
nodes_list = []

for node in flow_data.nodes:
    node_info = {
        'id': node['id'],
        'type': node['type'],
        'instruction': None,
        'edges': []
    }
    
    # Extract instruction/prompt if it exists
    if 'instruction' in node:
        instruction = node['instruction']
        if isinstance(instruction, dict) :
            if instruction.get('type') == 'prompt':
                node_info['instruction'] = instruction.get('text')
            else:
                node_info['instruction'] = instruction
        else:
            node_info['instruction'] = instruction
    
    # Extract edges (transitions)
    if 'edges' in node:
        for edge in node['edges']:
            edge_info = {
                'edge_id': edge.get('id') ,
                'destination': edge.get('destination_node_id') ,
                'transition_condition': edge.get('transition_condition')
            }
            node_info['edges'].append(edge_info)
    
    nodes_list.append(node_info)

# Step 4: Print all nodes and their details
print(f"=== Conversation Flow Nodes ===")
print(f"Total Nodes: {len(nodes_list) }\n")

for i, node in enumerate(nodes_list, 1) :
    print(f"Node {i}:")
    print(f"  ID: {node['id']}")
    print(f"  Type: {node['type']}")
    print(f"  Instruction/Prompt: {node['instruction']}")

python
import os
from retell import Retell

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

print(f"  Number of Edges: {len(node['edges']) }")
    
    if node['edges']:
        print(f"  Transitions:")
        for edge in node['edges']:
            print(f"    - To: {edge['destination']}")
            print(f"      Condition: {edge['transition_condition']}")
    print()

instruction

"prompt"

nodes[]

instruction

type: "prompt"

text

edges[]

destination_node_id

python
import streamlit as st
import plotly.graph_objects as go
from retell import Retell
import os

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

python
# Retrieve conversation flow
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

python
# Update conversation flow with modified nodes
updated_flow = client.conversation_flow.update(
    conversation_flow_id,
    nodes=[
        {
            "id": "node_id",
            "type": "conversation",
            "instruction": {
                "type": "prompt",
                "text": "Updated prompt text"
            }
        }
    ]
)

begin_tag_display_position

client.conversation_flow.update()

python
# Step 3: Convert to dictionary and save as JSON
flow_dict = flow_data.model_dump() if hasattr(flow_data, 'model_dump') else dict(flow_data)

# Save to file
filename = f'conversation_flow_{conversation_flow_id}.json'
with open(filename, 'w') as f:
    json.dump(flow_dict, f, indent=2)

print(f"✅ Downloaded conversation flow to {filename}")

# Download the file to your local machine
files.download(filename)

# ============================================
# PART 2: UPLOAD AND UPDATE CONVERSATION FLOW
# ============================================

print("\n--- Upload JSON to Update Conversation Flow ---")

# Upload JSON file from local machine
uploaded = files.upload()

# Get the uploaded filename
uploaded_filename = list(uploaded.keys() ) [0]

# Load the JSON data
with open(uploaded_filename, 'r') as f:
    updated_flow_data = json.load(f)

print(f"✅ Loaded JSON from {uploaded_filename}")

# Extract conversation_flow_id from the JSON
conversation_flow_id = updated_flow_data.get('conversation_flow_id')

if not conversation_flow_id:
    print("❌ Error: conversation_flow_id not found in JSON")
else:
    # Prepare update parameters (remove read-only fields)
    update_params = {k: v for k, v in updated_flow_data.items() 
                     if k not in ['conversation_flow_id', 'version']}
    
    # Update the conversation flow
    updated_flow = client.conversation_flow.update(
        conversation_flow_id,
        **update_params
    )

python
    print(f"✅ Successfully updated conversation flow: {conversation_flow_id}")
    print(f"New version: {updated_flow.version}")

python
os.environ["RETELL_API_KEY"] = "your_api_key_here"

conversation_flow_id

version

global_prompt

nodes

tools

model_choice

python
# Install Retell SDK
!pip install retell-sdk

import os
import json
from retell import Retell
from google.colab import files

# Initialize Retell client
client = Retell(
    api_key=os.environ.get("RETELL_API_KEY") ,
)

python
# ============================================
# PART 1: DOWNLOAD CONVERSATION FLOW JSON
# ============================================

# Replace with your agent ID
agent_id = 'your_agent_id_here'

# Step 1: Get the agent and extract conversation_flow_id
agent = client.agent.retrieve(agent_id)
response_engine = agent.response_engine

if isinstance(response_engine, dict) :
    conversation_flow_id = response_engine.get('conversation_flow_id')
else:
    conversation_flow_id = getattr(response_engine, 'conversation_flow_id', None)

print(f"Conversation Flow ID: {conversation_flow_id}")

# Step 2: Retrieve the conversation flow data
flow_data = client.conversation_flow.retrieve(conversation_flow_id)

Agent: "Hi! I'd like to help you book an appointment. May I have your name?"
User: "John Smith"
Agent: "Thanks John. What date works best for you?"
User: "Actually, I need to speak to a human"
Agent: "I understand you'd like to speak with someone. Let me first finish collecting your preferred date, then I can help with that. What date works for you?"

Agent: "Hi! I'd like to help you book an appointment. May I have your name?"
User: "John Smith"
Agent: "Thanks John. What date works best for you?"
User: "Actually, I need to speak to a human"
Agent: [GLOBAL NODE TRIGGERS INSTANTLY] "I completely understand. Transferring you to our team now. One moment..."
[Transfer initiated]
User: "Wait, I changed my mind. Can we just book the appointment?"
Agent: [RETURNS AND RESUMES] "Absolutely! We were collecting your preferred date. What date works best?"
User: "Next Tuesday at 2pm, and I also need to reschedule my existing appointment for next Friday"
Agent: [HANDLES MULTIPLE TASKS] "Perfect! I'll book Tuesday at 2pm for you, and I can also help reschedule your Friday appointment. Let me handle the Tuesday booking first, then we'll update Friday..."

Agent: "Hi! I'd like to help you book an appointment. May I have your name?"
User: "John Smith"
Agent: "Thanks John. What date works best for you?"
User: "Actually, I need to speak to a human"
Agent: [GLOBAL NODE TRIGGERS] "I understand. Let me transfer you to our team right away. One moment please..."
[Transfer initiated]
User: "Wait, actually I changed my mind. Can we just finish the booking?"
Agent: [RETURNS TO NODE 3] "Of course! Let's continue. What date works best for you?"
User: "Next Tuesday"
Agent: "Great! What time on Tuesday?"

Agent: "Hi! I'd like to help you book an appointment. May I have your name?"
User: "John Smith"
Agent: "Thanks John. What date works best for you?"
User: "Actually, I need to speak to a human"
Agent: "I understand you'd like to speak with someone. I can help transfer you, but let me quickly note what we've covered so far - I have your name as John Smith. Would you like me to transfer you now, or shall we finish booking first?"
User: "Let's finish booking"
Agent: "Perfect. What date works for you?"
User: "Next Tuesday at 2pm"
Agent: [SWITCHES TASKS] "Great! I've noted Tuesday at 2pm. Let me confirm that appointment for you now..."

{}

[]

"

'

"model_choice"

"type"

"model"

"start_speaker"

"user"

"agent"

"nodes"

"id"

"type"

"conversation"

"instruction"

"type"

"text"

"conversation_flow_id"

"version"

json
{
  "model_choice": {
    "type": "cascading",
    "model": "gpt-4.1"
  },
  "start_speaker": "agent",
  "nodes": [
    {
      "id": "start",
      "type": "conversation",
      "instruction": {
        "type": "prompt",
        "text": "Your prompt here"
      }
    }
  ]
}

{}

[]

"

'

headers

query_params

response_variables

{}

[]

model_choice

type

model

start_speaker

"user"

"agent"

nodes

conversation_flow_id

version

javascript
{
  "model_choice": {
    "type": "cascading",
    "model": "gpt-4.1"
  },
  "start_speaker": "agent",
  "nodes": [
    {
      "id": "start",
      "type": "conversation",
      "instruction": {
        "type": "prompt",
        "text": "Greet the customer and ask how you can help them."
      }
    }
  ]
}

call_started

call_ended

call_analyzed

transcript_updated

call_analyzed

otp_code

Number

javascript
// Example: verify OTP using Code Tool
const spokenOTP = dv.otp_code;
const generatedOTP = metadata.generated_otp; // stored when OTP was sent

if (spokenOTP === generatedOTP) {
  return { verified: true, message: "Authentication successful" };
} else {
  return { verified: false, message: "Invalid code" };
}