> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Retell AI 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. **Authentication:** Bearer Token **Categories:** AI, Communication **Tools:** 83: 36 read, 34 write, 13 destructive **Users sign in with:** Access token **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=RETELL) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Retell AI connection In **AgentKit > Connections**, create a Retell AI connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript 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.actions const connector = 'retell' const identifier = 'user_123' // Generate an authorization link for the user const { 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 call const result = await actions.executeTool({ connector, identifier, toolName: 'retell_get_api_key_info', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_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.actions connection_name = "retell" identifier = "user_123" # Generate an authorization link for the user link_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 call result = actions.execute_tool( tool_input={}, tool_name="retell_get_api_key_info", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user opens the link once and enters their Retell AI credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'retell_agent_playground_completion', toolInput: { agent_id: '', messages: [{ role: 'user', content: 'Hi, I\'d like to check my appointment.', }], }, connector: 'retell', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="retell_agent_playground_completion", tool_input={ "agent_id": "", "messages": [{ "role": "user", "content": "Hi, I'd like to check my appointment.", }], }, connection_name="retell", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `retell_agent_playground_completion` Agent Playground Completion · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `messages` (`array`, required): 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_id` (`string`, optional): Conversation flow component ID, required when current_node_id is a node inside a component. Example: component_xyz789 - `current_node_id` (`string`, optional): For conversation flow agents, the node to resume from. Example: start-node-abc123 - `current_state` (`string`, optional): For Retell LLM agents, the state to resume from. Example: greeting - `dynamic_variables` (`object`, optional): Dynamic variables to substitute into the prompt, as string key-value pairs. Example: {"customer_name": "John Smith"} - `tool_mocks` (`array`, optional): 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}"}] - `version` (`integer`, optional): Agent version to use. Omit for the latest version. Example: 2 Example input: `{"agent_id":"","messages":[{"role":"user","content":"Hi, I'd like to check my appointment."}]}` ### `retell_get_agent` Get Agent · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `version` (`integer`, optional): Agent version to retrieve. Omit for the latest version. Example: 2 Example input: `{"agent_id":""}` ### `retell_get_api_key_info` Get API Key Info · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `retell_get_batch_test` Get Batch Test · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `test_case_batch_job_id` (`string`, required): 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 Example input: `{"test_case_batch_job_id":""}` ### `retell_get_call` Get Call · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `call_id` (`string`, required): ID of the call, from the `call_id` field returned by retell_list_calls or retell_create_phone_call. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"call_id":""}` ### `retell_get_chat` Get Chat · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `chat_id` (`string`, required): ID of the chat, from the `chat_id` field returned by retell_list_chats or retell_create_chat. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"chat_id":""}` ### `retell_get_chat_agent` Get Chat Agent · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `version` (`integer`, optional): Agent version to retrieve. Omit for the latest version. Example: 2 Example input: `{"agent_id":""}` ### `retell_get_concurrency` Get Concurrency · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `retell_get_contact` Get Contact · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `contact_id` (`string`, required): ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0 Example input: `{"contact_id":""}` ### `retell_get_contact_by_phone` Get Contact by Phone · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `phone_number` (`string`, required): Phone number to look up, E.164 preferred; other formats are normalized and an unparseable number returns 400. Example: +14155551234 Example input: `{"phone_number":""}` ### `retell_get_conversation_flow` Get Conversation Flow · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `conversation_flow_id` (`string`, required): ID of the conversation flow, from the `conversation_flow_id` field returned by retell_list_conversation_flows. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90 - `version` (`integer`, optional): Version to retrieve. Omit for the latest version. Example: 1 Example input: `{"conversation_flow_id":""}` ### `retell_get_conversation_flow_component` Get Conversation Flow Component · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `conversation_flow_component_id` (`string`, required): ID of the shared conversation flow component, from the `conversation_flow_component_id` field returned by retell_list_conversation_flow_components. Example: f0e1d2c3b4a5968778695a4b3c2d1e0f Example input: `{"conversation_flow_component_id":""}` ### `retell_get_knowledge_base` Get Knowledge Base · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `knowledge_base_id` (`string`, required): ID of the knowledge base, from the `knowledge_base_id` field returned by retell_list_knowledge_bases. Example: knowledge_base_a456426614174000 Example input: `{"knowledge_base_id":""}` ### `retell_get_mcp_tools` Get MCP Tools · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `mcp_id` (`string`, required): ID of the MCP server configured on the agent's response engine (in its mcps list). Example: mcp_crm_server - `component_id` (`string`, optional): ID of the conversation flow component, when the MCP server is configured inside a component. Example: component_xyz789 - `version` (`integer`, optional): Agent version to use. Omit for the latest version. Example: 2 Example input: `{"agent_id":"","mcp_id":""}` ### `retell_get_phone_number` Get Phone Number · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `phone_number` (`string`, required): 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 Example input: `{"phone_number":""}` ### `retell_get_retell_llm` Get Retell LLM · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `llm_id` (`string`, required): ID of the Retell LLM response engine, from the `llm_id` field returned by retell_list_retell_llms. Example: llm_234sdertfsdsfsdf - `version` (`integer`, optional): Version to retrieve. Omit for the latest version. Example: 1 Example input: `{"llm_id":""}` ### `retell_get_test_case_definition` Get Test Case Definition · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `test_case_definition_id` (`string`, required): ID of the test case definition to retrieve, from the `test_case_definition_id` field returned by retell_list_test_case_definitions. Example: 1a2b3c4d5e6f708192a3b4c5d6e7f809 Example input: `{"test_case_definition_id":""}` ### `retell_get_test_run` Get Test Run · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `test_case_job_id` (`string`, required): ID of the test run, from the `test_case_job_id` field returned by retell_list_test_runs. Example: 3c2b1a0f9e8d7c6b5a49382716f5e4d3 Example input: `{"test_case_job_id":""}` ### `retell_get_voice` Get Voice · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `voice_id` (`string`, required): ID of the voice, from retell_list_voices. Example: retell-Cimo Example input: `{"voice_id":""}` ### `retell_list_agent_versions` List Agent Versions · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{"agent_id":""}` ### `retell_list_agents` List Agents · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `filter_criteria` (`object`, optional): 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"}} - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_batch_tests` List Batch Tests · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `type` (`string`, required): 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-llm`, `conversation-flow`. - `conversation_flow_id` (`string`, optional): Conversation flow ID, required when type is conversation-flow. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90 - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `llm_id` (`string`, optional): Retell LLM ID, required when type is retell-llm. Example: llm_234sdertfsdsfsdf - `pagination_key` (`string`, optional): 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. - `version` (`integer`, optional): Response engine version the tests ran against. Omit for the latest version. Example: 2 Example input: `{"type":"retell-llm"}` ### `retell_list_calls` List Calls · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `filter_criteria` (`object`, optional): 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": } or {"type": "range", "op": "bt", "value": [from, to]}. Example: {"agent": [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"}], "call_status": {"type": "enum", "op": "in", "value": ["ended"]}} - `include_total` (`boolean`, optional): Also return total, the number of calls matching the filters. Adds an extra query, so request it only when needed. Defaults to false. - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort calls by start_timestamp: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_chats` List Chats · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `filter_criteria` (`object`, optional): 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": } or a {"type": "range", "op": "bt"} pair. Example: {"agent": [{"agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"}]} - `include_total` (`boolean`, optional): Also return total, the number of chats matching the filters. Adds an extra query, so request it only when needed. Defaults to false. - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort chats by start_timestamp: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_contact_conversations` List Contact Conversations · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `contact_id` (`string`, required): ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0 - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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. Example input: `{"contact_id":""}` ### `retell_list_contacts` List Contacts · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `excluded_contact_ids` (`array`, optional): Contact IDs to leave out of the results and the total. Example: ["9f8e7d6c5b4a39281706f5e4d3c2b1a0"] - `filter_criteria` (`object`, optional): 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}} - `limit` (`integer`, optional): Maximum number of contacts to return, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_query` (`string`, optional): 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_order` (`string`, optional): Sort by created time: asc or desc. Defaults to desc (newest first). One of: `asc`, `desc`. Example input: `{}` ### `retell_list_conversation_flow_components` List Conversation Flow Components · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_conversation_flows` List Conversation Flows · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_export_requests` List Export Requests · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_knowledge_bases` List Knowledge Bases · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `retell_list_phone_numbers` List Phone Numbers · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_retell_llms` List Retell LLMs · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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_order` (`string`, optional): Sort order for results: ascending or descending. Defaults to descending. One of: `ascending`, `descending`. Example input: `{}` ### `retell_list_test_case_definitions` List Test Case Definitions · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `type` (`string`, required): 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-llm`, `conversation-flow`. - `conversation_flow_id` (`string`, optional): Conversation flow ID, required when type is conversation-flow. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90 - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `llm_id` (`string`, optional): Retell LLM ID, required when type is retell-llm. Example: llm_234sdertfsdsfsdf - `pagination_key` (`string`, optional): 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. Example input: `{"type":"retell-llm"}` ### `retell_list_test_runs` List Test Runs · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `test_case_batch_job_id` (`string`, required): 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 - `limit` (`integer`, optional): Maximum number of items to return per page, from 1 to 1000. Defaults to 50. Example: 20 - `pagination_key` (`string`, optional): 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. Example input: `{"test_case_batch_job_id":""}` ### `retell_list_voices` List Voices · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `retell_search_community_voice` Search Community Voices · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `search_query` (`string`, required): Text to search for in voice names, descriptions or IDs. Example: warm british female - `voice_provider` (`string`, optional): Provider to search: elevenlabs, cartesia, minimax, fish_audio or inworld. Example: elevenlabs. One of: `elevenlabs`, `cartesia`, `minimax`, `fish_audio`, `inworld`. Example input: `{"search_query":""}` ### `retell_add_community_voice` Add Community Voice · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `provider_voice_id` (`string`, required): Voice ID assigned by the provider, from retell_search_community_voice. Example: 21m00Tcm4TlvDq8ikWAM - `voice_name` (`string`, required): Name to give the voice in your library. Example: Support Voice - `public_user_id` (`string`, optional): User ID of the voice owner. Required for ElevenLabs voices only. Example: 63e06b7e7cafdc46be4d2e0b - `voice_provider` (`string`, optional): Provider the voice comes from: elevenlabs, cartesia, minimax, fish_audio or inworld. Example: elevenlabs. One of: `elevenlabs`, `cartesia`, `minimax`, `fish_audio`, `inworld`. Example input: `{"provider_voice_id":"","voice_name":""}` ### `retell_create_agent` Create Agent · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `response_engine` (`object`, required): Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": ""} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_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_id` (`string`, required): ID of the voice the agent speaks with, from the `voice_id` field returned by retell_list_voices. Example: retell-Cimo - `agent_name` (`string`, optional): Name of the agent, for your own reference. Example: Customer Support Agent - `ambient_sound` (`string`, optional): 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-shop`, `convention-hall`, `summer-outdoor`, `mountain-outdoor`, `static-noise`, `call-center`. - `begin_message_delay_ms` (`integer`, optional): Milliseconds to wait before the agent's first message, from 0 to 5000. Example: 1000 - `boosted_keywords` (`array`, optional): Words the transcriber should favour, such as names and product terms. Example: ["Retell", "Kubernetes"] - `data_storage_setting` (`string`, optional): What Retell stores for this agent's calls: everything, everything_except_pii, or basic_attributes_only (metadata only, no transcripts or recordings). One of: `everything`, `everything_except_pii`, `basic_attributes_only`. - `enable_backchannel` (`boolean`, optional): Whether the agent interjects short acknowledgements such as "yeah" or "uh-huh" while the user speaks. Defaults to false. - `end_call_after_silence_ms` (`integer`, optional): 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_sensitivity` (`number`, optional): How easily the user can interrupt the agent, from 0 (cannot interrupt) to 1 (interrupts easily). Defaults to 1. Example: 0.7 - `language` (`string`, optional): Locale the agent speaks and transcribes, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-US. One of: `en-US`, `en-IN`, `en-GB`, `en-AU`, `en-NZ`, `de-DE`, `es-ES`, `es-419`, `hi-IN`, `fr-FR`, `fr-CA`, `ja-JP`, `pt-PT`, `pt-BR`, `zh-CN`, `ru-RU`, `it-IT`, `ko-KR`, `nl-NL`, `nl-BE`, `pl-PL`, `tr-TR`, `vi-VN`, `ro-RO`, `bg-BG`, `ca-ES`, `th-TH`, `da-DK`, `fi-FI`, `el-GR`, `hu-HU`, `id-ID`, `no-NO`, `sk-SK`, `sv-SE`, `lt-LT`, `lv-LV`, `cs-CZ`, `ms-MY`, `af-ZA`, `ar-SA`, `az-AZ`, `bs-BA`, `cy-GB`, `fa-IR`, `fil-PH`, `gl-ES`, `he-IL`, `hr-HR`, `hy-AM`, `is-IS`, `kk-KZ`, `kn-IN`, `mk-MK`, `mr-IN`, `ne-NP`, `sl-SI`, `sr-RS`, `sw-KE`, `ta-IN`, `ur-IN`, `yue-CN`, `uk-UA`. - `max_call_duration_ms` (`integer`, optional): Maximum call length in milliseconds, from 60000 (1 minute) to 7200000 (2 hours). Defaults to 3600000 (1 hour). Example: 1800000 - `post_call_analysis_data` (`array`, optional): 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."}] - `responsiveness` (`number`, optional): How quickly the agent responds, from 0 (waits longer) to 1 (responds fastest). Defaults to 1. Example: 0.8 - `timezone` (`string`, optional): IANA timezone for the agent, used for time-aware prompts. Defaults to America/Los_Angeles. Example: America/New_York - `voice_model` (`string`, optional): 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_speed` (`number`, optional): Speech rate from 0.5 (slower) to 2 (faster). Defaults to 1. Example: 1.1 - `voice_temperature` (`number`, optional): Voice stability from 0 (more stable) to 2 (more varied). Defaults to 1. Example: 1 - `voicemail_option` (`object`, optional): 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_url` (`string`, optional): URL that receives this agent's call event webhooks (call_started, call_ended, call_analyzed by default). Example: https://example.com/retell/webhook Example input: `{"response_engine":{"type":"retell-llm","llm_id":"llm_234sdertfsdsfsdf"},"voice_id":""}` ### `retell_create_agent_version` Create Agent Version · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `base_version` (`integer`, required): Existing version to copy into the new draft, from retell_list_agent_versions. Example: 12 Example input: `{"agent_id":"","base_version":12}` ### `retell_create_batch_call` Create Batch Call · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `from_number` (`string`, required): Number to call from, in E.164 format. Must be a number purchased from or imported to Retell. Example: +14157774444 - `tasks` (`array`, required): 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_window` (`object`, optional): 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"} - `name` (`string`, optional): Name of the batch, for your own reference. Example: March renewal reminders - `reserved_concurrency` (`integer`, optional): Concurrent call slots to keep free for other calls, such as inbound calls, while the batch runs. Example: 2 - `trigger_timestamp` (`number`, optional): When to start the batch, as a Unix timestamp in milliseconds. Omit to start immediately. Example: 1735718400000 Example input: `{"from_number":"","tasks":[{"to_number":"+12137774445","retell_llm_dynamic_variables":{"customer_name":"John Doe"}}]}` ### `retell_create_batch_test` Create Batch Test · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `response_engine` (`object`, required): Response engine the test runs against, as an object. For a Retell LLM use {"type": "retell-llm", "llm_id": ""}; for a conversation flow use {"type": "conversation-flow", "conversation_flow_id": ""}. Either may add a numeric version. Custom LLMs are not supported. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"} - `test_case_definition_ids` (`array`, required): IDs of the test case definitions to run, from retell_list_test_case_definitions. Example: ["1a2b3c4d5e6f708192a3b4c5d6e7f809"] Example input: `{"response_engine":{"type":"retell-llm","llm_id":"llm_234sdertfsdsfsdf"},"test_case_definition_ids":["1a2b3c4d5e6f708192a3b4c5d6e7f809"]}` ### `retell_create_chat` Create Chat · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `agent_id` (`string`, required): ID of the chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `agent_version` (`integer`, optional): Agent version to use, as a version number. Omit to use the latest version. Example: 3 - `metadata` (`object`, optional): 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_variables` (`object`, optional): 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"} Example input: `{"agent_id":""}` ### `retell_create_chat_agent` Create Chat Agent · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `response_engine` (`object`, required): Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": ""} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_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_name` (`string`, optional): Name of the chat agent, for your own reference. Example: Website Chat Agent - `auto_close_message` (`string`, optional): Message shown when the chat is closed automatically. Example: This chat has been closed due to inactivity. - `data_storage_setting` (`string`, optional): What Retell stores for this agent's chats: everything, everything_except_pii, or basic_attributes_only. One of: `everything`, `everything_except_pii`, `basic_attributes_only`. - `end_chat_after_silence_ms` (`integer`, optional): 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 - `language` (`string`, optional): Locale the chat agent uses, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-US. One of: `en-US`, `en-IN`, `en-GB`, `en-AU`, `en-NZ`, `de-DE`, `es-ES`, `es-419`, `hi-IN`, `fr-FR`, `fr-CA`, `ja-JP`, `pt-PT`, `pt-BR`, `zh-CN`, `ru-RU`, `it-IT`, `ko-KR`, `nl-NL`, `nl-BE`, `pl-PL`, `tr-TR`, `vi-VN`, `ro-RO`, `bg-BG`, `ca-ES`, `th-TH`, `da-DK`, `fi-FI`, `el-GR`, `hu-HU`, `id-ID`, `no-NO`, `sk-SK`, `sv-SE`, `lt-LT`, `lv-LV`, `cs-CZ`, `ms-MY`, `af-ZA`, `ar-SA`, `az-AZ`, `bs-BA`, `cy-GB`, `fa-IR`, `fil-PH`, `gl-ES`, `he-IL`, `hr-HR`, `hy-AM`, `is-IS`, `kk-KZ`, `kn-IN`, `mk-MK`, `mr-IN`, `ne-NP`, `sl-SI`, `sr-RS`, `sw-KE`, `ta-IN`, `ur-IN`, `yue-CN`, `uk-UA`. - `post_chat_analysis_data` (`array`, optional): 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."}] - `timezone` (`string`, optional): IANA timezone for the agent. Defaults to America/Los_Angeles. Example: America/New_York - `webhook_url` (`string`, optional): URL that receives this agent's chat event webhooks (chat_started, chat_ended, chat_analyzed by default). Example: https://example.com/retell/webhook Example input: `{"response_engine":{"type":"retell-llm","llm_id":"llm_234sdertfsdsfsdf"}}` ### `retell_create_chat_completion` Create Chat Completion · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `chat_id` (`string`, required): ID of the ongoing chat, from retell_create_chat. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 - `content` (`string`, required): The user's message text. Example: Hi, I'd like to reschedule my appointment. Example input: `{"chat_id":"","content":""}` ### `retell_create_contact` Create Contact · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `phone_number` (`string`, required): Contact's phone number, E.164 preferred. Only one contact can exist per phone number. Example: +14155551234 - `contact_memory` (`string`, optional): Free-text memory about the contact that agents can read during conversations. Example: Prefers afternoon calls. Has a premium plan. - `contact_tag_ids` (`array`, optional): Full set of tag IDs for the contact, from the organization's contact tags. Example: ["0f1e2d3c4b5a69788796a5b4c3d2e1f0"] - `custom_fields` (`object`, optional): 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_call` (`boolean`, optional): Mark the contact as do-not-call. Calls and SMS chats that set honor_internal_dnc are then rejected for this number. - `first_name` (`string`, optional): Contact's first name. Example: John - `last_name` (`string`, optional): Contact's last name. Example: Smith Example input: `{"phone_number":""}` ### `retell_create_conversation_flow` Create Conversation Flow · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `model_choice` (`object`, required): 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"} - `nodes` (`array`, required): 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_speaker` (`string`, required): Who speaks first in the conversation: user or agent. Example: agent. One of: `user`, `agent`. - `begin_after_user_silence_ms` (`integer`, optional): When the user speaks first, start talking after the user has been silent this many milliseconds. Omit to wait indefinitely. Example: 2000 - `default_dynamic_variables` (`object`, optional): 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_prompt` (`string`, optional): 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_ids` (`array`, optional): IDs of knowledge bases the flow can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"] - `model_temperature` (`number`, optional): Randomness of responses, from 0 (deterministic) to 1 (more varied). Example: 0.7 - `start_node_id` (`string`, optional): ID of the node the conversation starts at. Example: start - `tools` (`array`, optional): 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"}] Example input: `{"model_choice":{"type":"cascading","model":"gpt-4.1"},"nodes":[{"id":"start","type":"conversation","instruction":{"type":"prompt","text":"Greet the customer and ask how you can help."}}],"start_speaker":"user"}` ### `retell_create_conversation_flow_component` Create Conversation Flow Component · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `name` (`string`, required): Name of the component. Example: Customer Information Collector - `nodes` (`array`, required): 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_id` (`string`, optional): ID of the node the component starts at. Example: collect_info - `tools` (`array`, optional): 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"}] Example input: `{"name":"","nodes":[{"id":"collect_info","type":"conversation","instruction":{"type":"prompt","text":"Ask the customer for their name and contact information."}}]}` ### `retell_create_phone_call` Create Phone Call · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `from_number` (`string`, required): Number to call from, in E.164 format. Must be a number purchased from or imported to Retell. Example: +14157774444 - `to_number` (`string`, required): Number to call, in E.164 format. Numbers purchased from Retell can call US destinations only. Example: +12137774445 - `agent_override` (`object`, optional): 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_headers` (`object`, optional): Custom SIP headers to add to the call. Example: {"X-Custom-Header": "Custom Value"} - `honor_internal_dnc` (`boolean`, optional): Reject the call with 400 if the contact for to_number is marked do-not-call. Defaults to false. - `idempotency_key` (`string`, optional): 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 - `metadata` (`object`, optional): 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_id` (`string`, optional): Agent to use for this call only, instead of the number's outbound agent. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `override_agent_version` (`integer`, optional): Version of the override agent to use, as a version number. Omit to use the latest version. Example: 3 - `retell_llm_dynamic_variables` (`object`, optional): 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"} Example input: `{"from_number":"","to_number":""}` ### `retell_create_phone_number` Buy Phone Number · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `allowed_inbound_country_list` (`array`, optional): 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_list` (`array`, optional): ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"] - `area_code` (`integer`, optional): Three-digit US area code to buy a number in. Example: 415 - `country_code` (`string`, optional): Country of the number: US or CA. Defaults to US. One of: `US`, `CA`. - `fallback_number` (`string`, optional): Number in E.164 format to forward inbound calls to when concurrency is full and no slot frees up. Example: +14155550100 - `inbound_agents` (`array`, optional): 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_url` (`string`, optional): URL Retell calls on each inbound call so you can override the agent or set dynamic variables. Example: https://example.com/inbound-webhook - `nickname` (`string`, optional): Nickname for the number, for your own reference. Example: Support line - `number_provider` (`string`, optional): Telephony provider to buy from: twilio or telnyx. Defaults to twilio. One of: `twilio`, `telnyx`. - `outbound_agents` (`array`, optional): 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_number` (`string`, optional): Specific number to buy, in E.164 format, if you already know an available one. Example: +14157774444 - `toll_free` (`boolean`, optional): Buy a toll-free number instead of a local one. Toll-free numbers cost more. Defaults to false. Example input: `{}` ### `retell_create_retell_llm` Create Retell LLM · Write 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": ...}. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `start_speaker` (`string`, required): Who speaks first in the conversation: user or agent. The Retell docs mark it required when creating a Retell LLM. Example: agent. One of: `user`, `agent`. - `begin_message` (`string`, optional): 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_variables` (`object`, optional): Default values for dynamic variables used in the prompt, as string key-value pairs; per-call values override them. Example: {"company_name": "Acme"} - `general_prompt` (`string`, optional): 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_tools` (`array`, optional): 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_ids` (`array`, optional): IDs of knowledge bases the LLM can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"] - `model` (`string`, optional): 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_temperature` (`number`, optional): Randomness of responses, from 0 (deterministic) to 1 (more varied). Defaults to 0. Example: 0.2 - `s2s_model` (`string`, optional): 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_state` (`string`, optional): Name of the state the conversation starts in. Required when states is not empty. Example: greeting - `states` (`array`, optional): 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."}] Example input: `{"start_speaker":"user"}` ### `retell_create_sms_chat` Create SMS Chat · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `from_number` (`string`, required): Number to send from, in E.164 format. Must be a Retell number with SMS capability. Example: +12137771234 - `to_number` (`string`, required): Number to text, in E.164 format. Example: +14155551234 - `honor_internal_dnc` (`boolean`, optional): Reject the chat with 400 if the contact for to_number is marked do-not-call. Defaults to false. - `metadata` (`object`, optional): 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_id` (`string`, optional): Chat agent to use for this conversation only. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `override_agent_version` (`integer`, optional): Version of the override agent to use, as a version number. Omit to use the latest version. Example: 3 - `retell_llm_dynamic_variables` (`object`, optional): 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"} Example input: `{"from_number":"","to_number":""}` ### `retell_create_test_case_definition` Create Test Case Definition · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `metrics` (`array`, required): Criteria the test is evaluated against, as plain-language statements. Example: ["The agent confirms the new appointment time."] - `name` (`string`, required): Name of the test case. Example: Reschedule appointment - `response_engine` (`object`, required): Response engine the test runs against, as an object. For a Retell LLM use {"type": "retell-llm", "llm_id": ""}; for a conversation flow use {"type": "conversation-flow", "conversation_flow_id": ""}. Either may add a numeric version. Custom LLMs are not supported. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"} - `user_prompt` (`string`, required): 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_variables` (`object`, optional): Dynamic variables to inject into the response engine for this test, as string key-value pairs. Example: {"customer_name": "John Smith"} - `llm_model` (`string`, optional): LLM that simulates the user, such as gpt-4.1. See the Retell docs for supported models. Example: gpt-4.1 - `tool_mocks` (`array`, optional): 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}"}] Example input: `{"metrics":["The agent confirms the new appointment time."],"name":"","response_engine":{"type":"retell-llm","llm_id":"llm_234sdertfsdsfsdf"},"user_prompt":""}` ### `retell_end_chat` End Chat · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `chat_id` (`string`, required): ID of the ongoing chat to end, from retell_create_chat or retell_list_chats. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"chat_id":""}` ### `retell_import_phone_number` Import Phone Number · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `phone_number` (`string`, required): Number to import, in E.164 format. Example: +14157774444 - `termination_uri` (`string`, required): 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_list` (`array`, optional): 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_list` (`array`, optional): ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"] - `inbound_agents` (`array`, optional): 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_url` (`string`, optional): URL Retell calls on each inbound call so you can override the agent or set dynamic variables. Example: https://example.com/inbound-webhook - `nickname` (`string`, optional): Nickname for the number, for your own reference. Example: Imported support line - `outbound_agents` (`array`, optional): 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_password` (`string`, optional): Password for SIP trunk authentication, if your trunk requires credentials. - `sip_trunk_auth_username` (`string`, optional): Username for SIP trunk authentication, if your trunk requires credentials. Example: retell-trunk - `transport` (`string`, optional): Outbound SIP transport protocol: TLS, TCP or UDP. Defaults to TCP. One of: `TLS`, `TCP`, `UDP`. Example input: `{"phone_number":"","termination_uri":""}` ### `retell_publish_agent_version` Publish Agent Version · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `version` (`integer`, required): Draft version number to publish, from retell_list_agent_versions. Example: 15 - `version_description` (`string`, optional): Description of what changed in this version. Example: Hotfix for transfer timeout - `version_title` (`string`, optional): Short title for the published version, for your own reference. Example: Hotfix Example input: `{"agent_id":"","version":15}` ### `retell_repair_agent` Repair Agent · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `version` (`integer`, optional): Draft version to repair. Omit for the latest version. Example: 3 Example input: `{"agent_id":""}` ### `retell_rerun_call_analysis` Rerun Call Analysis · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `call_id` (`string`, required): ID of the ended call to analyse again, from retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"call_id":""}` ### `retell_rerun_chat_analysis` Rerun Chat Analysis · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `chat_id` (`string`, required): ID of the chat to analyse again, from retell_list_chats. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"chat_id":""}` ### `retell_stop_call` Stop Call · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `call_id` (`string`, required): ID of the ongoing call to stop, from retell_create_phone_call or retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"call_id":""}` ### `retell_update_agent` Update Agent · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `agent_name` (`string`, optional): Name of the agent, for your own reference. Example: Customer Support Agent - `ambient_sound` (`string`, optional): 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-shop`, `convention-hall`, `summer-outdoor`, `mountain-outdoor`, `static-noise`, `call-center`. - `begin_message_delay_ms` (`integer`, optional): Milliseconds to wait before the agent's first message, from 0 to 5000. Example: 1000 - `boosted_keywords` (`array`, optional): Words the transcriber should favour, such as names and product terms. Example: ["Retell", "Kubernetes"] - `data_storage_setting` (`string`, optional): What Retell stores for this agent's calls: everything, everything_except_pii, or basic_attributes_only (metadata only, no transcripts or recordings). One of: `everything`, `everything_except_pii`, `basic_attributes_only`. - `enable_backchannel` (`boolean`, optional): Whether the agent interjects short acknowledgements such as "yeah" or "uh-huh" while the user speaks. Defaults to false. - `end_call_after_silence_ms` (`integer`, optional): 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_sensitivity` (`number`, optional): How easily the user can interrupt the agent, from 0 (cannot interrupt) to 1 (interrupts easily). Defaults to 1. Example: 0.7 - `language` (`string`, optional): Locale the agent speaks and transcribes, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-US. One of: `en-US`, `en-IN`, `en-GB`, `en-AU`, `en-NZ`, `de-DE`, `es-ES`, `es-419`, `hi-IN`, `fr-FR`, `fr-CA`, `ja-JP`, `pt-PT`, `pt-BR`, `zh-CN`, `ru-RU`, `it-IT`, `ko-KR`, `nl-NL`, `nl-BE`, `pl-PL`, `tr-TR`, `vi-VN`, `ro-RO`, `bg-BG`, `ca-ES`, `th-TH`, `da-DK`, `fi-FI`, `el-GR`, `hu-HU`, `id-ID`, `no-NO`, `sk-SK`, `sv-SE`, `lt-LT`, `lv-LV`, `cs-CZ`, `ms-MY`, `af-ZA`, `ar-SA`, `az-AZ`, `bs-BA`, `cy-GB`, `fa-IR`, `fil-PH`, `gl-ES`, `he-IL`, `hr-HR`, `hy-AM`, `is-IS`, `kk-KZ`, `kn-IN`, `mk-MK`, `mr-IN`, `ne-NP`, `sl-SI`, `sr-RS`, `sw-KE`, `ta-IN`, `ur-IN`, `yue-CN`, `uk-UA`. - `max_call_duration_ms` (`integer`, optional): Maximum call length in milliseconds, from 60000 (1 minute) to 7200000 (2 hours). Defaults to 3600000 (1 hour). Example: 1800000 - `post_call_analysis_data` (`array`, optional): 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_engine` (`object`, optional): Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": ""} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_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"} - `responsiveness` (`number`, optional): How quickly the agent responds, from 0 (waits longer) to 1 (responds fastest). Defaults to 1. Example: 0.8 - `timezone` (`string`, optional): IANA timezone for the agent, used for time-aware prompts. Defaults to America/Los_Angeles. Example: America/New_York - `version` (`integer`, optional): Draft version to update. Omit for the latest version. Published versions cannot be changed. Example: 3 - `voice_id` (`string`, optional): ID of the voice the agent speaks with, from the `voice_id` field returned by retell_list_voices. Example: retell-Cimo - `voice_model` (`string`, optional): 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_speed` (`number`, optional): Speech rate from 0.5 (slower) to 2 (faster). Defaults to 1. Example: 1.1 - `voice_temperature` (`number`, optional): Voice stability from 0 (more stable) to 2 (more varied). Defaults to 1. Example: 1 - `voicemail_option` (`object`, optional): 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_url` (`string`, optional): URL that receives this agent's call event webhooks (call_started, call_ended, call_analyzed by default). Example: https://example.com/retell/webhook Example input: `{"agent_id":""}` ### `retell_update_call` Update Call · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `call_id` (`string`, required): ID of the call, from the `call_id` field returned by retell_list_calls or retell_create_phone_call. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 - `custom_attributes` (`object`, optional): 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_setting` (`string`, optional): 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: `everything`, `everything_except_pii`, `basic_attributes_only`. - `metadata` (`object`, optional): 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"} Example input: `{"call_id":""}` ### `retell_update_chat` Update Chat · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `chat_id` (`string`, required): ID of the chat, from the `chat_id` field returned by retell_list_chats or retell_create_chat. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 - `custom_attributes` (`object`, optional): 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_setting` (`string`, optional): Data storage setting for this chat: everything or basic_attributes_only (metadata only). It can only be made more restrictive, never less. One of: `everything`, `basic_attributes_only`. - `metadata` (`object`, optional): 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_variables` (`object`, optional): 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%"} Example input: `{"chat_id":""}` ### `retell_update_chat_agent` Update Chat Agent · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `agent_name` (`string`, optional): Name of the chat agent, for your own reference. Example: Website Chat Agent - `auto_close_message` (`string`, optional): Message shown when the chat is closed automatically. Example: This chat has been closed due to inactivity. - `data_storage_setting` (`string`, optional): What Retell stores for this agent's chats: everything, everything_except_pii, or basic_attributes_only. One of: `everything`, `everything_except_pii`, `basic_attributes_only`. - `end_chat_after_silence_ms` (`integer`, optional): 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 - `language` (`string`, optional): Locale the chat agent uses, such as en-US, es-ES or de-DE. Defaults to en-US. Example: en-US. One of: `en-US`, `en-IN`, `en-GB`, `en-AU`, `en-NZ`, `de-DE`, `es-ES`, `es-419`, `hi-IN`, `fr-FR`, `fr-CA`, `ja-JP`, `pt-PT`, `pt-BR`, `zh-CN`, `ru-RU`, `it-IT`, `ko-KR`, `nl-NL`, `nl-BE`, `pl-PL`, `tr-TR`, `vi-VN`, `ro-RO`, `bg-BG`, `ca-ES`, `th-TH`, `da-DK`, `fi-FI`, `el-GR`, `hu-HU`, `id-ID`, `no-NO`, `sk-SK`, `sv-SE`, `lt-LT`, `lv-LV`, `cs-CZ`, `ms-MY`, `af-ZA`, `ar-SA`, `az-AZ`, `bs-BA`, `cy-GB`, `fa-IR`, `fil-PH`, `gl-ES`, `he-IL`, `hr-HR`, `hy-AM`, `is-IS`, `kk-KZ`, `kn-IN`, `mk-MK`, `mr-IN`, `ne-NP`, `sl-SI`, `sr-RS`, `sw-KE`, `ta-IN`, `ur-IN`, `yue-CN`, `uk-UA`. - `post_chat_analysis_data` (`array`, optional): 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_engine` (`object`, optional): Response engine that generates the agent's replies, as an object with a type. Use {"type": "retell-llm", "llm_id": ""} for a Retell LLM (see retell_create_retell_llm), {"type": "conversation-flow", "conversation_flow_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"} - `timezone` (`string`, optional): IANA timezone for the agent. Defaults to America/Los_Angeles. Example: America/New_York - `version` (`integer`, optional): Draft version to update. Omit for the latest version. Example: 3 - `webhook_url` (`string`, optional): URL that receives this agent's chat event webhooks (chat_started, chat_ended, chat_analyzed by default). Example: https://example.com/retell/webhook Example input: `{"agent_id":""}` ### `retell_update_contact` Update Contact · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `contact_id` (`string`, required): ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0 - `contact_memory` (`string`, optional): New free-text memory about the contact, replacing the current text. Example: Asked to be called after 3pm. - `contact_tag_ids` (`array`, optional): Full replacement set of tag IDs for the contact. Example: ["0f1e2d3c4b5a69788796a5b4c3d2e1f0"] - `custom_fields` (`object`, optional): Custom contact field values to set, keyed by field name; value types must match the field definitions. Example: {"account_tier": "premium"} - `do_not_call` (`boolean`, optional): Mark or unmark the contact as do-not-call. - `first_name` (`string`, optional): New first name. Example: John - `last_name` (`string`, optional): New last name. Example: Smith Example input: `{"contact_id":""}` ### `retell_update_conversation_flow` Update Conversation Flow · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `conversation_flow_id` (`string`, required): ID of the conversation flow, from the `conversation_flow_id` field returned by retell_list_conversation_flows. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90 - `begin_after_user_silence_ms` (`integer`, optional): When the user speaks first, start talking after the user has been silent this many milliseconds. Omit to wait indefinitely. Example: 2000 - `default_dynamic_variables` (`object`, optional): 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_prompt` (`string`, optional): 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_ids` (`array`, optional): IDs of knowledge bases the flow can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"] - `model_choice` (`object`, optional): 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_temperature` (`number`, optional): Randomness of responses, from 0 (deterministic) to 1 (more varied). Example: 0.7 - `nodes` (`array`, optional): 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_id` (`string`, optional): ID of the node the conversation starts at. Example: start - `start_speaker` (`string`, optional): Who speaks first in the conversation: user or agent. Example: agent. One of: `user`, `agent`. - `tools` (`array`, optional): 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"}] - `version` (`integer`, optional): Version to update. Omit for the latest version. Example: 1 Example input: `{"conversation_flow_id":""}` ### `retell_update_conversation_flow_component` Update Conversation Flow Component · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `conversation_flow_component_id` (`string`, required): ID of the shared conversation flow component, from the `conversation_flow_component_id` field returned by retell_list_conversation_flow_components. Example: f0e1d2c3b4a5968778695a4b3c2d1e0f - `name` (`string`, optional): Name of the component. Example: Customer Information Collector - `nodes` (`array`, optional): 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_id` (`string`, optional): ID of the node the component starts at. Example: collect_info - `tools` (`array`, optional): 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"}] Example input: `{"conversation_flow_component_id":""}` ### `retell_update_live_call` Update Live Call · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `call_id` (`string`, required): ID of the ongoing call, from retell_create_phone_call or retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 - `call_control` (`object`, optional): 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_override` (`object`, optional): 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%"}} Example input: `{"call_id":""}` ### `retell_update_phone_number` Update Phone Number · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `phone_number` (`string`, required): 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_list` (`array`, optional): 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_list` (`array`, optional): ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. Empty or unset allows all countries. Example: ["US", "CA"] - `auth_password` (`string`, optional): New SIP trunk authentication password, for imported numbers. - `auth_username` (`string`, optional): New SIP trunk authentication username, for imported numbers. Example: retell-trunk - `fallback_number` (`string`, optional): Number in E.164 format to forward inbound calls to when concurrency is full. Example: +14155550100 - `inbound_agents` (`array`, optional): 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_agents` (`array`, optional): 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_url` (`string`, optional): 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_url` (`string`, optional): URL Retell calls on each inbound call so you can override the agent or set dynamic variables. Example: https://example.com/inbound-webhook - `nickname` (`string`, optional): Nickname for the number, for your own reference. Example: Support line - `outbound_agents` (`array`, optional): 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_agents` (`array`, optional): 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_uri` (`string`, optional): New SIP trunk termination URI, for imported numbers. Example: someuri.pstn.twilio.com - `transport` (`string`, optional): Outbound SIP transport protocol: TLS, TCP or UDP. One of: `TLS`, `TCP`, `UDP`. Example input: `{"phone_number":""}` ### `retell_update_retell_llm` Update Retell LLM · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `llm_id` (`string`, required): ID of the Retell LLM response engine, from the `llm_id` field returned by retell_list_retell_llms. Example: llm_234sdertfsdsfsdf - `begin_message` (`string`, optional): 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_variables` (`object`, optional): Default values for dynamic variables used in the prompt, as string key-value pairs; per-call values override them. Example: {"company_name": "Acme"} - `general_prompt` (`string`, optional): 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_tools` (`array`, optional): 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_ids` (`array`, optional): IDs of knowledge bases the LLM can retrieve from, from retell_list_knowledge_bases. Example: ["knowledge_base_a456426614174000"] - `model` (`string`, optional): 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_temperature` (`number`, optional): Randomness of responses, from 0 (deterministic) to 1 (more varied). Defaults to 0. Example: 0.2 - `s2s_model` (`string`, optional): 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_speaker` (`string`, optional): Who speaks first in the conversation: user or agent. The Retell docs mark it required when creating a Retell LLM. Example: agent. One of: `user`, `agent`. - `starting_state` (`string`, optional): Name of the state the conversation starts in. Required when states is not empty. Example: greeting - `states` (`array`, optional): 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."}] - `version` (`integer`, optional): Version to update. Omit for the latest version. Example: 1 Example input: `{"llm_id":""}` ### `retell_update_test_case_definition` Update Test Case Definition · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `test_case_definition_id` (`string`, required): 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_variables` (`object`, optional): Dynamic variables to inject into the response engine for this test, as string key-value pairs. Example: {"customer_name": "John Smith"} - `llm_model` (`string`, optional): LLM that simulates the user, such as gpt-4.1. See the Retell docs for supported models. Example: gpt-4.1 - `metrics` (`array`, optional): Criteria the test is evaluated against, as plain-language statements. Example: ["The agent confirms the new appointment time."] - `name` (`string`, optional): Name of the test case. Example: Reschedule appointment - `response_engine` (`object`, optional): Response engine the test runs against, as an object. For a Retell LLM use {"type": "retell-llm", "llm_id": ""}; for a conversation flow use {"type": "conversation-flow", "conversation_flow_id": ""}. Either may add a numeric version. Custom LLMs are not supported. Example: {"type": "retell-llm", "llm_id": "llm_234sdertfsdsfsdf"} - `tool_mocks` (`array`, optional): 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_prompt` (`string`, optional): 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. Example input: `{"test_case_definition_id":""}` ### `retell_delete_agent` Delete Agent · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice agent to delete, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD Example input: `{"agent_id":""}` ### `retell_delete_agent_version` Delete Agent Version · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the voice or chat agent, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD - `version` (`integer`, required): Version number to delete, from retell_list_agent_versions. Example: 4 Example input: `{"agent_id":"","version":4}` ### `retell_delete_call` Delete Call · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `call_id` (`string`, required): ID of the call to delete, from retell_list_calls. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"call_id":""}` ### `retell_delete_chat` Delete Chat · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `chat_id` (`string`, required): ID of the chat to delete, from retell_list_chats. Example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 Example input: `{"chat_id":""}` ### `retell_delete_chat_agent` Delete Chat Agent · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `agent_id` (`string`, required): ID of the chat agent to delete, from the `agent_id` field returned by retell_list_agents. Example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD Example input: `{"agent_id":""}` ### `retell_delete_contact` Delete Contact · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `contact_id` (`string`, required): ID of the contact, from the `contact_id` field returned by retell_list_contacts or retell_create_contact. Example: 9f8e7d6c5b4a39281706f5e4d3c2b1a0 Example input: `{"contact_id":""}` ### `retell_delete_conversation_flow` Delete Conversation Flow · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `conversation_flow_id` (`string`, required): ID of the conversation flow, from the `conversation_flow_id` field returned by retell_list_conversation_flows. Example: a1b2c3d4e5f60718293a4b5c6d7e8f90 - `force_delete` (`boolean`, optional): 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. Example input: `{"conversation_flow_id":""}` ### `retell_delete_conversation_flow_component` Delete Conversation Flow Component · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `conversation_flow_component_id` (`string`, required): ID of the shared conversation flow component, from the `conversation_flow_component_id` field returned by retell_list_conversation_flow_components. Example: f0e1d2c3b4a5968778695a4b3c2d1e0f Example input: `{"conversation_flow_component_id":""}` ### `retell_delete_knowledge_base` Delete Knowledge Base · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `knowledge_base_id` (`string`, required): ID of the knowledge base to delete, from retell_list_knowledge_bases. Example: knowledge_base_a456426614174000 Example input: `{"knowledge_base_id":""}` ### `retell_delete_knowledge_base_source` Delete Knowledge Base Source · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `knowledge_base_id` (`string`, required): ID of the knowledge base the source belongs to, from retell_list_knowledge_bases. Example: knowledge_base_a456426614174000 - `source_id` (`string`, required): ID of the source to remove, from the source_id field in knowledge_base_sources returned by retell_get_knowledge_base. Example: 5c1e9a2b7d3f Example input: `{"knowledge_base_id":"","source_id":""}` ### `retell_delete_phone_number` Delete Phone Number · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `phone_number` (`string`, required): The phone number to delete, in E.164 format, as returned by retell_list_phone_numbers. Example: +14157774444 Example input: `{"phone_number":""}` ### `retell_delete_retell_llm` Delete Retell LLM · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `llm_id` (`string`, required): ID of the Retell LLM response engine, from the `llm_id` field returned by retell_list_retell_llms. Example: llm_234sdertfsdsfsdf - `force_delete` (`boolean`, optional): 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. Example input: `{"llm_id":""}` ### `retell_delete_test_case_definition` Delete Test Case Definition · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `test_case_definition_id` (`string`, required): ID of the test case definition to delete, from the `test_case_definition_id` field returned by retell_list_test_case_definitions. Example: 1a2b3c4d5e6f708192a3b4c5d6e7f809 Example input: `{"test_case_definition_id":""}` ## Related Other AI connectors ([all 134](/agentkit/connectors/?category=ai)): - [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools - [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 69 tools - [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |