RetellAI captures calls and transcripts, enabling businesses to analyze conversations, extract insights, and enhance customer interactions in one centralized platform
RetellAI captures calls and transcripts, enabling businesses to analyze conversations, extract insights, and enhance customer interactions in one centralized platform On Nagent, Retell AI is exposed as a fully-configurable artificial intelligence integration that any agent can call — 67 actions, and API key authentication. No code is required to wire Retell AI into your workflow — connect it once via the External Integrations panel and reuse it across every agent you build.
Agent builders use Retell AI to automate the kinds of tasks artificial intelligence teams previously handled manually. Concrete examples — each one is a single agent step in Nagent — include:
Every action and trigger is paired with a structured input/output schema (visible in the sections below), so when you wire Retell AI into Helix — our agentic agent builder — the editor knows exactly what each step expects and produces. Configure once, deploy anywhere across your Nagent agents.
Every operation an agent can call against Retell AI, with input parameters and output schema. Drop these into any step of an agent built in Helix.
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
Custom name for the voice in your library. This will be how the voice appears in your voice list.
Public user ID of the voice creator. This is required for ElevenLabs community voices to properly attribute and access the voice.
The voice ID from the voice provider (e.g., ElevenLabs). This identifies the specific community voice you want to add to your library.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The knowledge base id to add sources to
URLs to be scraped and added to the knowledge base. Must be valid URLs.
Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB.
Texts to add to the knowledge base. Array of objects with title (string, required) and text (string, required).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_BUY_A_NEW_PHONE_NUMBER_BIND_AGENTSThis endpoint allows purchasing a new phone number with a specified area code and binding it to designated agents for inbound and outbound calls. It requires JSON with agent IDs and area code. Responses indicate the creation status or errors. A purchased phone number is a prerequisite for initiating outbound calls; an empty phone number inventory will prevent outbound calls from being made.
Input parameters
Nickname for the number, for reference only.
Area code of the number to obtain. Format is a 3-digit integer, currently supporting only US area codes.
Unique id of agent to bind to the number. If null, this number would not accept inbound calls.
Unique id of agent to bind to the number. If null, this number would not initiate outbound calls without an agent id override.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Agent volume level. Range: \[0, 2\], default 1.
Language/locale code for speech recognition and synthesis (e.g., en-US, es-ES, fr-FR, de-DE, ja-JP). Default: en-US.
Speech-to-text mode. Options: fast, accurate, custom.
Voice ID to use for the agent. Obtain valid voice_id from GET /list-voices endpoint.
Whether this agent is available for public preview.
Name of the agent for reference purposes.
IVR detection and action configuration
PII scrubbing configuration
TTS model selection for the selected voice (e.g., eleven_turbo_v2, sonic-3, tts-1).
Speech rate multiplier. Range: \[0.5, 2\], default 1.
URL to receive webhook events for this agent.
Background ambience. Options: coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise, call-center.
Emotional tone for the voice. Options: calm, sympathetic, happy, sad, angry, fearful, surprised.
Audio denoising mode. Options: none, noise-cancellation, noise-and-background-speech-cancellation.
How quickly the agent responds. Range: \[0, 1\], default 1.
List of webhook events to subscribe to.
Whether to accept DTMF input from user. Default: true.
Response engine configuration with type, llm_id (for retell-llm), llm_websocket_url (for custom-llm), or conversation_flow_id (for conversation-flow).
Custom keywords to bias transcription accuracy for domain-specific terms.
Guardrail configuration
Phone ring duration for outbound calls. Range: \[5000, 90000\], default: 30000.
Voicemail action configuration
Custom backchannel phrases to use.
Custom speech-to-text configuration
Enable expiring signed URLs for accessing logs and recordings.
DTMF input handling configuration
Voice stability/temperature setting. Range: \[0, 2\], default 1.
Message to leave when voicemail is detected.
Whether agent interjects with acknowledgment phrases (e.g., 'uh-huh', 'I see').
Backup voice IDs from different providers to use if primary voice fails.
Maximum number of reminders allowed.
Webhook request timeout in milliseconds. Default: 10000.
Milliseconds of silence before triggering a reminder.
Version documentation or notes for this agent configuration.
Ambient sound volume level. Range: \[0, 2\], default 1.
Data retention policy. Options: everything, everything_except_pii, basic_attributes_only. Default: everything.
Maximum call duration in milliseconds. Default: 3600000 (1 hour).
Whether to normalize text (convert numbers, currency) for natural speech.
Vocabulary specialization. Options: general, medical. Default: general.
Frequency of backchannel interjections. Range: \[0, 1\], default 0.8 when enabled.
Delay before agent speaks first message. Range: \[0, 5000\].
Custom prompt for generating call summary. Maximum 2000 characters.
Custom data extraction fields for post-call analysis.
How easily the agent can be interrupted. Range: \[0, 1\], default 1.
LLM model to use for post-call analysis (e.g., gpt-4.1-mini, gpt-4.1, claude-4.5-sonnet).
Custom pronunciation rules using IPA or CMU phonetic notation.
Signed URL expiration time in milliseconds. Default: 86400000 (24 hours).
Milliseconds of silence before automatically ending the call. Minimum: 10000, default: 600000.
Custom prompt for determining call success. Maximum 2000 characters.
Enable dynamic adjustment of voice speed based on context.
Whether to detect voicemail entry.
Voicemail detection window. Range: \[5000, 180000\], default: 30000.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
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.
The number you want to call, in E.164 format. Right now only US numbers are officially supported when using Retell-purchased numbers.
The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell.
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.
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.
For this particular call, set the agent version. Only effective when override_agent_id is set.
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call.
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.
Specifies which version of the agent to use for this call. If not provided, the latest version is used.
Add optional dynamic variables in key value pairs of string to inject into your Retell LLM prompt and tool descriptions.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_CREATE_BATCH_TESTTool to create a batch test job that runs multiple test cases against an agent. Use when you need to evaluate agent performance across multiple test scenarios simultaneously.
Input parameters
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 of test case definition IDs to run. Must contain at least 1 and at most 200 test case IDs.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The chat agent to use for the call.
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.
The version of the chat agent to use for the chat. If not provided, will default to latest version.
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Language/dialect for chat operations (e.g., 'en-US', 'es-ES'). Defaults to 'en-US'.
Whether this chat agent is available for public preview
Chat agent identifier for reference purposes
PII (Personally Identifiable Information) scrubbing configuration
URL that will receive chat event notifications (e.g., chat started, ended, analyzed)
The Response Engine generating agent responses. Required field with type, llm_id, and version.
Enable signed URLs for public logs access. When enabled, secure time-limited URLs are generated.
Message displayed when chat auto-closes after silence period
Webhook timeout in milliseconds. Defaults to 10,000ms.
Data retention policy for the chat. Options: 'everything', 'everything_except_pii', or 'basic_attributes_only'.
Summary generation guidance for chat analysis. Maximum 2000 characters.
Custom analysis extraction schema for post-chat analysis
LLM model selection for post-chat analysis
Signed URL expiration duration in milliseconds. Defaults to 86,400,000ms (24 hours).
Silence duration (in milliseconds) before automatically closing the chat. Minimum value is 360,000ms (6 minutes).
Success evaluation criteria for chat analysis. Maximum 2000 characters.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique identifier of the chat session to create completion for
User message content to generate agent chat completion response for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
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 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'}}\].
Custom and built-in function definitions available in the conversation flow. Includes custom tools, end call tools, appointment booking tools, etc.
Knowledge base configuration for retrieval behavior. May include 'top_k' and 'filter_score' parameters.
Reusable sub-flows embedded within the conversation flow. Each component has its own nodes and tools.
Model configuration with model name and type. Example: {'model': 'gpt-4o', 'type': 'cascading'}. Required fields: 'model' (string) and 'type' (string).
System instructions applied across all nodes in the conversation flow. Used to define overall agent behavior and personality.
ID of the node where execution begins. If not specified, the first node in the nodes array is used.
Who initiates the conversation. Either 'user' or 'agent'.
Whether this conversation flow is used for transfer LLM scenarios. Affects how the flow is processed during call transfers.
Controls the randomness of the model's responses. Valid range: 0-1. Lower values make responses more deterministic. Default: 0.7.
Array of knowledge base IDs for RAG (Retrieval-Augmented Generation). Enables the agent to retrieve information from specified knowledge bases.
Whether to use strict mode for tool calls. Only applicable when using certain supported models.
Template variables available throughout the flow for personalization. Example: {'company_name': 'Acme Corp', 'support_hours': '9am-5pm'}.
Frontend display coordinates for the begin tag. Expected to contain 'x' and 'y' properties for UI positioning.
Milliseconds to wait before agent speaks after user silence. If not set, the agent waits indefinitely for the user to speak.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
MCP (Model Context Protocol) server configurations for the component. Enables integration with external MCP-compatible services.
Name of the conversation flow component. Used to identify the component.
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.
Custom and system integrations available within the component. Includes custom tools, end call tools, appointment booking tools, and more.
ID of the node where execution begins. If not specified, the first node in the nodes array is used as the starting point.
Frontend display coordinates for the begin tag. Expected to contain x and y properties for positioning in the UI.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Name of the knowledge base. Must be less than 40 characters.
URLs to be scraped and added to the knowledge base. Must be valid URLs.
Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB.
Texts to add to the knowledge base. Array of objects with text and title fields.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Model Context Protocol (MCP) integrations for extended capabilities.
Text LLM model selection for generating responses.
Conversation state definitions with prompts, transitions (edges), and state-specific tools.
Knowledge base configuration for RAG
Speech-to-speech model selection for real-time voice responses.
The first utterance spoken by the agent when the conversation starts.
Predefined tools available to the agent, such as end_call or transfer_call functions.
Determines who initiates the conversation. Either 'user' or 'agent'.
System prompt applied across all conversation states. Defines agent behavior and personality.
Name of the initial conversation state when using multi-state flows.
Controls randomness in model responses. Range: \[0, 1\]. Default is 0 for deterministic output.
List of knowledge base IDs for RAG (Retrieval-Augmented Generation) capabilities.
Enables dedicated resources for lower latency responses. Use for high-priority agents.
Enforces strict mode for tool calls to ensure proper function execution.
Key-value pairs injected into prompts as variables for dynamic content.
Milliseconds to wait after user stops speaking before agent responds.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Name of the test case definition.
Array of metric name strings to evaluate the test case. Each metric describes a specific aspect to verify.
Optional LLM model specification to use for evaluation.
Optional array of tool mocks to simulate tool responses during testing.
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.
Response engine configuration. Must include type ('retell-llm' or 'conversation-flow'), the corresponding ID field, and version.
Optional dynamic variables object to inject into the test case prompts as key-value pairs.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_DELETE_AGENTDeletes an existing agent by its unique identifier. Returns 204 No Content on successful deletion.
Input parameters
Unique id of the agent to be deleted
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The call id to delete.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the chat agent to delete
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique id of the conversation flow to be deleted
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the conversation flow component to delete.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The knowledge base id to delete.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the source to delete from the knowledge base
The unique identifier of the knowledge base to delete source from
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Phone number to delete in E.164 format (e.g., +14159998888)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the Retell LLM to delete
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
ID of the test case definition to delete
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_END_CHATTool to end an active chat session. Use when you need to terminate an ongoing chat conversation.
Input parameters
Unique id of the chat to be ended
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_GET_AGENTRetrieve details of a specific agent by its unique identifier. Use when you need to access agent configuration details.
Input parameters
Unique identifier of the agent to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the agent to retrieve versions for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
ID of the batch test job to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique id of the chat to be retrieved
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique identifier of the chat agent to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the chat agent to retrieve versions for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_GET_CONCURRENCYRetrieves the current concurrency and concurrency limits for the organization. Use when you need to check concurrent call capacity and availability.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the conversation flow to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the conversation flow component to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier of the knowledge base to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique identifier of the Retell LLM Response Engine to be retrieved
Optional version of the API to use for this request. Defaults to latest version if not specified
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
User-defined reference name for the phone number (optional).
Transport protocol for SIP communication. Options: 'TLS', 'TCP', or 'UDP'. Defaults to 'TCP' if not specified.
The phone number to import in E.164 format (+country code, then number with no spaces or special characters). Example: '+14157779999'
The termination URI to uniquely identify your elastic SIP trunk. This is used for outbound calls. Example: 'sip.example.com'
Unique ID of agent to bind to the number for inbound calls. If null, this number will not accept inbound calls.
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.
Webhook URL for inbound call events and context (optional).
Version number of the inbound agent. Defaults to the latest version if not specified.
Version number of the outbound agent. Defaults to the latest version if not specified.
Password for SIP trunk authentication (optional).
Username for SIP trunk authentication (optional).
List of ISO 3166-1 alpha-2 country codes that are allowed for inbound calls. If empty or null, all countries are allowed.
List of ISO 3166-1 alpha-2 country codes that are allowed for outbound calls. If empty or null, all countries are allowed.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_LIST_AGENTSRetrieves a list of all agents associated with the account.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_LIST_ALL_CHATSTool to retrieve a list of all chats associated with the account. Use when you need to view chat history or analyze past conversations.
Input parameters
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.
The chats will be sorted by start_timestamp, whether to return the chats in ascending or descending order. Default is descending.
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Type of response engine to filter batch tests
LLM ID (required when type is retell-llm)
Version of the response engine (defaults to latest if not specified)
Conversation flow ID (required when type is conversation-flow)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_LIST_CHAT_AGENTSTool to retrieve a list of all chat agents associated with the account. Use when you need to view available chat agents or find specific chat agent configurations.
Input parameters
A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 1000.
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.
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_LIST_CONVERSATION_FLOWSTool to list all conversation flows that can be attached to an agent. Use when you need to retrieve available conversation flows for agent configuration.
Input parameters
Limit the number of conversation flows returned. Default is 1000, maximum is 1000.
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.
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_LIST_RETELL_LLMSTool to list all Retell LLM Response Engines that can be attached to an agent. Use when you need to retrieve available LLM configurations including their IDs, models, prompts, tools, and other settings.
Input parameters
A limit on the number of objects to be returned. Limit can range between 1 and 1000, default is 1000
The pagination key to continue fetching the next page of LLMs. Represented by a llm id
Specifies the version of the llm associated with the pagination_key
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Type of response engine. Must be either 'retell-llm' or 'conversation-flow'
LLM ID (required when type is retell-llm)
Version of the response engine. If not specified, defaults to the latest version
Conversation flow ID (required when type is conversation-flow)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique identifier of the batch test job to retrieve test runs for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique id of the agent to be published
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Unique id of the chat agent to be published
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The agent to use for the call.
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.
Direction of the phone call. Stored for tracking purpose.
The number you want to call, in E.164 format. Stored for tracking purpose.
The number you own in E.164 format. Stored for tracking purpose.
The version of the agent to use for the call.
Override configuration for agent, retell LLM, or conversation flow settings for a specific call.
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Number of calls to return per request. Maximum: 1000 Each record may include full transcripts and analysis; high limits can produce large payloads.
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.
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.
Filter criteria for call retrieval
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Call Id
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Phone number in E.164 format (e.g., +14158887777). The phone number will be automatically URL-encoded for the API request.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The unique identifier for the voice to retrieve (e.g., 'cartesia-Cleo', '11labs-Adrian')
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Query to find voices by name, description, or ID
Provider filter for voices. Options: elevenlabs, cartesia, minimax
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Agent speech loudness (range 0-2)
Unique identifier for the agent to update
Speech recognition language/dialect
Voice identifier for TTS output
Agent identifier for reference purposes
Configuration for IVR handling actions
Configuration for PII scrubbing
Model selection (eleven_turbo_v2, sonic-3, gpt-4o-mini-tts, etc.)
Speech rate adjustment (range 0.5-2)
Event notification endpoint
Response engine configuration (OneOf: retell-llm, custom-llm, or conversation-flow)
Configuration for voicemail handling actions
Custom STT configuration with provider and endpointing
Configuration for user DTMF input (request)
Speech stability control (range 0-2)
Enable engagement vocalizations
Call duration cap (60,000-7,200,000ms)
Array of analysis data objects for post-call extraction
Silence timeout minimum 10,000ms
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The call id of the call to be updated
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.
Custom attributes for the call
Data storage setting for calls
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
RETELLAI_UPDATE_CHAT_AGENTUpdate an existing chat agent configuration. Use when modifying chat agent settings, response engine, or behavior parameters.
Input parameters
Unique id of the chat agent to be updated
Supported languages including en-US, es-ES, multi, etc.
Public agent preview availability
Agent reference name
Event listener endpoint
The response generation engine attached to the agent
Message displayed when chat auto-closes
everything, everything_except_pii, or basic_attributes_only
Silence duration threshold (360000-259200000 ms range)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
The chat id of the chat to be updated.
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.
Custom attributes for the chat. Values can be strings, numbers, or booleans.
Data storage settings for chat
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
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Model Context Protocol (MCP) server configurations for external integrations
Array of conversation nodes that define the flow structure and logic
Available tools/functions that can be called during the conversation flow
Specific version of conversation flow to update; defaults to latest if not specified
Knowledge base retrieval configuration settings
Embedded sub-components within the conversation flow
Model choice settings for the conversation flow
System prompt applied across all nodes in the conversation flow
Entry point node identifier that determines where the conversation flow begins
Determines who initiates the conversation; must be 'user' or 'agent'
Flag indicating whether this is a transfer LLM configuration
Controls response randomness; range 0-1 where 0 is deterministic and 1 is most random
Knowledge base IDs for RAG (Retrieval-Augmented Generation) functionality
Unique identifier for the conversation flow to update
Enables strict mode for tool calls to enforce stricter validation
Pre-configured variables that can be used dynamically throughout the flow
Milliseconds to wait after user silence before agent begins speaking
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
MCP server configurations for the component. Each configuration includes name, url, headers, query_params, and timeout_ms.
The component's display name
Array of node objects that comprise the component structure. Each node contains an id, type, and instruction configuration.
Array of tool configurations available within the component. Each tool includes type, name, description, and endpoint details.
Identifier of the initial node in the component flow
Frontend display coordinates for the begin tag in the visual editor
The unique identifier of the conversation flow component to update
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Custom reference name for the phone number
SIP transport protocol
E.164 format phone number (e.g., +14157774444)
SIP authentication password
SIP authentication username
SIP termination address
Agent ID for receiving calls, or null to prevent inbound calls
Agent ID for making outbound calls
Webhook endpoint URL for inbound call notifications
Inbound agent version number
Outbound agent version number
ISO 3166-1 alpha-2 country codes allowed for inbound calls
ISO 3166-1 alpha-2 country codes allowed for outbound calls
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Model Context Protocol (MCP) integrations for extended capabilities.
Text LLM model selection for generating responses.
Unique identifier of the Retell LLM Response Engine to update.
Conversation state definitions with prompts, transitions (edges), and state-specific tools.
Version number of the LLM configuration.
Knowledge base configuration for RAG
Speech-to-speech model selection for real-time voice responses.
The first utterance spoken by the agent when the conversation starts.
Predefined tools available to the agent, such as end_call or transfer_call functions.
Determines who initiates the conversation. Either 'user' or 'agent'.
System prompt applied across all conversation states. Defines agent behavior and personality.
Name of the initial conversation state when using multi-state flows.
Controls randomness in model responses. Range: \[0, 1\]. Lower values are more deterministic.
List of knowledge base IDs for RAG (Retrieval-Augmented Generation) capabilities.
Enables dedicated resources for lower latency responses. Use for high-priority agents.
Enforces strict mode for tool calls to ensure proper function execution.
Key-value pairs injected into prompts as variables for dynamic content.
Milliseconds to wait after user stops speaking before agent responds.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
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
Name of the test case definition
Array of metric names to evaluate
Available LLM models for agents
Mock tool calls for testing
User prompt to simulate in the test case
Response engine for test cases. Custom LLM is not supported.
Dynamic variables to inject into the response engine
ID of the test case definition to update
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
No publicly available marketplace agent is found using this tool yet. There are 92 agents privately built on Nagent that already use Retell AI.
Build on Nagent
Connect Retell AI to any Nagent agent in minutes — no API key management, no boilerplate. Just configure and deploy.
The five questions agent builders ask before adopting a new integration.
Open the External Integrations panel inside Nagent (app.nagent.ai/externalIntegration), find Retell AI, and click "Connect Now." You'll authenticate with an API key — Nagent handles credential storage and refresh automatically. Once connected, Retell AI is available to any agent in your workspace.
No. Nagent provides no-code integration for every tool. Once Retell AI is connected, you configure its 67 actions directly in the agent builder UI — no API calls, no boilerplate, no schema management.
Helix — Nagent's agentic agent builder — lets you drop Retell AI steps into any workflow visually. Pick an action (e.g., one of those listed above), fill in the inputs (Helix knows the required vs. optional schema for each parameter), and connect it to upstream/downstream steps. Triggers run as the entry point of an agent, so when a Retell AI event fires, the agent kicks off automatically.
Every Retell AI action and trigger ships with a fully-typed schema — input parameters with name, type, required flag, and description, plus the output payload shape. The schemas are documented in the sections above. Helix uses these schemas to validate your configuration at build time and to type-check the data flowing between steps.
Yes. While Retell AI ships with 67 pre-built artificial intelligence actions, you can layer custom logic around them inside Helix — pre/post-processing steps, conditional branches, retries, or stitching Retell AI together with other connected tools. For deeper customization, talk to our team about Nagent's Agentic AI Lab — forward-deployed engineers who build Retell AI-based workflows tailored to your business.