Skip to main content
Retell AI logo
  • Category: artificial intelligence
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 70
  • Triggers: 0
  • Slug: RETELLAI
  • Version: 20261101_00

Tools

Slug: RETELLAI_ADD_COMMUNITY_VOICEAdd a community voice from ElevenLabs to your Retell voice library. Use when you need to import a shared community voice for use in your agents.

Input Parameters

string
required
Custom name for the voice in your library. This will be how the voice appears in your voice list.
string
required
Public user ID of the voice creator. This is required for ElevenLabs community voices to properly attribute and access the voice.
string
required
The voice ID from the voice provider (e.g., ElevenLabs). This identifies the specific community voice you want to add to your library.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_ADD_KNOWLEDGE_BASE_SOURCESTool to add sources (documents, URLs, text) to an existing knowledge base in Retell AI. Use when you need to add additional content to a knowledge base. At least one of knowledge_base_texts, knowledge_base_files, or knowledge_base_urls should be provided.

Input Parameters

string
required
The knowledge base id to add sources to
array
URLs to be scraped and added to the knowledge base. Must be valid URLs.
array
Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB.
array
Texts to add to the knowledge base. Array of objects with title (string, required) and text (string, required).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_BUY_A_NEW_PHONE_NUMBER_BIND_AGENTSPurchase a new phone number, optionally specifying a US area code and binding inbound and outbound agents. A nickname can also be supplied.

Input Parameters

string
Nickname for the number, for reference only.
integer
Area code of the number to obtain. Format is a 3-digit integer, currently supporting only US area codes.
string
Unique id of agent to bind to the number. If null, this number would not accept inbound calls.
string
Unique id of agent to bind to the number. If null, this number would not initiate outbound calls without an agent id override.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_AGENTCreate a new voice AI agent with specified configuration. Use when you need to set up a voice-based AI agent with custom response engine, voice settings, and behavior configuration.

Input Parameters

number
Agent volume level. Range: [0, 2], default 1.
string
Language/locale code for speech recognition and synthesis (e.g., en-US, es-ES, fr-FR, de-DE, ja-JP). Default: en-US.
string
Speech-to-text mode. Options: fast, accurate, custom.
string
required
Voice ID to use for the agent. Obtain valid voice_id from GET /list-voices endpoint.
boolean
Whether this agent is available for public preview.
string
Name of the agent for reference purposes.
object
IVR detection and action configuration
object
PII scrubbing configuration
string
TTS model selection for the selected voice (e.g., eleven_turbo_v2, sonic-3, tts-1).
number
Speech rate multiplier. Range: [0.5, 2], default 1.
string
URL to receive webhook events for this agent.
string
Background ambience. Options: coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise, call-center.
string
Emotional tone for the voice. Options: calm, sympathetic, happy, sad, angry, fearful, surprised.
string
Audio denoising mode. Options: none, noise-cancellation, noise-and-background-speech-cancellation.
number
How quickly the agent responds. Range: [0, 1], default 1.
array
List of webhook events to subscribe to.
boolean
Whether to accept DTMF input from user. Default: true.
object
required
Response engine configuration with type, llm_id (for retell-llm), llm_websocket_url (for custom-llm), or conversation_flow_id (for conversation-flow).
array
Custom keywords to bias transcription accuracy for domain-specific terms.
object
Guardrail configuration
integer
Phone ring duration for outbound calls. Range: [5000, 90000], default: 30000.
object
Voicemail action configuration
array
Custom backchannel phrases to use.
object
Custom speech-to-text configuration
boolean
Enable expiring signed URLs for accessing logs and recordings.
object
DTMF input handling configuration
number
Voice stability/temperature setting. Range: [0, 2], default 1.
string
Message to leave when voicemail is detected.
boolean
Whether agent interjects with acknowledgment phrases (e.g., ‘uh-huh’, ‘I see’).
array
Backup voice IDs from different providers to use if primary voice fails.
integer
Maximum number of reminders allowed.
integer
Webhook request timeout in milliseconds. Default: 10000.
number
Milliseconds of silence before triggering a reminder.
string
Version documentation or notes for this agent configuration.
number
Ambient sound volume level. Range: [0, 2], default 1.
string
Data retention policy. Options: everything, everything_except_pii, basic_attributes_only. Default: everything.
integer
Maximum call duration in milliseconds. Default: 3600000 (1 hour).
boolean
Whether to normalize text (convert numbers, currency) for natural speech.
string
Vocabulary specialization. Options: general, medical. Default: general.
number
Frequency of backchannel interjections. Range: [0, 1], default 0.8 when enabled.
integer
Delay before agent speaks first message. Range: [0, 5000].
string
Custom prompt for generating call summary. Maximum 2000 characters.
array
Custom data extraction fields for post-call analysis.
number
How easily the agent can be interrupted. Range: [0, 1], default 1.
string
LLM model to use for post-call analysis (e.g., gpt-4.1-mini, gpt-4.1, claude-4.5-sonnet).
array
Custom pronunciation rules using IPA or CMU phonetic notation.
integer
Signed URL expiration time in milliseconds. Default: 86400000 (24 hours).
integer
Milliseconds of silence before automatically ending the call. Minimum: 10000, default: 600000.
string
Custom prompt for determining call success. Maximum 2000 characters.
boolean
Enable dynamic adjustment of voice speed based on context.
boolean
Whether to detect voicemail entry.
integer
Voicemail detection window. Range: [5000, 180000], default: 30000.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_AGENT_VERSIONCreate a draft version of a voice or chat agent from a selected version.

Input Parameters

string
required
Unique ID of the voice or chat agent.
integer
required
Existing version number to clone into a new draft.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_A_NEW_OUTBOUND_PHONE_CALLInitiate an outbound call by POST to ‘/v2/create-phone-call’. Requires ‘from_number’ and ‘to_number’ in E.164 format. Optional overrides and metadata supported. On success, returns call details including type, status, and IDs.

Input Parameters

object
An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with this call. Not used for processing. Stored for retrieval later.
string
required
The number you want to call, in E.164 format. Right now only US numbers are officially supported when using Retell-purchased numbers.
string
required
The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell.
string
For this particular call, override the agent used with this agent id. This does not bind the agent to this number, this is for one time override.
boolean
If true, E.164 validation will be ignored for the from_number. Useful for dialing internal pseudo numbers. Only applies with custom telephony, not Retell Telephony.
integer
For this particular call, set the agent version. Only effective when override_agent_id is set.
object
A set of key-value pairs to inject into the prompt and tool descriptions. Values must be strings. Use {{variable_name}} in prompts to reference them.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_A_NEW_WEB_CALLThe /v2/create-web-call endpoint creates a web call with a unique agent ID, returning call details like type, token, call ID, and status in JSON format, with a 201 response. Optional metadata and variables can be included.

Input Parameters

string
required
Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call.
object
An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing.
integer
Specifies which version of the agent to use for this call. If not provided, the latest version is used.
object
Add optional dynamic variables in key value pairs of string to inject into your Retell LLM prompt and tool descriptions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_BATCH_TESTCreate a batch test job to run test cases against a Retell LLM or conversation flow response engine.

Input Parameters

string
required
Response engine configuration for running the test cases. Can be either a Retell LLM or conversation flow. Custom LLM is not supported for batch tests.
array
required
Array of test case definition IDs to run. Must contain at least 1 and at most 200 test case IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_CHATTool to create a new chat session with a chat agent. Use when you need to initiate a new chat conversation with a RetellAI chat agent.

Input Parameters

string
required
The chat agent to use for the call.
object
An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the chat. Not used for processing. You can later get this field from the chat object.
integer
The version of the chat agent to use for the chat. If not provided, will default to latest version.
object
Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_CHAT_AGENTCreate a new chat agent with specified configuration. Use when you need to set up a chat-based AI agent with custom response engine and behavior settings.

Input Parameters

string
Language/dialect for chat operations (e.g., ‘en-US’, ‘es-ES’). Defaults to ‘en-US’.
boolean
Whether this chat agent is available for public preview
string
Chat agent identifier for reference purposes
object
PII (Personally Identifiable Information) scrubbing configuration
string
URL that will receive chat event notifications (e.g., chat started, ended, analyzed)
string
required
The Response Engine generating agent responses. Required field with type, llm_id, and version.
boolean
Enable signed URLs for public logs access. When enabled, secure time-limited URLs are generated.
string
Message displayed when chat auto-closes after silence period
integer
Webhook timeout in milliseconds. Defaults to 10,000ms.
string
Data retention policy for the chat. Options: ‘everything’, ‘everything_except_pii’, or ‘basic_attributes_only’.
string
Summary generation guidance for chat analysis. Maximum 2000 characters.
array
Custom analysis extraction schema for post-chat analysis
object
LLM model selection for post-chat analysis
integer
Signed URL expiration duration in milliseconds. Defaults to 86,400,000ms (24 hours).
integer
Silence duration (in milliseconds) before automatically closing the chat. Minimum value is 360,000ms (6 minutes).
string
Success evaluation criteria for chat analysis. Maximum 2000 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_CHAT_COMPLETIONTool to create a chat completion for an existing chat session, generating the agent’s response to a user message. Use when you need the agent to respond to user input in an ongoing chat conversation.

Input Parameters

string
required
Unique identifier of the chat session to create completion for
string
required
User message content to generate agent chat completion response for

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_CONVERSATION_FLOWCreate a new Conversation Flow that can be attached to an agent for response generation. Requires start_speaker, model_choice, and nodes. Returns conversation_flow_id and full configuration.

Input Parameters

array
MCP (Model Context Protocol) server configurations. Enables integration with external MCP-compatible services. Each MCP may include ‘name’, ‘url’, ‘headers’, ‘query_params’, and ‘timeout_ms’.
array
required
Array of conversation flow nodes. Each node must have an ‘id’ (string), ‘type’ (string), and type-specific configuration like ‘instruction’. Example: [{‘id’: ‘greeting_node’, ‘type’: ‘conversation’, ‘instruction’: {‘type’: ‘prompt’, ‘text’: ‘Greet the user’}}].
array
Custom and built-in function definitions available in the conversation flow. Includes custom tools, end call tools, appointment booking tools, etc.
object
Knowledge base configuration for retrieval behavior. May include ‘top_k’ and ‘filter_score’ parameters.
array
Reusable sub-flows embedded within the conversation flow. Each component has its own nodes and tools.
object
required
Model configuration with model name and type. Example: {‘model’: ‘gpt-4o’, ‘type’: ‘cascading’}. Required fields: ‘model’ (string) and ‘type’ (string).
string
System instructions applied across all nodes in the conversation flow. Used to define overall agent behavior and personality.
string
ID of the node where execution begins. If not specified, the first node in the nodes array is used.
string ("user" | "agent")
required
Who initiates the conversation. Either ‘user’ or ‘agent’.
boolean
Whether this conversation flow is used for transfer LLM scenarios. Affects how the flow is processed during call transfers.
number
Controls the randomness of the model’s responses. Valid range: 0-1. Lower values make responses more deterministic. Default: 0.7.
array
Array of knowledge base IDs for RAG (Retrieval-Augmented Generation). Enables the agent to retrieve information from specified knowledge bases.
boolean
Whether to use strict mode for tool calls. Only applicable when using certain supported models.
object
Template variables available throughout the flow for personalization. Example: {‘company_name’: ‘Acme Corp’, ‘support_hours’: ‘9am-5pm’}.
object
Frontend display coordinates for the begin tag. Expected to contain ‘x’ and ‘y’ properties for UI positioning.
integer
Milliseconds to wait before agent speaks after user silence. If not set, the agent waits indefinitely for the user to speak.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_CONVERSATION_FLOW_COMPONENTCreates a new shared conversation flow component at POST ‘/create-conversation-flow-component’. Requires ‘name’ and ‘nodes’ array. Optional: tools, mcps, start_node_id, begin_tag_display_position. Returns component ID, timestamp, and the full component definition.

Input Parameters

array
MCP (Model Context Protocol) server configurations for the component. Enables integration with external MCP-compatible services.
string
required
Name of the conversation flow component. Used to identify the component.
array
required
Array of conversation flow nodes forming the component structure. Nodes can be of various types including conversation, end, function, transfer, branch, and more. Each node has an id, type, and type-specific configuration.
array
Custom and system integrations available within the component. Includes custom tools, end call tools, appointment booking tools, and more.
string
ID of the node where execution begins. If not specified, the first node in the nodes array is used as the starting point.
object
Frontend display coordinates for the begin tag. Expected to contain x and y properties for positioning in the UI.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_KNOWLEDGE_BASETool to create a new knowledge base in Retell AI with texts, files, and URLs. Use when you need to create a knowledge base for an AI agent. At least one of knowledge_base_texts, knowledge_base_files, or knowledge_base_urls should be provided.

Input Parameters

string
required
Name of the knowledge base. Must be less than 40 characters.
array
URLs to be scraped and added to the knowledge base. Must be valid URLs.
array
Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB.
array
Texts to add to the knowledge base. Array of objects with text and title fields.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_RETELL_LLMCreate a new Retell LLM Response Engine that can be attached to an agent. Use when you need to configure a new LLM-powered response system with custom prompts, tools, and conversation flows.

Input Parameters

array
Model Context Protocol (MCP) integrations for extended capabilities.
string ("gpt-4.1" | "gpt-4.1-mini" | "claude-4.5-sonnet" | "gemini-2.5-flash")
Text LLM model selection for generating responses.
array
Conversation state definitions with prompts, transitions (edges), and state-specific tools.
object
Knowledge base configuration for RAG
string ("gpt-4o-realtime" | "gpt-4o-mini-realtime")
Speech-to-speech model selection for real-time voice responses.
string
The first utterance spoken by the agent when the conversation starts.
array
Predefined tools available to the agent, such as end_call or transfer_call functions.
string ("user" | "agent")
required
Determines who initiates the conversation. Either ‘user’ or ‘agent’.
string
System prompt applied across all conversation states. Defines agent behavior and personality.
string
Name of the initial conversation state when using multi-state flows.
number
Controls randomness in model responses. Range: [0, 1]. Default is 0 for deterministic output.
array
List of knowledge base IDs for RAG (Retrieval-Augmented Generation) capabilities.
boolean
Enables dedicated resources for lower latency responses. Use for high-priority agents.
boolean
Enforces strict mode for tool calls to ensure proper function execution.
object
Key-value pairs injected into prompts as variables for dynamic content.
integer
Milliseconds to wait after user stops speaking before agent responds.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_CREATE_TEST_CASE_DEFINITIONTool to create a test case definition for agent QA testing in Retell AI. Use when you need to define test scenarios for evaluating agent performance with specific user personas, goals, and success metrics.

Input Parameters

string
required
Name of the test case definition.
array
required
Array of metric name strings to evaluate the test case. Each metric describes a specific aspect to verify.
string
Optional LLM model specification to use for evaluation.
array
Optional array of tool mocks to simulate tool responses during testing.
string
required
User scenario prompt describing the identity, goal, and personality for the test case. Should outline who the user is, what they want to achieve, and how they behave.
object
required
Response engine configuration. Must include type (‘retell-llm’ or ‘conversation-flow’), the corresponding ID field, and version.
object
Optional dynamic variables object to inject into the test case prompts as key-value pairs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_AGENTDeletes an existing agent by its unique identifier. Returns 204 No Content on successful deletion.

Input Parameters

string
required
Unique id of the agent to be deleted

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_CALLDelete a specific call and its associated data by call ID. Use when you need to permanently remove a call record from the system.

Input Parameters

string
required
The call id to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_CHAT_AGENTDelete an existing chat agent by its unique identifier. Use when you need to permanently remove a chat agent from the system.

Input Parameters

string
required
The unique identifier of the chat agent to delete

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_CONVERSATION_FLOWDelete a conversation flow and all its versions. Use when you need to permanently remove a conversation flow from the system.

Input Parameters

string
required
Unique id of the conversation flow to be deleted

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_CONVERSATION_FLOW_COMPONENTDelete a shared conversation flow component. When deleting a shared component, creates local copies for all linked conversation flows.

Input Parameters

string
required
The unique identifier of the conversation flow component to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_KNOWLEDGE_BASEDelete an existing knowledge base by its unique identifier. Use when you need to permanently remove a knowledge base from the system.

Input Parameters

string
required
The knowledge base id to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_KNOWLEDGE_BASE_SOURCEDelete an existing source from a knowledge base. Use when you need to remove a specific document, text, or URL source from a knowledge base.

Input Parameters

string
required
The unique identifier of the source to delete from the knowledge base
string
required
The unique identifier of the knowledge base to delete source from

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_PHONE_NUMBERTool to delete an existing phone number from Retell AI. Use when you need to remove a phone number that is no longer needed. The phone number must be in E.164 format (e.g., +14159998888).

Input Parameters

string
required
Phone number to delete in E.164 format (e.g., +14159998888)

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_RETELL_LLMDelete an existing Retell LLM Response Engine by its unique identifier. Use when you need to permanently remove a Retell LLM from the system.

Input Parameters

string
required
The unique identifier of the Retell LLM to delete

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_DELETE_TEST_CASE_DEFINITIONDelete a test case definition by its unique identifier. Use when you need to permanently remove a test case definition from the system.

Input Parameters

string
required
ID of the test case definition to delete

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_END_CHATTool to end an active chat session. Use when you need to terminate an ongoing chat conversation.

Input Parameters

string
required
Unique id of the chat to be ended

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_AGENTRetrieve details of a specific agent by its unique identifier. Use when you need to access agent configuration details.

Input Parameters

string
required
Unique identifier of the agent to retrieve

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_AGENT_VERSIONSTool to retrieve all versions of a specific agent. Use when you need to view version history or access previous configurations of an agent.

Input Parameters

string
required
The unique identifier of the agent to retrieve versions for

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_BATCH_TESTRetrieve details and results of a specific batch test job. Use when you need to check the status and results of a batch test execution.

Input Parameters

string
required
ID of the batch test job to retrieve

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_CHATTool to retrieve details of a specific chat session by chat ID. Use when you need to access chat transcript, status, or analysis data.

Input Parameters

string
required
Unique id of the chat to be retrieved

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_CHAT_AGENTRetrieve details of a specific chat agent by its unique identifier. Use when you need to access chat agent configuration details.

Input Parameters

string
required
Unique identifier of the chat agent to retrieve

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_CHAT_AGENT_VERSIONSRetrieve all versions of a specific chat agent by its unique identifier. Use when you need to access version history of a chat agent.

Input Parameters

string
required
The unique identifier of the chat agent to retrieve versions for

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_CONCURRENCYRetrieves the current concurrency and concurrency limits for the organization. Use when you need to check concurrent call capacity and availability.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_CONVERSATION_FLOWRetrieve details of a specific Conversation Flow by its ID. Use when you need to fetch conversation flow configuration including nodes, version, and settings.

Input Parameters

string
required
The unique identifier of the conversation flow to retrieve

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_CONVERSATION_FLOW_COMPONENTRetrieves a shared conversation flow component by its unique identifier. Use when you need to fetch details of a specific conversation flow component.

Input Parameters

string
required
The unique identifier of the conversation flow component to retrieve

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_KNOWLEDGE_BASERetrieve details of a specific knowledge base by its unique identifier. Use when you need to access knowledge base configuration including name, status, sources, and refresh settings.

Input Parameters

string
required
The unique identifier of the knowledge base to retrieve

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_GET_RETELL_LLMRetrieve details of a specific Retell LLM Response Engine by its unique identifier. Use when you need to access LLM configuration including model settings, prompts, tools, states, and knowledge base configurations.

Input Parameters

string
required
Unique identifier of the Retell LLM Response Engine to be retrieved
integer
Optional version of the API to use for this request. Defaults to latest version if not specified

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_IMPORT_PHONE_NUMBERTool to import a phone number from custom telephony and bind agents to it. Use when you need to integrate an existing phone number with Retell AI’s system for handling inbound and outbound calls.

Input Parameters

string
User-defined reference name for the phone number (optional).
string
Transport protocol for SIP communication. Options: ‘TLS’, ‘TCP’, or ‘UDP’. Defaults to ‘TCP’ if not specified.
string
required
The phone number to import in E.164 format (+country code, then number with no spaces or special characters). Example: ‘+14157779999’
string
required
The termination URI to uniquely identify your elastic SIP trunk. This is used for outbound calls. Example: ‘sip.example.com’
string
Unique ID of agent to bind to the number for inbound calls. If null, this number will not accept inbound calls.
string
Unique ID of agent to bind to the number for outbound calls. If null, this number will not initiate outbound calls without an agent ID override.
string
Webhook URL for inbound call events and context (optional).
integer
Version number of the inbound agent. Defaults to the latest version if not specified.
integer
Version number of the outbound agent. Defaults to the latest version if not specified.
string
Password for SIP trunk authentication (optional).
string
Username for SIP trunk authentication (optional).
array
List of ISO 3166-1 alpha-2 country codes that are allowed for inbound calls. If empty or null, all countries are allowed.
array
List of ISO 3166-1 alpha-2 country codes that are allowed for outbound calls. If empty or null, all countries are allowed.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_AGENTSRetrieves a list of all agents associated with the account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_AGENT_VERSIONSList paginated version summaries for a Retell voice or chat agent.

Input Parameters

integer
Maximum version summaries to return (up to 1000).
string
required
Unique ID of the voice or chat agent.
string ("ascending" | "descending")
Order versions by version number.
string
Cursor returned by a previous page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_ALL_CHATSRetrieve a page of chats associated with the account for viewing chat history or analyzing conversations. Supports sorting, a result limit, and a pagination key for subsequent pages.

Input Parameters

integer
Limit the number of chats returned. Default is 50, maximum is 1000. To retrieve more than 1000 results, use pagination_key to continue fetching the next page.
string ("ascending" | "descending")
The chats will be sorted by start_timestamp, whether to return the chats in ascending or descending order. Default is descending.
string
The pagination key to continue fetching the next page of chats. Represented by a chat id, pagination key is exclusive (not included in the fetched chats). If not set, will start from the beginning.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_ALL_PHONE_NUMBERSRetrieves a list of all phone numbers associated with the account. An empty result means no phone numbers exist; RETELLAI_BUY_A_NEW_PHONE_NUMBER_BIND_AGENTS must be called before outbound calls can be made.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_BATCH_TESTSTool to list batch test jobs for a response engine. Use when you need to retrieve batch testing results for a Retell LLM or conversation flow.

Input Parameters

string ("retell-llm" | "conversation-flow")
required
Type of response engine to filter batch tests
string
LLM ID (required when type is retell-llm)
integer
Version of the response engine (defaults to latest if not specified)
string
Conversation flow ID (required when type is conversation-flow)

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_CHAT_AGENTSList chat agents associated with the account, with pagination and an optional page limit. Use it to view available chat agents or find agent configurations.

Input Parameters

integer
A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 1000.
string
The pagination key to continue fetching the next page of agents. Pagination key is represented by a agent id, pagination key and version pair is exclusive (not included in the fetched page). If not set, will start from the beginning.
integer
Specifies the version of the agent associated with the pagination_key. When paginating, both the pagination_key and its version must be provided to ensure consistent ordering and to fetch the next page correctly.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_CONVERSATION_FLOW_COMPONENTSRetrieves a list of all shared conversation flow components. Use when you need to access reusable conversation flow building blocks that can be referenced across multiple conversation flows.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_CONVERSATION_FLOWSList conversation flows available for agent configuration. Results are paginated; use the pagination key and its version to retrieve subsequent pages.

Input Parameters

integer
Limit the number of conversation flows returned. Default is 1000, maximum is 1000.
string
The pagination key to continue fetching the next page of conversation flows. Represented by a conversation flow id, pagination key is exclusive (not included in the fetched page). If not set, will start from the beginning.
integer
Specifies the version of the conversation flow associated with the pagination_key. When paginating, both the pagination_key and its version must be provided to ensure consistent ordering and to fetch the next page correctly.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_KNOWLEDGE_BASESTool to retrieve all knowledge bases associated with the account. Use when you need to list or view all available knowledge bases with their details including IDs, names, statuses, sources, and refresh settings.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_RETELL_LLMSList a page of Retell LLM Response Engines that can be attached to an agent, including available IDs, models, prompts, tools, and other settings. Use pagination to retrieve additional pages.

Input Parameters

integer
A limit on the number of objects to be returned. Limit can range between 1 and 1000, default is 1000
string
The pagination key to continue fetching the next page of LLMs. Represented by a llm id
integer
Specifies the version of the llm associated with the pagination_key

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_TEST_CASE_DEFINITIONSTool to list test case definitions for a response engine (Retell LLM or Conversation Flow). Use when you need to retrieve all test cases configured for a specific response engine and optionally a specific version.

Input Parameters

string ("retell-llm" | "conversation-flow")
required
Type of response engine. Must be either ‘retell-llm’ or ‘conversation-flow’
string
LLM ID (required when type is retell-llm)
integer
Version of the response engine. If not specified, defaults to the latest version
string
Conversation flow ID (required when type is conversation-flow)

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_TEST_RUNSTool to list all test case jobs (test runs) for a batch test job. Use when you need to retrieve execution results and details for all tests in a batch.

Input Parameters

string
required
Unique identifier of the batch test job to retrieve test runs for

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_LIST_VOICESList all voices available to the user. Returns voice details including voice_id, name, provider, accent, gender, age, and preview audio URL.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_PUBLISH_AGENTPublishes the latest version of the agent and creates a new draft agent with a newer version. Use when you need to deploy an agent to production.

Input Parameters

string
required
Unique id of the agent to be published

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_PUBLISH_AGENT_VERSIONPublish a selected draft version of a Retell voice or chat agent in place.

Input Parameters

integer
required
Draft version number to publish.
string
required
Unique ID of the voice or chat agent.
string
Optional title to store on the published version.
string
Optional description to store on the published version.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_PUBLISH_CHAT_AGENTPublishes the latest version of the chat agent and creates a new draft chat agent with a newer version. Use when you need to deploy a chat agent to production.

Input Parameters

string
required
Unique id of the chat agent to be published

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_REGISTER_PHONE_CALLRegister a phone call for custom telephony integration with Retell AI. Use when you need to register a call before connecting it to Retell’s audio websocket for custom telephony providers.

Input Parameters

string
required
The agent to use for the call.
object
An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.
string ("inbound" | "outbound")
Direction of the phone call. Stored for tracking purpose.
string
The number you want to call, in E.164 format. Stored for tracking purpose.
string
The number you own in E.164 format. Stored for tracking purpose.
integer
The version of the agent to use for the call.
object
Override configuration for agent, retell LLM, or conversation flow settings for a specific call.
object
Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_RETRIEVE_CALL_DETAILSTool to retrieve call details with filtering options. Use when you need to fetch call records, analyze call history, or monitor call performance.

Input Parameters

integer
Number of calls to return per request. Maximum: 1000 Each record may include full transcripts and analysis; high limits can produce large payloads.
string ("ascending" | "descending")
Sort order for results by start_timestamp Only start_timestamp ordering is supported; sort by end_timestamp client-side if call completion order is needed.
string
Call ID for pagination (exclusive). Use the last call_id from previous results Iterate pages by setting this to the last call_id of each response; stop when the response returns fewer records than limit.
object
Filter criteria for call retrieval

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_RETRIEVE_CALL_DETAILS_BY_IDRetrieve call details by ID for web/phone calls, including type, agent ID, status, timestamps, and web access token; covering responses from success to server errors.

Input Parameters

string
required
Call Id

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_RETRIEVE_DETAILS_OF_A_SPECIFIC_PHONE_NUMBERTool to retrieve details of a specific phone number from Retell AI. Use when you need to get information about a phone number including its type, timestamps, SIP configuration, and SMS settings. The phone number should be provided in E.164 format.

Input Parameters

string
required
Phone number in E.164 format (e.g., +14158887777). The phone number will be automatically URL-encoded for the API request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_RETRIEVE_DETAILS_OF_A_SPECIFIC_VOICETool to retrieve details of a specific voice by its voice_id. Use when you need information about a specific voice including its name, provider, accent, gender, age, and preview audio URL.

Input Parameters

string
required
The unique identifier for the voice to retrieve (e.g., ‘cartesia-Cleo’, ‘11labs-Adrian’)

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_SEARCH_COMMUNITY_VOICESearch for community voices from voice providers. Use when you need to find voices by name, description, or ID, optionally filtering by provider.

Input Parameters

string
required
Query to find voices by name, description, or ID
string ("elevenlabs" | "cartesia" | "minimax")
Provider filter for voices. Options: elevenlabs, cartesia, minimax

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_AGENTUpdate an existing agent’s latest draft version. Use when modifying agent configuration, voice settings, or behavior parameters for a Retell AI agent.

Input Parameters

number
Agent speech loudness (range 0-2)
string
required
Unique identifier for the agent to update
string
Speech recognition language/dialect
string
Voice identifier for TTS output
string
Agent identifier for reference purposes
object
Configuration for IVR handling actions
object
Configuration for PII scrubbing
string
Model selection (eleven_turbo_v2, sonic-3, gpt-4o-mini-tts, etc.)
number
Speech rate adjustment (range 0.5-2)
string
Event notification endpoint
string
Response engine configuration (OneOf: retell-llm, custom-llm, or conversation-flow)
object
Configuration for voicemail handling actions
object
Custom STT configuration with provider and endpointing
object
Configuration for user DTMF input (request)
number
Speech stability control (range 0-2)
boolean
Enable engagement vocalizations
integer
Call duration cap (60,000-7,200,000ms)
array
Array of analysis data objects for post-call extraction
integer
Silence timeout minimum 10,000ms

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_CALLUpdate an active call’s parameters such as metadata, dynamic variables, or data storage settings. Use when you need to modify call attributes during an ongoing call or update storage settings.

Input Parameters

string
required
The call id of the call to be updated
object
An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object. Size limited to 50kB max.
object
Custom attributes for the call
string ("everything" | "everything_except_pii" | "basic_attributes_only")
Data storage setting for calls
object
Override dynamic variables represented as key-value pairs of strings. Setting this will override or add the dynamic variables set in the agent during the call. Only need to set the delta where you want to override, no need to set the entire dynamic variables object. Setting this to null will remove any existing override.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_CHAT_AGENTUpdate an existing chat agent’s configuration, including its response engine and supported behavior settings. A response engine must be supplied with every update.

Input Parameters

string
required
Unique id of the chat agent to be updated
string
Supported languages including en-US, es-ES, multi, etc.
boolean
Public agent preview availability
string
Agent reference name
string
Event listener endpoint
object
required
The response generation engine attached to the agent
string
Message displayed when chat auto-closes
string
everything, everything_except_pii, or basic_attributes_only
integer
Silence duration threshold (360000-259200000 ms range)

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_CHAT_METADATATool to update metadata and sensitive data storage settings for an existing chat. Use when you need to modify chat metadata, custom attributes, or override dynamic variables.

Input Parameters

string
required
The chat id of the chat to be updated.
object
An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the chat. Not used for processing. You can later get this field from the chat object. Size limited to 50kB max.
object
Custom attributes for the chat. Values can be strings, numbers, or booleans.
string ("everything" | "basic_attributes_only")
Data storage settings for chat
object
Override dynamic variables represented as key-value pairs of strings. Setting this will override or add the dynamic variables set in the agent during the call. Only need to set the delta where you want to override, no need to set the entire dynamic variables object. Setting this to null will remove any existing override.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_CONVERSATION_FLOWUpdate an existing conversation flow configuration. Use when modifying conversation flow settings such as model parameters, nodes, tools, or prompt templates.

Input Parameters

array
Model Context Protocol (MCP) server configurations for external integrations
array
Array of conversation nodes that define the flow structure and logic
array
Available tools/functions that can be called during the conversation flow
integer
Specific version of conversation flow to update; defaults to latest if not specified
object
Knowledge base retrieval configuration settings
array
Embedded sub-components within the conversation flow
object
Model choice settings for the conversation flow
string
System prompt applied across all nodes in the conversation flow
string
Entry point node identifier that determines where the conversation flow begins
string
Determines who initiates the conversation; must be ‘user’ or ‘agent’
boolean
Flag indicating whether this is a transfer LLM configuration
number
Controls response randomness; range 0-1 where 0 is deterministic and 1 is most random
array
Knowledge base IDs for RAG (Retrieval-Augmented Generation) functionality
string
required
Unique identifier for the conversation flow to update
boolean
Enables strict mode for tool calls to enforce stricter validation
object
Pre-configured variables that can be used dynamically throughout the flow
integer
Milliseconds to wait after user silence before agent begins speaking

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_CONVERSATION_FLOW_COMPONENTUpdate an existing shared conversation flow component by its ID. Use when you need to modify component properties like name, nodes, tools, or MCP configurations.

Input Parameters

array
MCP server configurations for the component. Each configuration includes name, url, headers, query_params, and timeout_ms.
string
The component’s display name
array
Array of node objects that comprise the component structure. Each node contains an id, type, and instruction configuration.
array
Array of tool configurations available within the component. Each tool includes type, name, description, and endpoint details.
string
Identifier of the initial node in the component flow
object
Frontend display coordinates for the begin tag in the visual editor
string
required
The unique identifier of the conversation flow component to update

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_PHONE_NUMBERUpdate agent bound to a purchased phone number. Use when you need to change the agent configuration, nickname, webhook URLs, or SIP settings for an existing phone number.

Input Parameters

string
Custom reference name for the phone number
string ("TLS" | "TCP" | "UDP")
SIP transport protocol
string
required
E.164 format phone number (e.g., +14157774444)
string
SIP authentication password
string
SIP authentication username
string
SIP termination address
string
Agent ID for receiving calls, or null to prevent inbound calls
string
Agent ID for making outbound calls
string
Webhook endpoint URL for inbound call notifications
integer
Inbound agent version number
integer
Outbound agent version number
array
ISO 3166-1 alpha-2 country codes allowed for inbound calls
array
ISO 3166-1 alpha-2 country codes allowed for outbound calls

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_RETELL_LLMUpdate an existing Retell LLM Response Engine by its unique identifier. Use when you need to modify LLM configuration, prompts, tools, conversation flows, or model settings for an existing response engine.

Input Parameters

array
Model Context Protocol (MCP) integrations for extended capabilities.
string ("gpt-4.1" | "gpt-4.1-mini" | "gpt-5" | "claude-4.5-sonnet" | "gemini-2.5-flash")
Text LLM model selection for generating responses.
string
required
Unique identifier of the Retell LLM Response Engine to update.
array
Conversation state definitions with prompts, transitions (edges), and state-specific tools.
integer
Version number of the LLM configuration.
object
Knowledge base configuration for RAG
string ("gpt-4o-realtime" | "gpt-4o-mini-realtime")
Speech-to-speech model selection for real-time voice responses.
string
The first utterance spoken by the agent when the conversation starts.
array
Predefined tools available to the agent, such as end_call or transfer_call functions.
string ("user" | "agent")
Determines who initiates the conversation. Either ‘user’ or ‘agent’.
string
System prompt applied across all conversation states. Defines agent behavior and personality.
string
Name of the initial conversation state when using multi-state flows.
number
Controls randomness in model responses. Range: [0, 1]. Lower values are more deterministic.
array
List of knowledge base IDs for RAG (Retrieval-Augmented Generation) capabilities.
boolean
Enables dedicated resources for lower latency responses. Use for high-priority agents.
boolean
Enforces strict mode for tool calls to ensure proper function execution.
object
Key-value pairs injected into prompts as variables for dynamic content.
integer
Milliseconds to wait after user stops speaking before agent responds.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: RETELLAI_UPDATE_TEST_CASE_DEFINITIONUpdate a test case definition for agent testing. Use when modifying test scenarios, metrics, or mock configurations for Retell AI agent validation.

Input Parameters

string
Name of the test case definition
array
Array of metric names to evaluate
string ("gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-5" | "gpt-5.1" | "gpt-5.2" | "gpt-5-mini" | "gpt-5-nano" | "claude-4.5-sonnet" | "claude-4.5-haiku" | "gemini-2.5-flash" | "gemini-2.5-flash-lite" | "gemini-3.0-flash")
Available LLM models for agents
array
Mock tool calls for testing
string
User prompt to simulate in the test case
string
Response engine for test cases. Custom LLM is not supported.
object
Dynamic variables to inject into the response engine
string
required
ID of the test case definition to update

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not