The Retell AI connector lets your AI agent act in each user's Retell AI account. Each user connects their own Retell AI access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 83 tools.
- Tools
- 83
- What they doRead · write · destructive
- 36 · 34 · 1336 read34 write13 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Retell AI connection
In AgentKit > Connections, create a Retell AI connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'retell'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Retell AI:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'retell_get_api_key_info',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "retell"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Retell AI:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="retell_get_api_key_info",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Retell AI credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolretell_agent_playground_completionGet an agent's next reply to a conversation you supply, without creating a chat or storing anything in Retell.Read-onlyAgent Playground Completion
Get an agent's next reply to a conversation you supply, without creating a chat or storing anything in Retell. Returns messages (only the newly generated messages), current_state or current_node_id, dynamic_variables, call_ended and any knowledge base content retrieved. Use retell_agent_playground_completion to test how an agent responds. Use retell_create_chat_completion to continue a real chat.
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
messagesarrayrequired- Full conversation so far, oldest first. Each message has a role (user or agent) and content; tool call messages may also appear. Example: [{"role": "user", "content": "Hi, I'd like to check my appointment."}]
component_idstring- Conversation flow component ID, required when current_node_id is a node inside a component. Example: component_xyz789
current_node_idstring- For conversation flow agents, the node to resume from. Example: start-node-abc123
current_statestring- For Retell LLM agents, the state to resume from. Example: greeting
dynamic_variablesobject- Dynamic variables to substitute into the prompt, as string key-value pairs. Example: {"customer_name": "John Smith"}
tool_mocksarray- Mocked tool results so the agent does not call real tools. Each mock names the tool_name, an input_match_rule and the output string. Example: [{"tool_name": "check_availability", "input_match_rule": {"type": "any"}, "output": "{\"available\": true}"}]
versioninteger- Agent version to use. Omit for the latest version. Example: 2
retell_get_agentGet the full configuration of a Retell voice agent.Read-onlyGet Agent
Get the full configuration of a Retell voice agent. Returns the agent object, including agent_id, version, is_published, response_engine, agent_name, voice_id, language and the voice, webhook and call settings. Use retell_get_agent for voice agents. Use retell_get_chat_agent for chat agents and retell_list_agent_versions to see its versions.
Inputs
agent_idstringrequired- ID of the voice agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
versioninteger- Agent version to retrieve. Omit for the latest version. Example: 2
retell_get_api_key_infoGet information about the API key used for this connection and the organization that owns it.Read-onlyGet API Key Info
Get information about the API key used for this connection and the organization that owns it. Returns org_id, org_name and api_key_name. Use retell_get_api_key_info to confirm which Retell organization the connection acts on.
Inputs
This tool takes no inputs.
retell_get_batch_testGet the status and pass/fail counts of a Retell batch test job.Read-onlyGet Batch Test
Get the status and pass/fail counts of a Retell batch test job. Returns the batch test job, including test_case_batch_job_id, status, response_engine, pass_count, fail_count, error_count, total_count and timestamps. Use retell_get_batch_test to check whether a batch has finished. Use retell_list_test_runs for the individual results.
Inputs
test_case_batch_job_idstringrequired- ID of the batch test job, from the `test_case_batch_job_id` field returned by retell_create_batch_test or retell_list_batch_tests. Example: 7e6d5c4b3a2918070f1e2d3c4b5a6978
retell_get_callGet the full record of one Retell phone or web call.Read-onlyGet Call
Get the full record of one Retell phone or web call. Returns the call object: call_id, call_type, call_status, agent_id, from_number, to_number, direction, start and end timestamps, duration_ms, transcript, transcript_object, recording_url, public_log_url, disconnection_reason, call_analysis (summary, sentiment, success, custom data), call_cost and latency. Use retell_get_call for one call's transcript and analysis. Use retell_list_calls to find calls.
Inputs
call_idstringrequired- ID of the call, from the `call_id` field returned by retell_list_calls or retell_create_phone_call. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_get_chatGet the full record of one Retell chat or SMS conversation.Read-onlyGet Chat
Get the full record of one Retell chat or SMS conversation. Returns the chat object, including chat_id, agent_id, chat_status, chat_type, transcript, messages with tool calls, metadata, chat_cost and chat_analysis. Use retell_get_chat for one conversation's messages and analysis. Use retell_list_chats to find chats.
Inputs
chat_idstringrequired- ID of the chat, from the `chat_id` field returned by retell_list_chats or retell_create_chat. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_get_chat_agentGet the full configuration of a Retell chat agent.Read-onlyGet Chat Agent
Get the full configuration of a Retell chat agent. Returns the chat agent object, including agent_id, version, is_published, response_engine, agent_name, language, webhook settings and post-chat analysis settings. Use retell_get_chat_agent for chat agents. Use retell_get_agent for voice agents.
Inputs
agent_idstringrequired- ID of the chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
versioninteger- Agent version to retrieve. Omit for the latest version. Example: 2
retell_get_concurrencyGet the Retell organization's current call concurrency and its limits.Read-onlyGet Concurrency
Get the Retell organization's current call concurrency and its limits. Returns current_concurrency, concurrency_limit, base_concurrency, purchased_concurrency, purchase limits, reserved_inbound_concurrency and burst settings. Use retell_get_concurrency before launching calls or a batch to check how many calls can run at once.
Inputs
This tool takes no inputs.
retell_get_contactGet one Retell contact by ID.Read-onlyGet Contact
Get one Retell contact by ID. Returns the contact object, including contact_id, phone_number, first_name, last_name, do_not_call, contact_memory, contact_tags, custom_fields, conversation_count and timestamps. Use retell_get_contact when you have the contact ID. Use retell_get_contact_by_phone to look up by phone number, and retell_list_contacts to search.
Inputs
contact_idstringrequired- ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0
retell_get_contact_by_phoneLook up the Retell contact for a phone number; each organization has at most one contact per number.Read-onlyGet Contact by Phone
Look up the Retell contact for a phone number; each organization has at most one contact per number. Returns the contact object, including contact_id, phone_number, first_name, last_name, do_not_call, contact_memory, contact_tags, custom_fields, conversation_count and timestamps. Use retell_get_contact_by_phone to find who is calling or texting. Use retell_get_contact when you have the contact ID.
Inputs
phone_numberstringrequired- Phone number to look up, E.164 preferred; other formats are normalized and an unparseable number returns 400. Example: +14155551234
retell_get_conversation_flowGet the full definition of a Retell conversation flow, including its nodes and tools.Read-onlyGet Conversation Flow
Get the full definition of a Retell conversation flow, including its nodes and tools. Returns the conversation flow object, including conversation_flow_id, version, model_choice, start_speaker, global_prompt, nodes, tools, components and knowledge_base_ids. Use retell_get_conversation_flow to read a flow before editing it. Use retell_list_conversation_flows to browse flows.
Inputs
conversation_flow_idstringrequired- ID of the conversation flow, from the `conversation_flow_id` field returned by retell_list_conversation_flows. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90
versioninteger- Version to retrieve. Omit for the latest version. Example: 1
retell_get_conversation_flow_componentGet a shared Retell conversation flow component and the flows that use it.Read-onlyGet Conversation Flow Component
Get a shared Retell conversation flow component and the flows that use it. Returns the component object, including conversation_flow_component_id, name, nodes, start_node_id, tools, mcps and linked_conversation_flow_ids. Use retell_get_conversation_flow_component to read one component. Use retell_list_conversation_flow_components to browse.
Inputs
conversation_flow_component_idstringrequired- ID of the shared conversation flow component, from the `conversation_flow_component_id` field returned by retell_list_conversation_flow_components. Example: f0e1d2c3b4a5968778695a4b3c2d1e0f
retell_get_knowledge_baseGet one Retell knowledge base and its sources.Read-onlyGet Knowledge Base
Get one Retell knowledge base and its sources. Returns the knowledge base object, including knowledge_base_id, knowledge_base_name, status, chunk sizes, knowledge_base_sources and auto-refresh settings. Use retell_get_knowledge_base to check a knowledge base's status and list its source IDs. Use retell_list_knowledge_bases to browse.
Inputs
knowledge_base_idstringrequired- ID of the knowledge base, from the `knowledge_base_id` field returned by retell_list_knowledge_bases. Example: knowledge_base_a456426614174000
retell_get_mcp_toolsList the tools exposed by an MCP server configured on a Retell agent.Read-onlyGet MCP Tools
List the tools exposed by an MCP server configured on a Retell agent. Returns an array of tools, each with name, description and inputSchema. Use retell_get_mcp_tools to check what an agent's MCP server offers before referencing its tools in a prompt or flow.
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
mcp_idstringrequired- ID of the MCP server configured on the agent's response engine (in its mcps list). Example: mcp_crm_server
component_idstring- ID of the conversation flow component, when the MCP server is configured inside a component. Example: component_xyz789
versioninteger- Agent version to use. Omit for the latest version. Example: 2
retell_get_phone_numberGet the configuration of one Retell phone number, including the agents bound to it.Read-onlyGet Phone Number
Get the configuration of one Retell phone number, including the agents bound to it. Returns the phone number object, including phone_number, phone_number_type, nickname, area_code, inbound_agents, outbound_agents, SMS agents, webhook URLs and allowed country lists. Use retell_get_phone_number to check which agent answers or places calls on a number. Use retell_list_phone_numbers to browse.
Inputs
phone_numberstringrequired- The phone number in E.164 format (+ country code, then the number with no spaces or symbols), as returned by retell_list_phone_numbers. Example: +14157774444
retell_get_retell_llmGet the full configuration of a Retell LLM response engine, including its prompt and tools.Read-onlyGet Retell LLM
Get the full configuration of a Retell LLM response engine, including its prompt and tools. Returns the Retell LLM object, including llm_id, version, is_published, model, general_prompt, begin_message, general_tools, states and knowledge_base_ids. Use retell_get_retell_llm to read an agent's prompt; the agent's response_engine.llm_id gives the ID. Use retell_list_retell_llms to browse.
Inputs
llm_idstringrequired- ID of the Retell LLM response engine, from the `llm_id` field returned by retell_list_retell_llms. Example: llm_234sdertfsdsfsdf
versioninteger- Version to retrieve. Omit for the latest version. Example: 1
retell_get_test_case_definitionGet one Retell test case definition.Read-onlyGet Test Case Definition
Get one Retell test case definition. Returns the test case definition, including test_case_definition_id, name, response_engine, user_prompt, metrics, dynamic_variables, tool_mocks, llm_model and timestamps. Use retell_get_test_case_definition to read a scenario. Use retell_list_test_case_definitions to browse scenarios for a response engine.
Inputs
test_case_definition_idstringrequired- ID of the test case definition to retrieve, from the `test_case_definition_id` field returned by retell_list_test_case_definitions. Example: 1a2b3c4d5e6f708192a3b4c5d6e7f809
retell_get_test_runGet one Retell test run, including the simulated conversation and why it passed or failed.Read-onlyGet Test Run
Get one Retell test run, including the simulated conversation and why it passed or failed. Returns the test run with test_case_job_id, status, test_case_definition_id, test_case_definition_snapshot, transcript_snapshot, result_explanation and timestamps. Use retell_get_test_run to debug a failing scenario. Use retell_list_test_runs to find run IDs.
Inputs
test_case_job_idstringrequired- ID of the test run, from the `test_case_job_id` field returned by retell_list_test_runs. Example: 3c2b1a0f9e8d7c6b5a49382716f5e4d3
retell_get_voiceGet details of one Retell voice.Read-onlyGet Voice
Get details of one Retell voice. Returns the voice object, including voice_id, voice_name, provider, accent, gender, age and preview_audio_url. Use retell_get_voice to check a voice by ID. Use retell_list_voices to browse voices.
Inputs
voice_idstringrequired- ID of the voice, from retell_list_voices. Example: retell-Cimo
retell_list_agent_versionsList the stored versions of a Retell voice or chat agent.Read-onlyList Agent Versions
List the stored versions of a Retell voice or chat agent. Returns a page of versions (version, is_published, version_title, version_description, base_version, last_modification_timestamp) plus pagination_key and has_more. Use retell_list_agent_versions to find a draft to publish with retell_publish_agent_version or a base for retell_create_agent_version.
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_agentsList voice and chat agents in the Retell workspace, one entry per agent, with optional filters by name, ID or channel.Read-onlyList Agents
List voice and chat agents in the Retell workspace, one entry per agent, with optional filters by name, ID or channel. Returns a page of agents (agent_id, agent_name, channel, tags, is_transfer_agent, user_modified_timestamp) plus pagination_key and has_more. Use retell_list_agents to find an agent ID. Use retell_get_agent or retell_get_chat_agent for an agent's full configuration.
Inputs
filter_criteriaobject- Filters, combined with AND. Use query for a case-insensitive substring match on agent name or ID, channel to limit to voice or chat agents, and is_transfer_agent for transfer agents. Example: {"query": "support", "channel": {"type": "string", "op": "eq", "value": "voice"}}
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_batch_testsList batch test jobs run against one Retell LLM or conversation flow.Read-onlyList Batch Tests
List batch test jobs run against one Retell LLM or conversation flow. Returns a page of batch test jobs (test_case_batch_job_id, status, pass_count, fail_count, error_count, total_count, creation_timestamp) plus pagination_key and has_more. Use retell_list_batch_tests to review test history for a response engine. Use retell_get_batch_test for one job.
Inputs
typestringrequired- Type of response engine the tests belong to: retell-llm or conversation-flow. Pass llm_id or conversation_flow_id to match.one of
retell-llmconversation-flow conversation_flow_idstring- Conversation flow ID, required when type is conversation-flow. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
llm_idstring- Retell LLM ID, required when type is retell-llm. Example: llm_234sdertfsdsfsdf
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
versioninteger- Response engine version the tests ran against. Omit for the latest version. Example: 2
retell_list_callsList phone and web calls in the Retell workspace, newest first by default, with filters by agent, status, direction, numbers, time range, sentiment and more.Read-onlyList Calls
List phone and web calls in the Retell workspace, newest first by default, with filters by agent, status, direction, numbers, time range, sentiment and more. Returns a page of call objects (call_id, agent_id, call_status, from_number, to_number, start_timestamp, duration_ms, transcript, recording_url, call_analysis, call_cost) plus pagination_key, has_more and optionally total. Use retell_list_calls to search call history. Use retell_get_call for one call's full details.
Inputs
filter_criteriaobject- Filters, combined with AND. Each field takes a typed condition: agent is a list of {agent_id, version}; call_status, direction, call_type and user_sentiment take {"type": "enum", "op": "in", "value": [...]}; from_number and to_number take {"type": "string", "op": "eq", "value": "+1..."}; start_timestamp takes {"type": "number", "op": "ge", "value": <epoch ms>} or {"type": "range", "op": "bt", "value": [from, to]}. Example: {"agent": [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"}], "call_status": {"type": "enum", "op": "in", "value": ["ended"]}}
include_totalboolean- Also return total, the number of calls matching the filters. Adds an extra query, so request it only when needed. Defaults to false.
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort calls by start_timestamp: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_chatsList chat and SMS conversations in the Retell workspace, newest first by default, with filters by agent, status, type, numbers, time range and sentiment.Read-onlyList Chats
List chat and SMS conversations in the Retell workspace, newest first by default, with filters by agent, status, type, numbers, time range and sentiment. Returns a page of chat objects (chat_id, agent_id, chat_status, chat_type, start_timestamp, transcript, chat_analysis, chat_cost) plus pagination_key, has_more and optionally total. Use retell_list_chats to search chat history. Use retell_get_chat for one chat's full messages.
Inputs
filter_criteriaobject- Filters, combined with AND. agent is a list of {agent_id, version}; chat_status, chat_type, direction and user_sentiment take {"type": "enum", "op": "in", "value": [...]}; agent_number and user_number take {"type": "string", "op": "eq", "value": "+1..."}; start_timestamp takes {"type": "number", "op": "ge", "value": <epoch ms>} or a {"type": "range", "op": "bt"} pair. Example: {"agent": [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"}]}
include_totalboolean- Also return total, the number of chats matching the filters. Adds an extra query, so request it only when needed. Defaults to false.
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort chats by start_timestamp: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_contact_conversationsList a Retell contact's inbound calls, outbound calls and chats in one timeline, most recent first, matched by the contact's phone number.Read-onlyList Contact Conversations
List a Retell contact's inbound calls, outbound calls and chats in one timeline, most recent first, matched by the contact's phone number. Returns a page of conversations (type, call_id or chat_id, start_timestamp, duration_ms, direction, disconnection_reason, summary, sentiment, successful) plus pagination_key and has_more. Use retell_list_contact_conversations for one person's history. Use retell_get_call or retell_get_chat for a conversation's transcript.
Inputs
contact_idstringrequired- ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
retell_list_contactsList and search Retell contacts, newest first by default, by text or by filters on phone number, tags, do-not-call status and last conversation time.Read-onlyList Contacts
List and search Retell contacts, newest first by default, by text or by filters on phone number, tags, do-not-call status and last conversation time. Returns a page of contact objects (contact_id, phone_number, first_name, last_name, do_not_call, contact_tags, custom_fields, conversation_count) plus pagination_key, has_more and total. Use retell_list_contacts to search contacts by name or filters. Use retell_get_contact_by_phone for an exact phone number lookup.
Inputs
excluded_contact_idsarray- Contact IDs to leave out of the results and the total. Example: ["9f8e7d6c5b4a39281706f5e4d3c2b1a0"]
filter_criteriaobject- Filters, combined with AND. phone_number and contact_id take {"type": "string", "op": "eq", "value": ...}; do_not_call takes {"type": "boolean", "op": "eq", "value": true}; contact_tag_ids takes {"type": "enum", "op": "in", "value": [...]}; last_conversation_timestamp takes a number or range condition in epoch ms. Example: {"do_not_call": {"type": "boolean", "op": "eq", "value": false}}
limitinteger- Maximum number of contacts to return, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
search_querystring- Case-insensitive text matched against phone number, first name, last name, external ID and custom field values. The only way to search by name. Example: smith
sort_orderstring- Sort by created time: asc or desc. Defaults to desc (newest first).one of
ascdesc
retell_list_conversation_flow_componentsList shared conversation flow components in the Retell workspace.Read-onlyList Conversation Flow Components
List shared conversation flow components in the Retell workspace. Returns a page of component objects (conversation_flow_component_id, name, nodes, linked_conversation_flow_ids) plus pagination_key and has_more. Use retell_list_conversation_flow_components to find a component ID. Use retell_get_conversation_flow_component for one component.
Inputs
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_conversation_flowsList conversation flow response engines in the Retell workspace.Read-onlyList Conversation Flows
List conversation flow response engines in the Retell workspace. Returns a page of conversation flow objects (conversation_flow_id, version, model_choice, nodes, global_prompt) plus pagination_key and has_more. Use retell_list_conversation_flows to find a conversation_flow_id. Use retell_get_conversation_flow for one flow.
Inputs
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_export_requestsList history export requests in the Retell workspace.Read-onlyList Export Requests
List history export requests in the Retell workspace. Returns a page of export requests (export_request_id, channel, status, url, created_timestamp, timezone) plus pagination_key and has_more. Use retell_list_export_requests to find the download URL of a finished call or chat history export.
Inputs
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_knowledge_basesList all knowledge bases in the Retell workspace.Read-onlyList Knowledge Bases
List all knowledge bases in the Retell workspace. Returns an array of knowledge base objects (knowledge_base_id, knowledge_base_name, status, chunk sizes, knowledge_base_sources, enable_auto_refresh). Use retell_list_knowledge_bases to find knowledge base IDs to attach to a Retell LLM or conversation flow. Use retell_get_knowledge_base for one knowledge base.
Inputs
This tool takes no inputs.
retell_list_phone_numbersList phone numbers bought in or imported into the Retell workspace.Read-onlyList Phone Numbers
List phone numbers bought in or imported into the Retell workspace. Returns a page of phone number objects (phone_number, phone_number_type, nickname, area_code, inbound and outbound agents, SMS agents, webhook URLs) plus pagination_key and has_more. Use retell_list_phone_numbers to find a from_number for calls. Use retell_get_phone_number for one number.
Inputs
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_retell_llmsList Retell LLM response engines in the workspace.Read-onlyList Retell LLMs
List Retell LLM response engines in the workspace. Returns a page of Retell LLM objects (llm_id, version, model, general_prompt, begin_message, tools) plus pagination_key and has_more. Use retell_list_retell_llms to find an llm_id. Use retell_get_retell_llm for one engine's full configuration.
Inputs
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
sort_orderstring- Sort order for results: ascending or descending. Defaults to descending.one of
ascendingdescending
retell_list_test_case_definitionsList the test case definitions for one Retell LLM or conversation flow.Read-onlyList Test Case Definitions
List the test case definitions for one Retell LLM or conversation flow. Returns a page of test case definitions (test_case_definition_id, name, user_prompt, metrics, llm_model) plus pagination_key and has_more. Use retell_list_test_case_definitions to collect IDs for retell_create_batch_test. Use retell_get_test_case_definition for one scenario.
Inputs
typestringrequired- Type of response engine the tests belong to: retell-llm or conversation-flow. Pass llm_id or conversation_flow_id to match.one of
retell-llmconversation-flow conversation_flow_idstring- Conversation flow ID, required when type is conversation-flow. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
llm_idstring- Retell LLM ID, required when type is retell-llm. Example: llm_234sdertfsdsfsdf
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
retell_list_test_runsList the individual test runs in a Retell batch test job.Read-onlyList Test Runs
List the individual test runs in a Retell batch test job. Returns a page of test runs (test_case_job_id, status, test_case_definition_id, result_explanation, timestamps) plus pagination_key and has_more. Use retell_list_test_runs to see which scenarios passed or failed. Use retell_get_test_run for one run's transcript.
Inputs
test_case_batch_job_idstringrequired- ID of the batch test job, from the `test_case_batch_job_id` field returned by retell_create_batch_test or retell_list_batch_tests. Example: 7e6d5c4b3a2918070f1e2d3c4b5a6978
limitinteger- Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20
pagination_keystring- Cursor for the next page. Pass the `pagination_key` value from the previous response when `has_more` is true; leave empty for the first page.
retell_list_voicesList all voices available to the Retell workspace, including provider and cloned voices.Read-onlyList Voices
List all voices available to the Retell workspace, including provider and cloned voices. Returns an array of voice objects (voice_id, voice_name, provider, accent, gender, age, preview_audio_url). Use retell_list_voices to pick a voice_id for an agent. Use retell_search_community_voice to find more voices from providers.
Inputs
This tool takes no inputs.
retell_search_community_voiceSearch community voices from voice providers such as ElevenLabs, Cartesia, MiniMax, Fish Audio and Inworld by name, description or ID.Read-onlySearch Community Voices
Search community voices from voice providers such as ElevenLabs, Cartesia, MiniMax, Fish Audio and Inworld by name, description or ID. Returns voices: matching provider voices, each with provider_voice_id, name, description and (for ElevenLabs) public_user_id. Use retell_search_community_voice to find a voice that is not in your library yet, then add it with retell_add_community_voice. Use retell_list_voices for voices you already have.
Inputs
search_querystringrequired- Text to search for in voice names, descriptions or IDs. Example: warm british female
voice_providerstring- Provider to search: elevenlabs, cartesia, minimax, fish_audio or inworld. Example: elevenlabsone of
elevenlabscartesiaminimaxfish_audioinworld
retell_add_community_voiceAdd a community voice from a voice provider to the Retell workspace's voice library.WriteAdd Community Voice
Add a community voice from a voice provider to the Retell workspace's voice library. Returns the voice object, including voice_id, voice_name, provider, accent, gender, age and preview_audio_url. Use retell_add_community_voice after finding a voice with retell_search_community_voice; then use the returned voice_id in retell_create_agent.
Inputs
provider_voice_idstringrequired- Voice ID assigned by the provider, from retell_search_community_voice. Example: 21m00Tcm4TlvDq8ikWAM
voice_namestringrequired- Name to give the voice in your library. Example: Support Voice
public_user_idstring- User ID of the voice owner. Required for ElevenLabs voices only. Example: 63e06b7e7cafdc46be4d2e0b
voice_providerstring- Provider the voice comes from: elevenlabs, cartesia, minimax, fish_audio or inworld. Example: elevenlabsone of
elevenlabscartesiaminimaxfish_audioinworld
retell_create_agentCreate a Retell voice agent from a response engine and a voice, with optional language, voice, timing, webhook and post-call analysis settings.WriteCreate Agent
Create a Retell voice agent from a response engine and a voice, with optional language, voice, timing, webhook and post-call analysis settings. Returns the agent object, including agent_id, version, is_published, response_engine, agent_name, voice_id, language and the voice, webhook and call settings. Use retell_create_agent for phone and web call agents. Use retell_create_chat_agent for chat and SMS agents. Create the response engine first with retell_create_retell_llm or retell_create_conversation_flow, and pick a voice with retell_list_voices.
Inputs
response_engineobjectrequired- Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": "<llm_id>"} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_id": "<id>"} for a conversation flow, or {"type": "custom-llm", "llm_websocket_url": "wss://..."} for your own LLM server. Retell LLM and conversation flow engines may also take a numeric version. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
voice_idstringrequired- ID of the voice the agent speaks with, from the `voice_id` field returned by retell_list_voices. Example: retell-Cimo
agent_namestring- Name of the agent, for your own reference. Example: Customer Support Agent
ambient_soundstring- Background sound mixed into the call to sound more natural: coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise or call-center. Leave empty for none.one of
coffee-shopconvention-hallsummer-outdoormountain-outdoorstatic-noisecall-center begin_message_delay_msinteger- Milliseconds to wait before the agent's first message, from 0 to 5000. Example: 1000
boosted_keywordsarray- Words the transcriber should favour, such as names and product terms. Example: ["Retell", "Kubernetes"]
data_storage_settingstring- What Retell stores for this agent's calls: everything, everything_except_pii, or basic_attributes_only (metadata only, no transcripts or recordings).one of
everythingeverything_except_piibasic_attributes_only enable_backchannelboolean- Whether the agent interjects short acknowledgements such as "yeah" or "uh-huh" while the user speaks. Defaults to false.
end_call_after_silence_msinteger- End the call when the user stays silent this many milliseconds after the agent speaks. Minimum 10000; defaults to 600000 (10 minutes). Example: 30000
interruption_sensitivitynumber- How easily the user can interrupt the agent, from 0 (cannot interrupt) to 1 (interrupts easily). Defaults to 1. Example: 0.7
languagestring- Locale the agent speaks and transcribes, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-USone of
en-USen-INen-GBen-AUen-NZde-DEes-ESes-419hi-INfr-FRfr-CAja-JPpt-PTpt-BRzh-CNru-RUit-ITko-KRnl-NLnl-BEpl-PLtr-TRvi-VNro-RObg-BGca-ESth-THda-DKfi-FIel-GRhu-HUid-IDno-NOsk-SKsv-SElt-LTlv-LVcs-CZms-MYaf-ZAar-SAaz-AZbs-BAcy-GBfa-IRfil-PHgl-EShe-ILhr-HRhy-AMis-ISkk-KZkn-INmk-MKmr-INne-NPsl-SIsr-RSsw-KEta-INur-INyue-CNuk-UA max_call_duration_msinteger- Maximum call length in milliseconds, from 60000 (1 minute) to 7200000 (2 hours). Defaults to 3600000 (1 hour). Example: 1800000
post_call_analysis_dataarray- Extra data to extract from each call after it ends. Each item has a type (string, enum, boolean or number), a name and a description; enum items also list choices. Example: [{"type": "string", "name": "order_id", "description": "The order ID the caller mentions."}]
responsivenessnumber- How quickly the agent responds, from 0 (waits longer) to 1 (responds fastest). Defaults to 1. Example: 0.8
timezonestring- IANA timezone for the agent, used for time-aware prompts. Defaults to America/Los_Angeles. Example: America/New_York
voice_modelstring- Voice model for the selected voice, when its provider offers several (for example eleven_flash_v2_5, eleven_multilingual_v2 or sonic-3). Leave empty to use the voice's default model.
voice_speednumber- Speech rate from 0.5 (slower) to 2 (faster). Defaults to 1. Example: 1.1
voice_temperaturenumber- Voice stability from 0 (more stable) to 2 (more varied). Defaults to 1. Example: 1
voicemail_optionobject- What to do when the call reaches voicemail in the first 3 minutes. The action is an object with a type: hangup, static_text (with text to speak), prompt (with text describing what to say) or bridge_transfer. Example: {"action": {"type": "static_text", "text": "Please call us back at 555-0100."}}
webhook_urlstring- URL that receives this agent's call event webhooks (call_started, call_ended, call_analyzed by default). Example: https://example.com/retell/webhook
retell_create_agent_versionCreate a new draft version of a Retell voice or chat agent, copied from an existing version.WriteCreate Agent Version
Create a new draft version of a Retell voice or chat agent, copied from an existing version. Returns the new draft agent version, including agent_id, version, base_version, is_published and the agent's settings. Use retell_create_agent_version to start editing from an older or published version. Publish the draft with retell_publish_agent_version.
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
base_versionintegerrequired- Existing version to copy into the new draft, from retell_list_agent_versions. Example: 12
retell_create_batch_callSchedule a batch of outbound calls from one Retell number, sent now or at a set time, optionally limited to calling windows.WriteCreate Batch Call
Schedule a batch of outbound calls from one Retell number, sent now or at a set time, optionally limited to calling windows. Returns the batch call object with batch_call_id, name, from_number, scheduled_timestamp, total_task_count and call_time_window. Use retell_create_batch_call for campaigns to many numbers. Use retell_create_phone_call for a single call.
Inputs
from_numberstringrequired- Number to call from, in E.164 format. Must be a number purchased from or imported to Retell. Example: +14157774444
tasksarrayrequired- One entry per outbound call. Each task needs to_number (E.164) and can add retell_llm_dynamic_variables, metadata, override_agent_id, override_agent_version and agent_override for that call. Example: [{"to_number": "+12137774445", "retell_llm_dynamic_variables": {"customer_name": "John Doe"}}]
call_time_windowobject- Hours when calls may be placed. windows is a list of {start, end} in minutes after local midnight (end up to 1440, no windows crossing midnight); timezone is an IANA name (default America/Los_Angeles); day optionally limits the days. Example: {"windows": [{"start": 540, "end": 1020}], "timezone": "America/New_York"}
namestring- Name of the batch, for your own reference. Example: March renewal reminders
reserved_concurrencyinteger- Concurrent call slots to keep free for other calls, such as inbound calls, while the batch runs. Example: 2
trigger_timestampnumber- When to start the batch, as a Unix timestamp in milliseconds. Omit to start immediately. Example: 1735718400000
retell_create_batch_testRun a set of test case definitions against a Retell LLM or conversation flow as one batch test job.WriteCreate Batch Test
Run a set of test case definitions against a Retell LLM or conversation flow as one batch test job. Returns the batch test job, including test_case_batch_job_id, status, response_engine, pass_count, fail_count, error_count, total_count and timestamps. Use retell_create_batch_test to run scenarios. Poll retell_get_batch_test for status and use retell_list_test_runs for each test's result.
Inputs
response_engineobjectrequired- Response engine the test runs against, as an object. For a Retell LLM use {"type": "retell-llm", "llm_id": "<llm_id>"}; for a conversation flow use {"type": "conversation-flow", "conversation_flow_id": "<id>"}. Either may add a numeric version. Custom LLMs are not supported. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
test_case_definition_idsarrayrequired- IDs of the test case definitions to run, from retell_list_test_case_definitions. Example: ["1a2b3c4d5e6f708192a3b4c5d6e7f809"]
retell_create_chatStart a new chat session with a Retell chat agent.WriteCreate Chat
Start a new chat session with a Retell chat agent. Returns the chat object, including chat_id, agent_id, chat_status, chat_type, transcript, messages with tool calls, metadata, chat_cost and chat_analysis. Use retell_create_chat to open a text conversation, then send user messages with retell_create_chat_completion. Use retell_create_sms_chat to start a conversation over SMS.
Inputs
agent_idstringrequired- ID of the chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_versioninteger- Agent version to use, as a version number. Omit to use the latest version. Example: 3
metadataobject- Arbitrary key-value data stored on the chat for your own reference, such as your internal customer ID. Retell does not use it for processing and returns it on the chat object. Max 50 kB. Example: {"customer_id": "cust_123"}
retell_llm_dynamic_variablesobject- Dynamic variables as string key-value pairs, injected into the response engine prompt and tool descriptions wherever {{variable_name}} appears. Example: {"customer_name": "John Doe"}
retell_create_chat_agentCreate a Retell chat agent for text and SMS conversations from a response engine, with optional language, webhook and post-chat analysis settings.WriteCreate Chat Agent
Create a Retell chat agent for text and SMS conversations from a response engine, with optional language, webhook and post-chat analysis settings. Returns the chat agent object, including agent_id, version, is_published, response_engine, agent_name, language, webhook settings and post-chat analysis settings. Use retell_create_chat_agent for chat and SMS. Use retell_create_agent for voice calls. Create the response engine first with retell_create_retell_llm or retell_create_conversation_flow.
Inputs
response_engineobjectrequired- Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": "<llm_id>"} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_id": "<id>"} for a conversation flow, or {"type": "custom-llm", "llm_websocket_url": "wss://..."} for your own LLM server. Retell LLM and conversation flow engines may also take a numeric version. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
agent_namestring- Name of the chat agent, for your own reference. Example: Website Chat Agent
auto_close_messagestring- Message shown when the chat is closed automatically. Example: This chat has been closed due to inactivity.
data_storage_settingstring- What Retell stores for this agent's chats: everything, everything_except_pii, or basic_attributes_only.one of
everythingeverything_except_piibasic_attributes_only end_chat_after_silence_msinteger- End the chat when the user stays silent this many milliseconds after the agent replies, from 120000 (2 minutes) to 259200000 (72 hours). Defaults to 3600000 (1 hour). Example: 3600000
languagestring- Locale the chat agent uses, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-USone of
en-USen-INen-GBen-AUen-NZde-DEes-ESes-419hi-INfr-FRfr-CAja-JPpt-PTpt-BRzh-CNru-RUit-ITko-KRnl-NLnl-BEpl-PLtr-TRvi-VNro-RObg-BGca-ESth-THda-DKfi-FIel-GRhu-HUid-IDno-NOsk-SKsv-SElt-LTlv-LVcs-CZms-MYaf-ZAar-SAaz-AZbs-BAcy-GBfa-IRfil-PHgl-EShe-ILhr-HRhy-AMis-ISkk-KZkn-INmk-MKmr-INne-NPsl-SIsr-RSsw-KEta-INur-INyue-CNuk-UA post_chat_analysis_dataarray- Extra data to extract from each chat after it ends. Each item has a type (string, enum, boolean or number), a name and a description; enum items also list choices. Example: [{"type": "string", "name": "order_id", "description": "The order ID the user mentions."}]
timezonestring- IANA timezone for the agent. Defaults to America/Los_Angeles. Example: America/New_York
webhook_urlstring- URL that receives this agent's chat event webhooks (chat_started, chat_ended, chat_analyzed by default). Example: https://example.com/retell/webhook
retell_create_chat_completionSend a user message to an ongoing Retell chat and get the agent's reply.WriteCreate Chat Completion
Send a user message to an ongoing Retell chat and get the agent's reply. Returns messages: the new messages generated in this turn, including agent replies and any tool call invocations and results. Use retell_create_chat_completion to continue a chat started with retell_create_chat. Use retell_agent_playground_completion to test an agent without creating a chat.
Inputs
chat_idstringrequired- ID of the ongoing chat, from retell_create_chat. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
contentstringrequired- The user's message text. Example: Hi, I'd like to reschedule my appointment.
retell_create_contactCreate a contact in Retell, identified by phone number, with optional name, do-not-call flag, memory, tags and custom fields.WriteCreate Contact
Create a contact in Retell, identified by phone number, with optional name, do-not-call flag, memory, tags and custom fields. Returns the contact object, including contact_id, phone_number, first_name, last_name, do_not_call, contact_memory, contact_tags, custom_fields, conversation_count and timestamps. Use retell_create_contact for a new phone number. Use retell_get_contact_by_phone first to check whether a contact already exists, and retell_update_contact to change one.
Inputs
phone_numberstringrequired- Contact's phone number, E.164 preferred. Only one contact can exist per phone number. Example: +14155551234
contact_memorystring- Free-text memory about the contact that agents can read during conversations. Example: Prefers afternoon calls. Has a premium plan.
contact_tag_idsarray- Full set of tag IDs for the contact, from the organization's contact tags. Example: ["0f1e2d3c4b5a69788796a5b4c3d2e1f0"]
custom_fieldsobject- Values for the organization's custom contact fields, keyed by field name; value types must match the field definitions. Example: {"account_tier": "premium"}
do_not_callboolean- Mark the contact as do-not-call. Calls and SMS chats that set honor_internal_dnc are then rejected for this number.
first_namestring- Contact's first name. Example: John
last_namestring- Contact's last name. Example: Smith
retell_create_conversation_flowCreate a Retell conversation flow response engine: a graph of nodes, edges and tools that steers an agent through a structured conversation.WriteCreate Conversation Flow
Create a Retell conversation flow response engine: a graph of nodes, edges and tools that steers an agent through a structured conversation. Returns the conversation flow object, including conversation_flow_id, version, model_choice, start_speaker, global_prompt, nodes, tools, components and knowledge_base_ids. Use retell_create_conversation_flow for node-based agents. Use retell_create_retell_llm for prompt-based agents. Attach it to an agent with response_engine {"type": "conversation-flow", "conversation_flow_id": ...} in retell_create_agent or retell_update_agent.
Inputs
model_choiceobjectrequired- Model that runs the flow. For a text model use {"type": "cascading", "model": "gpt-4.1"} (optionally with high_priority); for speech-to-speech use {"type": "s2s", "model": "gpt-realtime"}. Example: {"type": "cascading", "model": "gpt-4.1"}
nodesarrayrequired- Nodes of the flow. Each node has an id, a type and type-specific fields; types include conversation (with an instruction prompt or static text), function, code, transfer_call, press_digit, branch, sms, extract_dynamic_variables, agent_swap, mcp, component and end. Nodes link to each other through edges with a transition_condition and destination_node_id. Example: [{"id": "start", "type": "conversation", "instruction": {"type": "prompt", "text": "Greet the customer and ask how you can help."}}]
start_speakerstringrequired- Who speaks first in the conversation: user or agent. Example: agentone of
useragent begin_after_user_silence_msinteger- When the user speaks first, start talking after the user has been silent this many milliseconds. Omit to wait indefinitely. Example: 2000
default_dynamic_variablesobject- Default values for dynamic variables referenced in the flow, as string key-value pairs. Example: {"company_name": "Retell Inc", "support_hours": "9 AM - 5 PM"}
global_promptstring- Prompt applied in every node of the flow, such as the agent's role and tone. Example: You are a helpful customer service agent.
knowledge_base_idsarray- IDs of knowledge bases the flow can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"]
model_temperaturenumber- Randomness of responses, from 0 (deterministic) to 1 (more varied). Example: 0.7
start_node_idstring- ID of the node the conversation starts at. Example: start
toolsarray- Custom tools nodes can call. Each tool has a type (such as custom for an HTTP call), a name, a description and type-specific fields such as url and method. Example: [{"type": "custom", "name": "get_customer_info", "description": "Get customer information", "tool_id": "tool_001", "url": "https://api.example.com/customer", "method": "GET"}]
retell_create_conversation_flow_componentCreate a shared conversation flow component: a reusable group of nodes that several conversation flows can embed.WriteCreate Conversation Flow Component
Create a shared conversation flow component: a reusable group of nodes that several conversation flows can embed. Returns the component object, including conversation_flow_component_id, name, nodes, start_node_id, tools, mcps and linked_conversation_flow_ids. Use retell_create_conversation_flow_component for steps shared across flows. Use retell_create_conversation_flow for a complete flow.
Inputs
namestringrequired- Name of the component. Example: Customer Information Collector
nodesarrayrequired- Nodes that make up the component, in the same shape as conversation flow nodes (id, type and type-specific fields, linked by edges). Example: [{"id": "collect_info", "type": "conversation", "instruction": {"type": "prompt", "text": "Ask the customer for their name and contact information."}}]
start_node_idstring- ID of the node the component starts at. Example: collect_info
toolsarray- Custom tools available within the component. Each tool has a type (such as custom for an HTTP call), a name, a description and type-specific fields such as url and method. Example: [{"type": "custom", "name": "get_customer_info", "description": "Get customer information", "tool_id": "tool_001", "url": "https://api.example.com/customer", "method": "GET"}]
retell_create_phone_callPlace an outbound phone call from a Retell number to a destination number, handled by the agent bound to the from number or an override agent.WriteCreate Phone Call
Place an outbound phone call from a Retell number to a destination number, handled by the agent bound to the from number or an override agent. Returns the call object with call_id, call_status (registered at first), agent_id, from_number, to_number, direction and metadata. Use retell_create_phone_call for a single call. Use retell_create_batch_call to call many numbers, and retell_get_call to follow the call's progress. The from_number must be a number bought in or imported into Retell (see retell_list_phone_numbers) with an outbound agent, unless you pass override_agent_id.
Inputs
from_numberstringrequired- Number to call from, in E.164 format. Must be a number purchased from or imported to Retell. Example: +14157774444
to_numberstringrequired- Number to call, in E.164 format. Numbers purchased from Retell can call US destinations only. Example: +12137774445
agent_overrideobject- Per-call overrides for agent, Retell LLM or conversation flow settings, as an object with optional agent, retell_llm and conversation_flow keys holding the fields to change. Example: {"agent": {"voice_speed": 1.1}, "retell_llm": {"begin_message": "Hi, this is Acme calling."}}
custom_sip_headersobject- Custom SIP headers to add to the call. Example: {"X-Custom-Header": "Custom Value"}
honor_internal_dncboolean- Reject the call with 400 if the contact for to_number is marked do-not-call. Defaults to false.
idempotency_keystring- Key that makes retries safe: repeating the request with the same key within one hour does not place a second call. Use a new key for each new call. Example: 4f1c2a7e-order-1234
metadataobject- Arbitrary key-value data stored on the call for your own reference, such as your internal customer ID. Retell does not use it for processing and returns it on the call object. Max 50 kB. Example: {"customer_id": "cust_123"}
override_agent_idstring- Agent to use for this call only, instead of the number's outbound agent. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
override_agent_versioninteger- Version of the override agent to use, as a version number. Omit to use the latest version. Example: 3
retell_llm_dynamic_variablesobject- Dynamic variables as string key-value pairs, injected into the response engine prompt and tool descriptions wherever {{variable_name}} appears. Example: {"customer_name": "John Doe"}
retell_create_phone_numberBuy a new phone number through Retell (US or Canada, from Twilio or Telnyx) and optionally bind inbound and outbound agents to it.WriteBuy Phone Number
Buy a new phone number through Retell (US or Canada, from Twilio or Telnyx) and optionally bind inbound and outbound agents to it. This incurs a monthly charge. Returns the phone number object, including phone_number, phone_number_type, nickname, area_code, inbound_agents, outbound_agents, SMS agents, webhook URLs and allowed country lists. Use retell_create_phone_number to buy a number from Retell. Use retell_import_phone_number to bring a number from your own SIP trunk.
Inputs
allowed_inbound_country_listarray- ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"]
allowed_outbound_country_listarray- ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"]
area_codeinteger- Three-digit US area code to buy a number in. Example: 415
country_codestring- Country of the number: US or CA. Defaults to US.one of
USCA fallback_numberstring- Number in E.164 format to forward inbound calls to when concurrency is full and no slot frees up. Example: +14155550100
inbound_agentsarray- Agents that answer inbound calls bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
inbound_webhook_urlstring- URL Retell calls on each inbound call so you can override the agent or set dynamic variables. Example: https://example.com/inbound-webhook
nicknamestring- Nickname for the number, for your own reference. Example: Support line
number_providerstring- Telephony provider to buy from: twilio or telnyx. Defaults to twilio.one of
twiliotelnyx outbound_agentsarray- Agents that place outbound calls bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
phone_numberstring- Specific number to buy, in E.164 format, if you already know an available one. Example: +14157774444
toll_freeboolean- Buy a toll-free number instead of a local one. Toll-free numbers cost more. Defaults to false.
retell_create_retell_llmCreate a Retell LLM response engine: the model, prompt, opening message, tools and optional states that drive an agent's replies.WriteCreate Retell LLM
Create a Retell LLM response engine: the model, prompt, opening message, tools and optional states that drive an agent's replies. Returns the Retell LLM object, including llm_id, version, is_published, model, general_prompt, begin_message, general_tools, states and knowledge_base_ids. Use retell_create_retell_llm for prompt-based agents. Use retell_create_conversation_flow for node-based flows. Attach it to an agent with retell_create_agent or retell_update_agent using response_engine {"type": "retell-llm", "llm_id": ...}.
Inputs
start_speakerstringrequired- Who speaks first in the conversation: user or agent. The Retell docs mark it required when creating a Retell LLM. Example: agentone of
useragent begin_messagestring- First thing the agent says when it speaks first. Leave empty to let the LLM generate the opening. Example: Hi, thanks for calling Acme. How can I help?
default_dynamic_variablesobject- Default values for dynamic variables used in the prompt, as string key-value pairs; per-call values override them. Example: {"company_name": "Acme"}
general_promptstring- System prompt applied in every state of the conversation: the agent's role, tone and instructions. Example: You are a friendly receptionist for Acme Dental. Book, move or cancel appointments.
general_toolsarray- Tools the LLM can call in any state. Each tool has a type and a name; types include end_call, transfer_call, press_digit, send_sms, custom (calls your URL), code, extract_dynamic_variable, agent_swap, mcp and integration_app, each with its own extra fields. Example: [{"type": "end_call", "name": "end_call", "description": "End the call when the user says goodbye."}]
knowledge_base_idsarray- IDs of knowledge bases the LLM can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"]
modelstring- Text LLM that powers the agent, such as gpt-4.1, gpt-4.1-mini or gpt-5. See the Retell docs for the current list of supported models. Example: gpt-4.1
model_temperaturenumber- Randomness of responses, from 0 (deterministic) to 1 (more varied). Defaults to 0. Example: 0.2
s2s_modelstring- Speech-to-speech model to use instead of a text model, such as gpt-realtime. Set either model or s2s_model, not both. Example: gpt-realtime
starting_statestring- Name of the state the conversation starts in. Required when states is not empty. Example: greeting
statesarray- Optional conversation states. Each state has a unique name, a state_prompt appended to the general prompt, edges to other states and state-specific tools. Requires starting_state. Example: [{"name": "greeting", "state_prompt": "Greet the caller and ask how you can help."}]
retell_create_sms_chatStart an outbound SMS conversation from a Retell number to a phone number; the agent writes and sends the first message.WriteCreate SMS Chat
Start an outbound SMS conversation from a Retell number to a phone number; the agent writes and sends the first message. Returns the chat object, including chat_id, agent_id, chat_status, chat_type, transcript, messages with tool calls, metadata, chat_cost and chat_analysis. Use retell_create_sms_chat to reach someone by text. Use retell_create_chat for an in-app chat and retell_create_phone_call for a voice call. The from_number needs SMS capability and an outbound SMS chat agent (see retell_update_phone_number), unless you pass override_agent_id.
Inputs
from_numberstringrequired- Number to send from, in E.164 format. Must be a Retell number with SMS capability. Example: +12137771234
to_numberstringrequired- Number to text, in E.164 format. Example: +14155551234
honor_internal_dncboolean- Reject the chat with 400 if the contact for to_number is marked do-not-call. Defaults to false.
metadataobject- Arbitrary key-value data stored on the chat for your own reference, such as your internal customer ID. Retell does not use it for processing and returns it on the chat object. Max 50 kB. Example: {"customer_id": "cust_123"}
override_agent_idstring- Chat agent to use for this conversation only. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
override_agent_versioninteger- Version of the override agent to use, as a version number. Omit to use the latest version. Example: 3
retell_llm_dynamic_variablesobject- Dynamic variables as string key-value pairs, injected into the response engine prompt and tool descriptions wherever {{variable_name}} appears. Example: {"customer_name": "John Doe"}
retell_create_test_case_definitionCreate a test case that simulates a user conversation against a Retell LLM or conversation flow and checks it against your metrics.WriteCreate Test Case Definition
Create a test case that simulates a user conversation against a Retell LLM or conversation flow and checks it against your metrics. Returns the test case definition, including test_case_definition_id, name, response_engine, user_prompt, metrics, dynamic_variables, tool_mocks, llm_model and timestamps. Use retell_create_test_case_definition to define a scenario, then run it with retell_create_batch_test.
Inputs
metricsarrayrequired- Criteria the test is evaluated against, as plain-language statements. Example: ["The agent confirms the new appointment time."]
namestringrequired- Name of the test case. Example: Reschedule appointment
response_engineobjectrequired- Response engine the test runs against, as an object. For a Retell LLM use {"type": "retell-llm", "llm_id": "<llm_id>"}; for a conversation flow use {"type": "conversation-flow", "conversation_flow_id": "<id>"}. Either may add a numeric version. Custom LLMs are not supported. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
user_promptstringrequired- Instructions for the simulated user: who they are and what they want. Example: You are John Smith. You want to move your Tuesday appointment to Friday afternoon.
dynamic_variablesobject- Dynamic variables to inject into the response engine for this test, as string key-value pairs. Example: {"customer_name": "John Smith"}
llm_modelstring- LLM that simulates the user, such as gpt-4.1. See the Retell docs for supported models. Example: gpt-4.1
tool_mocksarray- Mocked tool results so the test does not call real tools. Each mock names the tool_name the LLM calls, an input_match_rule deciding which calls it applies to, and the output string returned. Example: [{"tool_name": "check_availability", "input_match_rule": {"type": "any"}, "output": "{\"available\": true}"}]
retell_end_chatEnd an ongoing Retell chat so no more messages can be added.WriteEnd Chat
End an ongoing Retell chat so no more messages can be added. Returns an empty response on success (HTTP 204). Use retell_end_chat to close a conversation. Use retell_delete_chat to remove a chat's data.
- Idempotent
Inputs
chat_idstringrequired- ID of the ongoing chat to end, from retell_create_chat or retell_list_chats. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_import_phone_numberImport a phone number from your own telephony provider through an elastic SIP trunk, and optionally bind inbound and outbound agents.WriteImport Phone Number
Import a phone number from your own telephony provider through an elastic SIP trunk, and optionally bind inbound and outbound agents. Returns the phone number object, including phone_number, phone_number_type, nickname, area_code, inbound_agents, outbound_agents, SMS agents, webhook URLs and allowed country lists. Use retell_import_phone_number for numbers you already own through an elastic SIP trunk (for example Twilio or Telnyx). Use retell_create_phone_number to buy a number from Retell.
Inputs
phone_numberstringrequired- Number to import, in E.164 format. Example: +14157774444
termination_uristringrequired- Termination URI of your elastic SIP trunk, used for outbound calls. For Twilio this ends in .pstn.twilio.com. Example: someuri.pstn.twilio.com
allowed_inbound_country_listarray- ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"]
allowed_outbound_country_listarray- ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"]
inbound_agentsarray- Agents that answer inbound calls bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
inbound_webhook_urlstring- URL Retell calls on each inbound call so you can override the agent or set dynamic variables. Example: https://example.com/inbound-webhook
nicknamestring- Nickname for the number, for your own reference. Example: Imported support line
outbound_agentsarray- Agents that place outbound calls bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
sip_trunk_auth_passwordstring- Password for SIP trunk authentication, if your trunk requires credentials.
sip_trunk_auth_usernamestring- Username for SIP trunk authentication, if your trunk requires credentials. Example: retell-trunk
transportstring- Outbound SIP transport protocol: TLS, TCP or UDP. Defaults to TCP.one of
TLSTCPUDP
retell_publish_agent_versionPublish an existing draft version of a Retell voice or chat agent in place, so it can be used in production.WritePublish Agent Version
Publish an existing draft version of a Retell voice or chat agent in place, so it can be used in production. Returns an empty response on success; the version then shows is_published true in retell_list_agent_versions. Use retell_publish_agent_version after editing a draft with retell_update_agent or retell_update_chat_agent.
- Idempotent
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
versionintegerrequired- Draft version number to publish, from retell_list_agent_versions. Example: 15
version_descriptionstring- Description of what changed in this version. Example: Hotfix for transfer timeout
version_titlestring- Short title for the published version, for your own reference. Example: Hotfix
retell_repair_agentClean up a Retell agent draft that points at deleted resources: removes tools whose app connection is gone, unknown knowledge bases and deleted shared components, and remaps inaccessible voices to a default voice.WriteRepair Agent
Clean up a Retell agent draft that points at deleted resources: removes tools whose app connection is gone, unknown knowledge bases and deleted shared components, and remaps inaccessible voices to a default voice. Returns the repaired agent object, including agent_id, version, response_engine and voice_id. Repairing an agent with nothing to fix changes nothing. Use retell_repair_agent when an agent fails because something it references was deleted. Published versions cannot be repaired.
- Idempotent
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
versioninteger- Draft version to repair. Omit for the latest version. Example: 3
retell_rerun_call_analysisRun post-call analysis again on a Retell call, using the agent's current analysis settings.WriteRerun Call Analysis
Run post-call analysis again on a Retell call, using the agent's current analysis settings. This incurs charges. Returns the call object with its refreshed call_analysis. Use retell_rerun_call_analysis after changing an agent's post_call_analysis_data. Use retell_get_call to read the existing analysis.
Inputs
call_idstringrequired- ID of the ended call to analyse again, from retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_rerun_chat_analysisRun post-chat analysis again on a Retell chat, using the agent's current analysis settings.WriteRerun Chat Analysis
Run post-chat analysis again on a Retell chat, using the agent's current analysis settings. This incurs charges. Returns the chat object with its refreshed chat_analysis. Use retell_rerun_chat_analysis after changing a chat agent's post_chat_analysis_data. Use retell_get_chat to read the existing analysis.
Inputs
chat_idstringrequired- ID of the chat to analyse again, from retell_list_chats. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_stop_callHang up an ongoing Retell call.WriteStop Call
Hang up an ongoing Retell call. Returns an empty response on success (HTTP 204). Use retell_stop_call to end a live call. Use retell_delete_call to remove an ended call's data.
Inputs
call_idstringrequired- ID of the ongoing call to stop, from retell_create_phone_call or retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_update_agentUpdate settings on a Retell voice agent's latest draft version; fields you leave out stay unchanged.WriteUpdate Agent
Update settings on a Retell voice agent's latest draft version; fields you leave out stay unchanged. Returns the agent object, including agent_id, version, is_published, response_engine, agent_name, voice_id, language and the voice, webhook and call settings. Use retell_update_agent to change voice, timing or webhook settings. Use retell_update_retell_llm or retell_update_conversation_flow to change the prompt. Changes apply to the draft; publish them with retell_publish_agent_version.
- Idempotent
Inputs
agent_idstringrequired- ID of the voice agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_namestring- Name of the agent, for your own reference. Example: Customer Support Agent
ambient_soundstring- Background sound mixed into the call to sound more natural: coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise or call-center. Leave empty for none.one of
coffee-shopconvention-hallsummer-outdoormountain-outdoorstatic-noisecall-center begin_message_delay_msinteger- Milliseconds to wait before the agent's first message, from 0 to 5000. Example: 1000
boosted_keywordsarray- Words the transcriber should favour, such as names and product terms. Example: ["Retell", "Kubernetes"]
data_storage_settingstring- What Retell stores for this agent's calls: everything, everything_except_pii, or basic_attributes_only (metadata only, no transcripts or recordings).one of
everythingeverything_except_piibasic_attributes_only enable_backchannelboolean- Whether the agent interjects short acknowledgements such as "yeah" or "uh-huh" while the user speaks. Defaults to false.
end_call_after_silence_msinteger- End the call when the user stays silent this many milliseconds after the agent speaks. Minimum 10000; defaults to 600000 (10 minutes). Example: 30000
interruption_sensitivitynumber- How easily the user can interrupt the agent, from 0 (cannot interrupt) to 1 (interrupts easily). Defaults to 1. Example: 0.7
languagestring- Locale the agent speaks and transcribes, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-USone of
en-USen-INen-GBen-AUen-NZde-DEes-ESes-419hi-INfr-FRfr-CAja-JPpt-PTpt-BRzh-CNru-RUit-ITko-KRnl-NLnl-BEpl-PLtr-TRvi-VNro-RObg-BGca-ESth-THda-DKfi-FIel-GRhu-HUid-IDno-NOsk-SKsv-SElt-LTlv-LVcs-CZms-MYaf-ZAar-SAaz-AZbs-BAcy-GBfa-IRfil-PHgl-EShe-ILhr-HRhy-AMis-ISkk-KZkn-INmk-MKmr-INne-NPsl-SIsr-RSsw-KEta-INur-INyue-CNuk-UA max_call_duration_msinteger- Maximum call length in milliseconds, from 60000 (1 minute) to 7200000 (2 hours). Defaults to 3600000 (1 hour). Example: 1800000
post_call_analysis_dataarray- Extra data to extract from each call after it ends. Each item has a type (string, enum, boolean or number), a name and a description; enum items also list choices. Example: [{"type": "string", "name": "order_id", "description": "The order ID the caller mentions."}]
response_engineobject- Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": "<llm_id>"} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_id": "<id>"} for a conversation flow, or {"type": "custom-llm", "llm_websocket_url": "wss://..."} for your own LLM server. Retell LLM and conversation flow engines may also take a numeric version. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
responsivenessnumber- How quickly the agent responds, from 0 (waits longer) to 1 (responds fastest). Defaults to 1. Example: 0.8
timezonestring- IANA timezone for the agent, used for time-aware prompts. Defaults to America/Los_Angeles. Example: America/New_York
versioninteger- Draft version to update. Omit for the latest version. Published versions cannot be changed. Example: 3
voice_idstring- ID of the voice the agent speaks with, from the `voice_id` field returned by retell_list_voices. Example: retell-Cimo
voice_modelstring- Voice model for the selected voice, when its provider offers several (for example eleven_flash_v2_5, eleven_multilingual_v2 or sonic-3). Leave empty to use the voice's default model.
voice_speednumber- Speech rate from 0.5 (slower) to 2 (faster). Defaults to 1. Example: 1.1
voice_temperaturenumber- Voice stability from 0 (more stable) to 2 (more varied). Defaults to 1. Example: 1
voicemail_optionobject- What to do when the call reaches voicemail in the first 3 minutes. The action is an object with a type: hangup, static_text (with text to speak), prompt (with text describing what to say) or bridge_transfer. Example: {"action": {"type": "static_text", "text": "Please call us back at 555-0100."}}
webhook_urlstring- URL that receives this agent's call event webhooks (call_started, call_ended, call_analyzed by default). Example: https://example.com/retell/webhook
retell_update_callUpdate the metadata, custom attributes or data storage setting of an ended Retell call.WriteUpdate Call
Update the metadata, custom attributes or data storage setting of an ended Retell call. Returns the call object, including call_id, call_type, call_status, agent_id, from_number, to_number, direction, metadata and dynamic variables. Use retell_update_call on ended calls. Use retell_update_live_call to change dynamic variables or metadata on a call that is still in progress.
- Idempotent
Inputs
call_idstringrequired- ID of the call, from the `call_id` field returned by retell_list_calls or retell_create_phone_call. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
custom_attributesobject- Custom attributes as key-value pairs (string, number or boolean values). Each key must match a custom attribute already defined for the organization in the Retell dashboard; unknown keys are ignored. Example: {"custom_attribute_1": "value1"}
data_storage_settingstring- Data storage setting for this call: everything, everything_except_pii or basic_attributes_only. It can only be made more restrictive, never less.one of
everythingeverything_except_piibasic_attributes_only metadataobject- Arbitrary key-value data stored on the call for your own reference, such as your internal customer ID. Retell does not use it for processing and returns it on the call object. Max 50 kB. Example: {"customer_id": "cust_123"}
retell_update_chatUpdate the metadata, dynamic variable overrides, custom attributes or data storage setting of a Retell chat.WriteUpdate Chat
Update the metadata, dynamic variable overrides, custom attributes or data storage setting of a Retell chat. Returns the chat object, including chat_id, agent_id, chat_status, metadata, custom_attributes and dynamic variables. Use retell_update_chat to tag or annotate a chat. Use retell_end_chat to close it.
- Idempotent
Inputs
chat_idstringrequired- ID of the chat, from the `chat_id` field returned by retell_list_chats or retell_create_chat. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
custom_attributesobject- Custom attributes as key-value pairs (string, number or boolean values). Each key must match a custom attribute already defined for the organization in the Retell dashboard; unknown keys are ignored. Example: {"custom_attribute_1": "value1"}
data_storage_settingstring- Data storage setting for this chat: everything or basic_attributes_only (metadata only). It can only be made more restrictive, never less.one of
everythingbasic_attributes_only metadataobject- Arbitrary key-value data stored on the chat for your own reference, such as your internal customer ID. Retell does not use it for processing and returns it on the chat object. Max 50 kB. Example: {"customer_id": "cust_123"}
override_dynamic_variablesobject- Dynamic variables to add or replace for the rest of the chat, as string key-value pairs; send only the ones that change. Example: {"additional_discount": "15%"}
retell_update_chat_agentUpdate settings on a Retell chat agent's latest draft version; fields you leave out stay unchanged.WriteUpdate Chat Agent
Update settings on a Retell chat agent's latest draft version; fields you leave out stay unchanged. Returns the chat agent object, including agent_id, version, is_published, response_engine, agent_name, language, webhook settings and post-chat analysis settings. Use retell_update_chat_agent for chat agents. Use retell_update_agent for voice agents. Changes apply to the draft; publish them with retell_publish_agent_version.
- Idempotent
Inputs
agent_idstringrequired- ID of the chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_namestring- Name of the chat agent, for your own reference. Example: Website Chat Agent
auto_close_messagestring- Message shown when the chat is closed automatically. Example: This chat has been closed due to inactivity.
data_storage_settingstring- What Retell stores for this agent's chats: everything, everything_except_pii, or basic_attributes_only.one of
everythingeverything_except_piibasic_attributes_only end_chat_after_silence_msinteger- End the chat when the user stays silent this many milliseconds after the agent replies, from 120000 (2 minutes) to 259200000 (72 hours). Defaults to 3600000 (1 hour). Example: 3600000
languagestring- Locale the chat agent uses, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-USone of
en-USen-INen-GBen-AUen-NZde-DEes-ESes-419hi-INfr-FRfr-CAja-JPpt-PTpt-BRzh-CNru-RUit-ITko-KRnl-NLnl-BEpl-PLtr-TRvi-VNro-RObg-BGca-ESth-THda-DKfi-FIel-GRhu-HUid-IDno-NOsk-SKsv-SElt-LTlv-LVcs-CZms-MYaf-ZAar-SAaz-AZbs-BAcy-GBfa-IRfil-PHgl-EShe-ILhr-HRhy-AMis-ISkk-KZkn-INmk-MKmr-INne-NPsl-SIsr-RSsw-KEta-INur-INyue-CNuk-UA post_chat_analysis_dataarray- Extra data to extract from each chat after it ends. Each item has a type (string, enum, boolean or number), a name and a description; enum items also list choices. Example: [{"type": "string", "name": "order_id", "description": "The order ID the user mentions."}]
response_engineobject- Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": "<llm_id>"} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_id": "<id>"} for a conversation flow, or {"type": "custom-llm", "llm_websocket_url": "wss://..."} for your own LLM server. Retell LLM and conversation flow engines may also take a numeric version. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
timezonestring- IANA timezone for the agent. Defaults to America/Los_Angeles. Example: America/New_York
versioninteger- Draft version to update. Omit for the latest version. Example: 3
webhook_urlstring- URL that receives this agent's chat event webhooks (chat_started, chat_ended, chat_analyzed by default). Example: https://example.com/retell/webhook
retell_update_contactUpdate a Retell contact's name, do-not-call flag, memory, tags or custom fields; fields you leave out stay unchanged.WriteUpdate Contact
Update a Retell contact's name, do-not-call flag, memory, tags or custom fields; fields you leave out stay unchanged. Returns the contact object, including contact_id, phone_number, first_name, last_name, do_not_call, contact_memory, contact_tags, custom_fields, conversation_count and timestamps. Use retell_update_contact to change an existing contact. contact_tag_ids replaces the full tag set.
- Idempotent
Inputs
contact_idstringrequired- ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0
contact_memorystring- New free-text memory about the contact, replacing the current text. Example: Asked to be called after 3pm.
contact_tag_idsarray- Full replacement set of tag IDs for the contact. Example: ["0f1e2d3c4b5a69788796a5b4c3d2e1f0"]
custom_fieldsobject- Custom contact field values to set, keyed by field name; value types must match the field definitions. Example: {"account_tier": "premium"}
do_not_callboolean- Mark or unmark the contact as do-not-call.
first_namestring- New first name. Example: John
last_namestring- New last name. Example: Smith
retell_update_conversation_flowUpdate a Retell conversation flow's model, nodes, tools, prompt or other settings; fields you leave out stay unchanged.WriteUpdate Conversation Flow
Update a Retell conversation flow's model, nodes, tools, prompt or other settings; fields you leave out stay unchanged. Returns the conversation flow object, including conversation_flow_id, version, model_choice, start_speaker, global_prompt, nodes, tools, components and knowledge_base_ids. Use retell_update_conversation_flow to change a flow-based agent's behaviour. Arrays such as nodes replace the stored value, so send the complete list from retell_get_conversation_flow.
- Idempotent
Inputs
conversation_flow_idstringrequired- ID of the conversation flow, from the `conversation_flow_id` field returned by retell_list_conversation_flows. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90
begin_after_user_silence_msinteger- When the user speaks first, start talking after the user has been silent this many milliseconds. Omit to wait indefinitely. Example: 2000
default_dynamic_variablesobject- Default values for dynamic variables referenced in the flow, as string key-value pairs. Example: {"company_name": "Retell Inc", "support_hours": "9 AM - 5 PM"}
global_promptstring- Prompt applied in every node of the flow, such as the agent's role and tone. Example: You are a helpful customer service agent.
knowledge_base_idsarray- IDs of knowledge bases the flow can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"]
model_choiceobject- Model that runs the flow. For a text model use {"type": "cascading", "model": "gpt-4.1"} (optionally with high_priority); for speech-to-speech use {"type": "s2s", "model": "gpt-realtime"}. Example: {"type": "cascading", "model": "gpt-4.1"}
model_temperaturenumber- Randomness of responses, from 0 (deterministic) to 1 (more varied). Example: 0.7
nodesarray- Nodes of the flow. Each node has an id, a type and type-specific fields; types include conversation (with an instruction prompt or static text), function, code, transfer_call, press_digit, branch, sms, extract_dynamic_variables, agent_swap, mcp, component and end. Nodes link to each other through edges with a transition_condition and destination_node_id. Example: [{"id": "start", "type": "conversation", "instruction": {"type": "prompt", "text": "Greet the customer and ask how you can help."}}]
start_node_idstring- ID of the node the conversation starts at. Example: start
start_speakerstring- Who speaks first in the conversation: user or agent. Example: agentone of
useragent toolsarray- Custom tools nodes can call. Each tool has a type (such as custom for an HTTP call), a name, a description and type-specific fields such as url and method. Example: [{"type": "custom", "name": "get_customer_info", "description": "Get customer information", "tool_id": "tool_001", "url": "https://api.example.com/customer", "method": "GET"}]
versioninteger- Version to update. Omit for the latest version. Example: 1
retell_update_conversation_flow_componentUpdate a shared Retell conversation flow component; fields you leave out stay unchanged and changes reach every flow linked to it.WriteUpdate Conversation Flow Component
Update a shared Retell conversation flow component; fields you leave out stay unchanged and changes reach every flow linked to it. Returns the component object, including conversation_flow_component_id, name, nodes, start_node_id, tools, mcps and linked_conversation_flow_ids. Use retell_update_conversation_flow_component to change shared steps once for all flows. Arrays such as nodes replace the stored value.
- Idempotent
Inputs
conversation_flow_component_idstringrequired- ID of the shared conversation flow component, from the `conversation_flow_component_id` field returned by retell_list_conversation_flow_components. Example: f0e1d2c3b4a5968778695a4b3c2d1e0f
namestring- Name of the component. Example: Customer Information Collector
nodesarray- Nodes that make up the component, in the same shape as conversation flow nodes (id, type and type-specific fields, linked by edges). Example: [{"id": "collect_info", "type": "conversation", "instruction": {"type": "prompt", "text": "Ask the customer for their name and contact information."}}]
start_node_idstring- ID of the node the component starts at. Example: collect_info
toolsarray- Custom tools available within the component. Each tool has a type (such as custom for an HTTP call), a name, a description and type-specific fields such as url and method. Example: [{"type": "custom", "name": "get_customer_info", "description": "Get customer information", "tool_id": "tool_001", "url": "https://api.example.com/customer", "method": "GET"}]
retell_update_live_callChange an in-progress Retell call: override its dynamic variables, metadata or data storage setting, inject extra context for the agent, or make it respond now.WriteUpdate Live Call
Change an in-progress Retell call: override its dynamic variables, metadata or data storage setting, inject extra context for the agent, or make it respond now. Returns success: true when the update is applied. Use retell_update_live_call on ongoing calls. Use retell_update_call for calls that have ended.
- Idempotent
Inputs
call_idstringrequired- ID of the ongoing call, from retell_create_phone_call or retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
call_controlobject- Live agent control: additional_context is text added to the transcript and to the agent's next response context; trigger_response true makes the agent respond now. Example: {"additional_context": "The customer's order shipped today.", "trigger_response": true}
fields_to_overrideobject- Call fields to change immediately: override_dynamic_variables (string key-value pairs to add or replace), metadata, and data_storage_setting. Example: {"override_dynamic_variables": {"additional_discount": "15%"}}
retell_update_phone_numberUpdate a Retell phone number's bound voice and SMS agents, nickname, webhooks, allowed countries or SIP trunk settings; fields you leave out stay unchanged.WriteUpdate Phone Number
Update a Retell phone number's bound voice and SMS agents, nickname, webhooks, allowed countries or SIP trunk settings; fields you leave out stay unchanged. Returns the phone number object, including phone_number, phone_number_type, nickname, area_code, inbound_agents, outbound_agents, SMS agents, webhook URLs and allowed country lists. Use retell_update_phone_number to change which agent handles a number's calls or texts.
- Idempotent
Inputs
phone_numberstringrequired- The phone number in E.164 format (+ country code, then the number with no spaces or symbols), as returned by retell_list_phone_numbers. Example: +14157774444
allowed_inbound_country_listarray- ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"]
allowed_outbound_country_listarray- ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"]
auth_passwordstring- New SIP trunk authentication password, for imported numbers.
auth_usernamestring- New SIP trunk authentication username, for imported numbers. Example: retell-trunk
fallback_numberstring- Number in E.164 format to forward inbound calls to when concurrency is full. Example: +14155550100
inbound_agentsarray- Agents that answer inbound calls bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
inbound_sms_agentsarray- Chat agents that answer inbound SMS bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
inbound_sms_webhook_urlstring- URL Retell calls on each inbound SMS so you can override the agent or set dynamic variables. Example: https://example.com/inbound-sms-webhook
inbound_webhook_urlstring- URL Retell calls on each inbound call so you can override the agent or set dynamic variables. Example: https://example.com/inbound-webhook
nicknamestring- Nickname for the number, for your own reference. Example: Support line
outbound_agentsarray- Agents that place outbound calls bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
outbound_sms_agentsarray- Chat agents that send outbound SMS bound to this number, each with an agent_id and a weight (weights must add up to 1); one agent is picked at random by weight for each conversation. Each entry may also pin an agent_version. Pass an empty array to unbind. Example: [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "weight": 1}]
termination_uristring- New SIP trunk termination URI, for imported numbers. Example: someuri.pstn.twilio.com
transportstring- Outbound SIP transport protocol: TLS, TCP or UDP.one of
TLSTCPUDP
retell_update_retell_llmUpdate a Retell LLM response engine's model, prompt, opening message, tools or states; fields you leave out stay unchanged.WriteUpdate Retell LLM
Update a Retell LLM response engine's model, prompt, opening message, tools or states; fields you leave out stay unchanged. Returns the Retell LLM object, including llm_id, version, is_published, model, general_prompt, begin_message, general_tools, states and knowledge_base_ids. Use retell_update_retell_llm to change what an agent says. Use retell_update_agent to change its voice and call settings.
- Idempotent
Inputs
llm_idstringrequired- ID of the Retell LLM response engine, from the `llm_id` field returned by retell_list_retell_llms. Example: llm_234sdertfsdsfsdf
begin_messagestring- First thing the agent says when it speaks first. Leave empty to let the LLM generate the opening. Example: Hi, thanks for calling Acme. How can I help?
default_dynamic_variablesobject- Default values for dynamic variables used in the prompt, as string key-value pairs; per-call values override them. Example: {"company_name": "Acme"}
general_promptstring- System prompt applied in every state of the conversation: the agent's role, tone and instructions. Example: You are a friendly receptionist for Acme Dental. Book, move or cancel appointments.
general_toolsarray- Tools the LLM can call in any state. Each tool has a type and a name; types include end_call, transfer_call, press_digit, send_sms, custom (calls your URL), code, extract_dynamic_variable, agent_swap, mcp and integration_app, each with its own extra fields. Example: [{"type": "end_call", "name": "end_call", "description": "End the call when the user says goodbye."}]
knowledge_base_idsarray- IDs of knowledge bases the LLM can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"]
modelstring- Text LLM that powers the agent, such as gpt-4.1, gpt-4.1-mini or gpt-5. See the Retell docs for the current list of supported models. Example: gpt-4.1
model_temperaturenumber- Randomness of responses, from 0 (deterministic) to 1 (more varied). Defaults to 0. Example: 0.2
s2s_modelstring- Speech-to-speech model to use instead of a text model, such as gpt-realtime. Set either model or s2s_model, not both. Example: gpt-realtime
start_speakerstring- Who speaks first in the conversation: user or agent. The Retell docs mark it required when creating a Retell LLM. Example: agentone of
useragent starting_statestring- Name of the state the conversation starts in. Required when states is not empty. Example: greeting
statesarray- Optional conversation states. Each state has a unique name, a state_prompt appended to the general prompt, edges to other states and state-specific tools. Requires starting_state. Example: [{"name": "greeting", "state_prompt": "Greet the caller and ask how you can help."}]
versioninteger- Version to update. Omit for the latest version. Example: 1
retell_update_test_case_definitionUpdate a Retell test case definition's name, response engine, simulated user prompt, metrics, variables, tool mocks or model.WriteUpdate Test Case Definition
Update a Retell test case definition's name, response engine, simulated user prompt, metrics, variables, tool mocks or model. Returns the test case definition, including test_case_definition_id, name, response_engine, user_prompt, metrics, dynamic_variables, tool_mocks, llm_model and timestamps. Use retell_update_test_case_definition to change a scenario before rerunning it with retell_create_batch_test.
- Idempotent
Inputs
test_case_definition_idstringrequired- ID of the test case definition to update, from the `test_case_definition_id` field returned by retell_list_test_case_definitions. Example: 1a2b3c4d5e6f708192a3b4c5d6e7f809
dynamic_variablesobject- Dynamic variables to inject into the response engine for this test, as string key-value pairs. Example: {"customer_name": "John Smith"}
llm_modelstring- LLM that simulates the user, such as gpt-4.1. See the Retell docs for supported models. Example: gpt-4.1
metricsarray- Criteria the test is evaluated against, as plain-language statements. Example: ["The agent confirms the new appointment time."]
namestring- Name of the test case. Example: Reschedule appointment
response_engineobject- Response engine the test runs against, as an object. For a Retell LLM use {"type": "retell-llm", "llm_id": "<llm_id>"}; for a conversation flow use {"type": "conversation-flow", "conversation_flow_id": "<id>"}. Either may add a numeric version. Custom LLMs are not supported. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"}
tool_mocksarray- Mocked tool results so the test does not call real tools. Each mock names the tool_name the LLM calls, an input_match_rule deciding which calls it applies to, and the output string returned. Example: [{"tool_name": "check_availability", "input_match_rule": {"type": "any"}, "output": "{\"available\": true}"}]
user_promptstring- Instructions for the simulated user: who they are and what they want. Example: You are John Smith. You want to move your Tuesday appointment to Friday afternoon.
retell_delete_agentPermanently delete a Retell voice agent and all of its versions.DestructiveDelete Agent
Permanently delete a Retell voice agent and all of its versions. Returns an empty response on success (HTTP 204). Use retell_delete_agent for voice agents. Use retell_delete_chat_agent for chat agents and retell_delete_agent_version to remove one version.
- Idempotent
Inputs
agent_idstringrequired- ID of the voice agent to delete, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
retell_delete_agent_versionDelete one version of a Retell voice or chat agent.DestructiveDelete Agent Version
Delete one version of a Retell voice or chat agent. Returns an empty response on success (HTTP 204). Use retell_delete_agent_version to remove a single version. Use retell_delete_agent or retell_delete_chat_agent to delete the whole agent.
- Idempotent
Inputs
agent_idstringrequired- ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
versionintegerrequired- Version number to delete, from retell_list_agent_versions. Example: 4
retell_delete_callPermanently delete a Retell call and its associated data, including transcript and recording.DestructiveDelete Call
Permanently delete a Retell call and its associated data, including transcript and recording. Returns an empty response on success (HTTP 204). Use retell_delete_call to remove call history. Use retell_stop_call to end a call that is still in progress.
- Idempotent
Inputs
call_idstringrequired- ID of the call to delete, from retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_delete_chatPermanently delete a Retell chat and its messages.DestructiveDelete Chat
Permanently delete a Retell chat and its messages. Returns an empty response on success (HTTP 204). Use retell_delete_chat to remove chat history. Use retell_end_chat to close a chat without deleting it.
- Idempotent
Inputs
chat_idstringrequired- ID of the chat to delete, from retell_list_chats. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
retell_delete_chat_agentPermanently delete a Retell chat agent and all of its versions.DestructiveDelete Chat Agent
Permanently delete a Retell chat agent and all of its versions. Returns an empty response on success (HTTP 204). Use retell_delete_chat_agent for chat agents. Use retell_delete_agent for voice agents.
- Idempotent
Inputs
agent_idstringrequired- ID of the chat agent to delete, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
retell_delete_contactDelete a Retell contact.DestructiveDelete Contact
Delete a Retell contact. A contact linked to a record in a connected CRM cannot be deleted while two-way sync is active. Returns an empty response on success (HTTP 204). Use retell_delete_contact to remove a contact. Use retell_update_contact with do_not_call to stop contacting someone without deleting them.
- Idempotent
Inputs
contact_idstringrequired- ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0
retell_delete_conversation_flowPermanently delete a Retell conversation flow and all of its versions.DestructiveDelete Conversation Flow
Permanently delete a Retell conversation flow and all of its versions. Returns an empty response on success (HTTP 204). Use retell_delete_conversation_flow to remove an unused flow. The request is rejected while an agent still uses it unless force_delete is true.
- Idempotent
Inputs
conversation_flow_idstringrequired- ID of the conversation flow, from the `conversation_flow_id` field returned by retell_list_conversation_flows. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90
force_deleteboolean- Delete even if an agent still uses this conversation flow as its response engine. By default the request is rejected with 400 in that case. Defaults to false.
retell_delete_conversation_flow_componentDelete a shared Retell conversation flow component; each linked flow keeps a local copy of it.DestructiveDelete Conversation Flow Component
Delete a shared Retell conversation flow component; each linked flow keeps a local copy of it. Returns an empty response on success (HTTP 204). Use retell_delete_conversation_flow_component to stop sharing a component without breaking the flows that use it.
- Idempotent
Inputs
conversation_flow_component_idstringrequired- ID of the shared conversation flow component, from the `conversation_flow_component_id` field returned by retell_list_conversation_flow_components. Example: f0e1d2c3b4a5968778695a4b3c2d1e0f
retell_delete_knowledge_basePermanently delete a Retell knowledge base and all of its sources.DestructiveDelete Knowledge Base
Permanently delete a Retell knowledge base and all of its sources. Returns an empty response on success (HTTP 204). Use retell_delete_knowledge_base to remove the whole knowledge base. Use retell_delete_knowledge_base_source to remove one source.
- Idempotent
Inputs
knowledge_base_idstringrequired- ID of the knowledge base to delete, from retell_list_knowledge_bases. Example: knowledge_base_a456426614174000
retell_delete_knowledge_base_sourceRemove one source (a file, URL or text) from a Retell knowledge base.DestructiveDelete Knowledge Base Source
Remove one source (a file, URL or text) from a Retell knowledge base. Returns the knowledge base object, including knowledge_base_id, knowledge_base_name, status, chunk sizes, knowledge_base_sources and auto-refresh settings. Use retell_delete_knowledge_base_source to drop one source. Use retell_delete_knowledge_base to delete the whole knowledge base. Get the source_id from the knowledge_base_sources list returned by retell_get_knowledge_base.
- Idempotent
Inputs
knowledge_base_idstringrequired- ID of the knowledge base the source belongs to, from retell_list_knowledge_bases. Example: knowledge_base_a456426614174000
source_idstringrequired- ID of the source to remove, from the source_id field in knowledge_base_sources returned by retell_get_knowledge_base. Example: 5c1e9a2b7d3f
retell_delete_phone_numberRemove a phone number from the Retell workspace; a number bought through Retell is released.DestructiveDelete Phone Number
Remove a phone number from the Retell workspace; a number bought through Retell is released. Returns an empty response on success (HTTP 204). Use retell_delete_phone_number to stop paying for or using a number. Use retell_update_phone_number to only unbind its agents.
- Idempotent
Inputs
phone_numberstringrequired- The phone number to delete, in E.164 format, as returned by retell_list_phone_numbers. Example: +14157774444
retell_delete_retell_llmPermanently delete a Retell LLM response engine and all of its versions.DestructiveDelete Retell LLM
Permanently delete a Retell LLM response engine and all of its versions. Returns an empty response on success (HTTP 204). Use retell_delete_retell_llm to remove an unused engine. The request is rejected while an agent still uses it unless force_delete is true.
- Idempotent
Inputs
llm_idstringrequired- ID of the Retell LLM response engine, from the `llm_id` field returned by retell_list_retell_llms. Example: llm_234sdertfsdsfsdf
force_deleteboolean- Delete even if an agent still uses this Retell LLM as its response engine. By default the request is rejected with 400 in that case. Defaults to false.
retell_delete_test_case_definitionDelete a Retell test case definition.DestructiveDelete Test Case Definition
Delete a Retell test case definition. Returns an empty response on success (HTTP 204). Use retell_delete_test_case_definition to remove a scenario you no longer run.
- Idempotent
Inputs
test_case_definition_idstringrequired- ID of the test case definition to delete, from the `test_case_definition_id` field returned by retell_list_test_case_definitions. Example: 1a2b3c4d5e6f708192a3b4c5d6e7f809
No tools match.
