# Retell AI RetellAI captures calls and transcripts, enabling businesses to analyze conversations, extract insights, and enhance customer interactions in one centralized platform - **Category:** artificial intelligence - **Auth:** API_KEY - **Composio Managed App Available?** N/A - **Tools:** 67 - **Triggers:** 0 - **Slug:** `RETELLAI` - **Version:** 20260316_00 ## Tools ### Add community voice **Slug:** `RETELLAI_ADD_COMMUNITY_VOICE` Add 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `voice_name` | string | Yes | Custom name for the voice in your library. This will be how the voice appears in your voice list. | | `public_user_id` | string | Yes | Public user ID of the voice creator. This is required for ElevenLabs community voices to properly attribute and access the voice. | | `provider_voice_id` | string | Yes | The voice ID from the voice provider (e.g., ElevenLabs). This identifies the specific community voice you want to add to your library. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add sources to knowledge base **Slug:** `RETELLAI_ADD_KNOWLEDGE_BASE_SOURCES` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `knowledge_base_id` | string | Yes | The knowledge base id to add sources to | | `knowledge_base_urls` | array | No | URLs to be scraped and added to the knowledge base. Must be valid URLs. | | `knowledge_base_files` | array | No | Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB. | | `knowledge_base_texts` | array | No | Texts to add to the knowledge base. Array of objects with title (string, required) and text (string, required). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Buy a new phone number bind agents **Slug:** `RETELLAI_BUY_A_NEW_PHONE_NUMBER_BIND_AGENTS` This 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `nickname` | string | No | Nickname for the number, for reference only. | | `area_code` | integer | No | Area code of the number to obtain. Format is a 3-digit integer, currently supporting only US area codes. | | `inbound_agent_id` | string | No | Unique id of agent to bind to the number. If null, this number would not accept inbound calls. | | `outbound_agent_id` | string | No | Unique id of agent to bind to the number. If null, this number would not initiate outbound calls without an agent id override. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Voice AI Agent **Slug:** `RETELLAI_CREATE_AGENT` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `volume` | number | No | Agent volume level. Range: [0, 2], default 1. | | `language` | string | No | Language/locale code for speech recognition and synthesis (e.g., en-US, es-ES, fr-FR, de-DE, ja-JP). Default: en-US. | | `stt_mode` | string | No | Speech-to-text mode. Options: fast, accurate, custom. | | `voice_id` | string | Yes | Voice ID to use for the agent. Obtain valid voice_id from GET /list-voices endpoint. | | `is_public` | boolean | No | Whether this agent is available for public preview. | | `agent_name` | string | No | Name of the agent for reference purposes. | | `ivr_option` | object | No | IVR detection and action configuration | | `pii_config` | object | No | PII scrubbing configuration | | `voice_model` | string | No | TTS model selection for the selected voice (e.g., eleven_turbo_v2, sonic-3, tts-1). | | `voice_speed` | number | No | Speech rate multiplier. Range: [0.5, 2], default 1. | | `webhook_url` | string | No | URL to receive webhook events for this agent. | | `ambient_sound` | string | No | Background ambience. Options: coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise, call-center. | | `voice_emotion` | string | No | Emotional tone for the voice. Options: calm, sympathetic, happy, sad, angry, fearful, surprised. | | `denoising_mode` | string | No | Audio denoising mode. Options: none, noise-cancellation, noise-and-background-speech-cancellation. | | `responsiveness` | number | No | How quickly the agent responds. Range: [0, 1], default 1. | | `webhook_events` | array | No | List of webhook events to subscribe to. | | `allow_user_dtmf` | boolean | No | Whether to accept DTMF input from user. Default: true. | | `response_engine` | object | Yes | Response engine configuration with type, llm_id (for retell-llm), llm_websocket_url (for custom-llm), or conversation_flow_id (for conversation-flow). | | `boosted_keywords` | array | No | Custom keywords to bias transcription accuracy for domain-specific terms. | | `guardrail_config` | object | No | Guardrail configuration | | `ring_duration_ms` | integer | No | Phone ring duration for outbound calls. Range: [5000, 90000], default: 30000. | | `voicemail_option` | object | No | Voicemail action configuration | | `backchannel_words` | array | No | Custom backchannel phrases to use. | | `custom_stt_config` | object | No | Custom speech-to-text configuration | | `opt_in_signed_url` | boolean | No | Enable expiring signed URLs for accessing logs and recordings. | | `user_dtmf_options` | object | No | DTMF input handling configuration | | `voice_temperature` | number | No | Voice stability/temperature setting. Range: [0, 2], default 1. | | `voicemail_message` | string | No | Message to leave when voicemail is detected. | | `enable_backchannel` | boolean | No | Whether agent interjects with acknowledgment phrases (e.g., 'uh-huh', 'I see'). | | `fallback_voice_ids` | array | No | Backup voice IDs from different providers to use if primary voice fails. | | `reminder_max_count` | integer | No | Maximum number of reminders allowed. | | `webhook_timeout_ms` | integer | No | Webhook request timeout in milliseconds. Default: 10000. | | `reminder_trigger_ms` | number | No | Milliseconds of silence before triggering a reminder. | | `version_description` | string | No | Version documentation or notes for this agent configuration. | | `ambient_sound_volume` | number | No | Ambient sound volume level. Range: [0, 2], default 1. | | `data_storage_setting` | string | No | Data retention policy. Options: everything, everything_except_pii, basic_attributes_only. Default: everything. | | `max_call_duration_ms` | integer | No | Maximum call duration in milliseconds. Default: 3600000 (1 hour). | | `normalize_for_speech` | boolean | No | Whether to normalize text (convert numbers, currency) for natural speech. | | `vocab_specialization` | string | No | Vocabulary specialization. Options: general, medical. Default: general. | | `backchannel_frequency` | number | No | Frequency of backchannel interjections. Range: [0, 1], default 0.8 when enabled. | | `begin_message_delay_ms` | integer | No | Delay before agent speaks first message. Range: [0, 5000]. | | `analysis_summary_prompt` | string | No | Custom prompt for generating call summary. Maximum 2000 characters. | | `post_call_analysis_data` | array | No | Custom data extraction fields for post-call analysis. | | `interruption_sensitivity` | number | No | How easily the agent can be interrupted. Range: [0, 1], default 1. | | `post_call_analysis_model` | string | No | LLM model to use for post-call analysis (e.g., gpt-4.1-mini, gpt-4.1, claude-4.5-sonnet). | | `pronunciation_dictionary` | array | No | Custom pronunciation rules using IPA or CMU phonetic notation. | | `signed_url_expiration_ms` | integer | No | Signed URL expiration time in milliseconds. Default: 86400000 (24 hours). | | `end_call_after_silence_ms` | integer | No | Milliseconds of silence before automatically ending the call. Minimum: 10000, default: 600000. | | `analysis_successful_prompt` | string | No | Custom prompt for determining call success. Maximum 2000 characters. | | `enable_dynamic_voice_speed` | boolean | No | Enable dynamic adjustment of voice speed based on context. | | `enable_voicemail_detection` | boolean | No | Whether to detect voicemail entry. | | `voicemail_detection_timeout_ms` | integer | No | Voicemail detection window. Range: [5000, 180000], default: 30000. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a new outbound phone call **Slug:** `RETELLAI_CREATE_A_NEW_OUTBOUND_PHONE_CALL` Initiate 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `metadata` | object | No | 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. | | `to_number` | string | Yes | The number you want to call, in E.164 format. Right now only US numbers are officially supported when using Retell-purchased numbers. | | `from_number` | string | Yes | The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell. | | `override_agent_id` | string | No | 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. | | `ignore_e164_validation` | boolean | No | 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. | | `override_agent_version` | integer | No | For this particular call, set the agent version. Only effective when override_agent_id is set. | | `retell_llm_dynamic_variables` | object | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a new web call **Slug:** `RETELLAI_CREATE_A_NEW_WEB_CALL` The /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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call. | | `metadata` | object | No | 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. | | `agent_version` | integer | No | Specifies which version of the agent to use for this call. If not provided, the latest version is used. | | `retell_llm_dynamic_variables` | object | No | Add optional dynamic variables in key value pairs of string to inject into your Retell LLM prompt and tool descriptions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Batch Test **Slug:** `RETELLAI_CREATE_BATCH_TEST` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `response_engine` | string | Yes | 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. | | `test_case_definition_ids` | array | Yes | Array of test case definition IDs to run. Must contain at least 1 and at most 200 test case IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a new chat session **Slug:** `RETELLAI_CREATE_CHAT` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | The chat agent to use for the call. | | `metadata` | object | No | 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. | | `agent_version` | integer | No | The version of the chat agent to use for the chat. If not provided, will default to latest version. | | `retell_llm_dynamic_variables` | object | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a new chat agent **Slug:** `RETELLAI_CREATE_CHAT_AGENT` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `language` | string | No | Language/dialect for chat operations (e.g., 'en-US', 'es-ES'). Defaults to 'en-US'. | | `is_public` | boolean | No | Whether this chat agent is available for public preview | | `agent_name` | string | No | Chat agent identifier for reference purposes | | `pii_config` | object | No | PII (Personally Identifiable Information) scrubbing configuration | | `webhook_url` | string | No | URL that will receive chat event notifications (e.g., chat started, ended, analyzed) | | `response_engine` | string | Yes | The Response Engine generating agent responses. Required field with type, llm_id, and version. | | `opt_in_signed_url` | boolean | No | Enable signed URLs for public logs access. When enabled, secure time-limited URLs are generated. | | `auto_close_message` | string | No | Message displayed when chat auto-closes after silence period | | `webhook_timeout_ms` | integer | No | Webhook timeout in milliseconds. Defaults to 10,000ms. | | `data_storage_setting` | string | No | Data retention policy for the chat. Options: 'everything', 'everything_except_pii', or 'basic_attributes_only'. | | `analysis_summary_prompt` | string | No | Summary generation guidance for chat analysis. Maximum 2000 characters. | | `post_chat_analysis_data` | array | No | Custom analysis extraction schema for post-chat analysis | | `post_chat_analysis_model` | object | No | LLM model selection for post-chat analysis | | `signed_url_expiration_ms` | integer | No | Signed URL expiration duration in milliseconds. Defaults to 86,400,000ms (24 hours). | | `end_chat_after_silence_ms` | integer | No | Silence duration (in milliseconds) before automatically closing the chat. Minimum value is 360,000ms (6 minutes). | | `analysis_successful_prompt` | string | No | Success evaluation criteria for chat analysis. Maximum 2000 characters. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create chat completion **Slug:** `RETELLAI_CREATE_CHAT_COMPLETION` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chat_id` | string | Yes | Unique identifier of the chat session to create completion for | | `content` | string | Yes | User message content to generate agent chat completion response for | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create conversation flow **Slug:** `RETELLAI_CREATE_CONVERSATION_FLOW` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mcps` | array | No | 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'. | | `nodes` | array | Yes | 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'}}]. | | `tools` | array | No | Custom and built-in function definitions available in the conversation flow. Includes custom tools, end call tools, appointment booking tools, etc. | | `kb_config` | object | No | Knowledge base configuration for retrieval behavior. May include 'top_k' and 'filter_score' parameters. | | `components` | array | No | Reusable sub-flows embedded within the conversation flow. Each component has its own nodes and tools. | | `model_choice` | object | Yes | Model configuration with model name and type. Example: {'model': 'gpt-4o', 'type': 'cascading'}. Required fields: 'model' (string) and 'type' (string). | | `global_prompt` | string | No | System instructions applied across all nodes in the conversation flow. Used to define overall agent behavior and personality. | | `start_node_id` | string | No | ID of the node where execution begins. If not specified, the first node in the nodes array is used. | | `start_speaker` | string ("user" | "agent") | Yes | Who initiates the conversation. Either 'user' or 'agent'. | | `is_transfer_llm` | boolean | No | Whether this conversation flow is used for transfer LLM scenarios. Affects how the flow is processed during call transfers. | | `model_temperature` | number | No | Controls the randomness of the model's responses. Valid range: 0-1. Lower values make responses more deterministic. Default: 0.7. | | `knowledge_base_ids` | array | No | Array of knowledge base IDs for RAG (Retrieval-Augmented Generation). Enables the agent to retrieve information from specified knowledge bases. | | `tool_call_strict_mode` | boolean | No | Whether to use strict mode for tool calls. Only applicable when using certain supported models. | | `default_dynamic_variables` | object | No | Template variables available throughout the flow for personalization. Example: {'company_name': 'Acme Corp', 'support_hours': '9am-5pm'}. | | `begin_tag_display_position` | object | No | Frontend display coordinates for the begin tag. Expected to contain 'x' and 'y' properties for UI positioning. | | `begin_after_user_silence_ms` | integer | No | Milliseconds to wait before agent speaks after user silence. If not set, the agent waits indefinitely for the user to speak. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create conversation flow component **Slug:** `RETELLAI_CREATE_CONVERSATION_FLOW_COMPONENT` Creates 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mcps` | array | No | MCP (Model Context Protocol) server configurations for the component. Enables integration with external MCP-compatible services. | | `name` | string | Yes | Name of the conversation flow component. Used to identify the component. | | `nodes` | array | Yes | 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. | | `tools` | array | No | Custom and system integrations available within the component. Includes custom tools, end call tools, appointment booking tools, and more. | | `start_node_id` | string | No | ID of the node where execution begins. If not specified, the first node in the nodes array is used as the starting point. | | `begin_tag_display_position` | object | No | Frontend display coordinates for the begin tag. Expected to contain x and y properties for positioning in the UI. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a new knowledge base **Slug:** `RETELLAI_CREATE_KNOWLEDGE_BASE` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `knowledge_base_name` | string | Yes | Name of the knowledge base. Must be less than 40 characters. | | `knowledge_base_urls` | array | No | URLs to be scraped and added to the knowledge base. Must be valid URLs. | | `knowledge_base_files` | array | No | Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB. | | `knowledge_base_texts` | array | No | Texts to add to the knowledge base. Array of objects with text and title fields. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Retell LLM Response Engine **Slug:** `RETELLAI_CREATE_RETELL_LLM` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mcps` | array | No | Model Context Protocol (MCP) integrations for extended capabilities. | | `model` | string ("gpt-4.1" | "gpt-4.1-mini" | "claude-4.5-sonnet" | "gemini-2.5-flash") | No | Text LLM model selection for generating responses. | | `states` | array | No | Conversation state definitions with prompts, transitions (edges), and state-specific tools. | | `kb_config` | object | No | Knowledge base configuration for RAG | | `s2s_model` | string ("gpt-4o-realtime" | "gpt-4o-mini-realtime") | No | Speech-to-speech model selection for real-time voice responses. | | `begin_message` | string | No | The first utterance spoken by the agent when the conversation starts. | | `general_tools` | array | No | Predefined tools available to the agent, such as end_call or transfer_call functions. | | `start_speaker` | string ("user" | "agent") | Yes | Determines who initiates the conversation. Either 'user' or 'agent'. | | `general_prompt` | string | No | System prompt applied across all conversation states. Defines agent behavior and personality. | | `starting_state` | string | No | Name of the initial conversation state when using multi-state flows. | | `model_temperature` | number | No | Controls randomness in model responses. Range: [0, 1]. Default is 0 for deterministic output. | | `knowledge_base_ids` | array | No | List of knowledge base IDs for RAG (Retrieval-Augmented Generation) capabilities. | | `model_high_priority` | boolean | No | Enables dedicated resources for lower latency responses. Use for high-priority agents. | | `tool_call_strict_mode` | boolean | No | Enforces strict mode for tool calls to ensure proper function execution. | | `default_dynamic_variables` | object | No | Key-value pairs injected into prompts as variables for dynamic content. | | `begin_after_user_silence_ms` | integer | No | Milliseconds to wait after user stops speaking before agent responds. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Test Case Definition **Slug:** `RETELLAI_CREATE_TEST_CASE_DEFINITION` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Name of the test case definition. | | `metrics` | array | Yes | Array of metric name strings to evaluate the test case. Each metric describes a specific aspect to verify. | | `llm_model` | string | No | Optional LLM model specification to use for evaluation. | | `tool_mocks` | array | No | Optional array of tool mocks to simulate tool responses during testing. | | `user_prompt` | string | Yes | 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` | object | Yes | Response engine configuration. Must include type ('retell-llm' or 'conversation-flow'), the corresponding ID field, and version. | | `dynamic_variables` | object | No | Optional dynamic variables object to inject into the test case prompts as key-value pairs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete agent **Slug:** `RETELLAI_DELETE_AGENT` Deletes an existing agent by its unique identifier. Returns 204 No Content on successful deletion. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique id of the agent to be deleted | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete call **Slug:** `RETELLAI_DELETE_CALL` Delete 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `call_id` | string | Yes | The call id to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete chat agent **Slug:** `RETELLAI_DELETE_CHAT_AGENT` Delete an existing chat agent by its unique identifier. Use when you need to permanently remove a chat agent from the system. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | The unique identifier of the chat agent to delete | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete conversation flow **Slug:** `RETELLAI_DELETE_CONVERSATION_FLOW` Delete a conversation flow and all its versions. Use when you need to permanently remove a conversation flow from the system. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `conversation_flow_id` | string | Yes | Unique id of the conversation flow to be deleted | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete conversation flow component **Slug:** `RETELLAI_DELETE_CONVERSATION_FLOW_COMPONENT` Delete a shared conversation flow component. When deleting a shared component, creates local copies for all linked conversation flows. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `conversation_flow_component_id` | string | Yes | The unique identifier of the conversation flow component to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete knowledge base **Slug:** `RETELLAI_DELETE_KNOWLEDGE_BASE` Delete an existing knowledge base by its unique identifier. Use when you need to permanently remove a knowledge base from the system. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `knowledge_base_id` | string | Yes | The knowledge base id to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete knowledge base source **Slug:** `RETELLAI_DELETE_KNOWLEDGE_BASE_SOURCE` Delete 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `source_id` | string | Yes | The unique identifier of the source to delete from the knowledge base | | `knowledge_base_id` | string | Yes | The unique identifier of the knowledge base to delete source from | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete phone number **Slug:** `RETELLAI_DELETE_PHONE_NUMBER` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone_number` | string | Yes | Phone number to delete in E.164 format (e.g., +14159998888) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Retell LLM **Slug:** `RETELLAI_DELETE_RETELL_LLM` Delete 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `llm_id` | string | Yes | The unique identifier of the Retell LLM to delete | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete test case definition **Slug:** `RETELLAI_DELETE_TEST_CASE_DEFINITION` Delete a test case definition by its unique identifier. Use when you need to permanently remove a test case definition from the system. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `test_case_definition_id` | string | Yes | ID of the test case definition to delete | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### End chat **Slug:** `RETELLAI_END_CHAT` Tool to end an active chat session. Use when you need to terminate an ongoing chat conversation. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chat_id` | string | Yes | Unique id of the chat to be ended | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve details of a specific agent **Slug:** `RETELLAI_GET_AGENT` Retrieve details of a specific agent by its unique identifier. Use when you need to access agent configuration details. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique identifier of the agent to retrieve | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get agent versions **Slug:** `RETELLAI_GET_AGENT_VERSIONS` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | The unique identifier of the agent to retrieve versions for | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get batch test **Slug:** `RETELLAI_GET_BATCH_TEST` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `test_case_batch_job_id` | string | Yes | ID of the batch test job to retrieve | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get chat details **Slug:** `RETELLAI_GET_CHAT` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chat_id` | string | Yes | Unique id of the chat to be retrieved | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve details of a specific chat agent **Slug:** `RETELLAI_GET_CHAT_AGENT` Retrieve details of a specific chat agent by its unique identifier. Use when you need to access chat agent configuration details. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique identifier of the chat agent to retrieve | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get all versions of a chat agent **Slug:** `RETELLAI_GET_CHAT_AGENT_VERSIONS` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | The unique identifier of the chat agent to retrieve versions for | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get concurrency **Slug:** `RETELLAI_GET_CONCURRENCY` Retrieves the current concurrency and concurrency limits for the organization. Use when you need to check concurrent call capacity and availability. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Conversation Flow **Slug:** `RETELLAI_GET_CONVERSATION_FLOW` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `conversation_flow_id` | string | Yes | The unique identifier of the conversation flow to retrieve | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get conversation flow component **Slug:** `RETELLAI_GET_CONVERSATION_FLOW_COMPONENT` Retrieves a shared conversation flow component by its unique identifier. Use when you need to fetch details of a specific conversation flow component. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `conversation_flow_component_id` | string | Yes | The unique identifier of the conversation flow component to retrieve | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get knowledge base **Slug:** `RETELLAI_GET_KNOWLEDGE_BASE` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `knowledge_base_id` | string | Yes | The unique identifier of the knowledge base to retrieve | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve details of a specific Retell LLM **Slug:** `RETELLAI_GET_RETELL_LLM` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `llm_id` | string | Yes | Unique identifier of the Retell LLM Response Engine to be retrieved | | `version` | integer | No | Optional version of the API to use for this request. Defaults to latest version if not specified | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Import phone number **Slug:** `RETELLAI_IMPORT_PHONE_NUMBER` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `nickname` | string | No | User-defined reference name for the phone number (optional). | | `transport` | string | No | Transport protocol for SIP communication. Options: 'TLS', 'TCP', or 'UDP'. Defaults to 'TCP' if not specified. | | `phone_number` | string | Yes | The phone number to import in E.164 format (+country code, then number with no spaces or special characters). Example: '+14157779999' | | `termination_uri` | string | Yes | The termination URI to uniquely identify your elastic SIP trunk. This is used for outbound calls. Example: 'sip.example.com' | | `inbound_agent_id` | string | No | Unique ID of agent to bind to the number for inbound calls. If null, this number will not accept inbound calls. | | `outbound_agent_id` | string | No | 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. | | `inbound_webhook_url` | string | No | Webhook URL for inbound call events and context (optional). | | `inbound_agent_version` | integer | No | Version number of the inbound agent. Defaults to the latest version if not specified. | | `outbound_agent_version` | integer | No | Version number of the outbound agent. Defaults to the latest version if not specified. | | `sip_trunk_auth_password` | string | No | Password for SIP trunk authentication (optional). | | `sip_trunk_auth_username` | string | No | Username for SIP trunk authentication (optional). | | `inbound_allowed_countries` | array | No | List of ISO 3166-1 alpha-2 country codes that are allowed for inbound calls. If empty or null, all countries are allowed. | | `outbound_allowed_countries` | array | No | List of ISO 3166-1 alpha-2 country codes that are allowed for outbound calls. If empty or null, all countries are allowed. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List agents **Slug:** `RETELLAI_LIST_AGENTS` Retrieves a list of all agents associated with the account. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all chats **Slug:** `RETELLAI_LIST_ALL_CHATS` Tool to retrieve a list of all chats associated with the account. Use when you need to view chat history or analyze past conversations. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all phone numbers **Slug:** `RETELLAI_LIST_ALL_PHONE_NUMBERS` Retrieves 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List batch tests **Slug:** `RETELLAI_LIST_BATCH_TESTS` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("retell-llm" | "conversation-flow") | Yes | Type of response engine to filter batch tests | | `llm_id` | string | No | LLM ID (required when type is retell-llm) | | `version` | integer | No | Version of the response engine (defaults to latest if not specified) | | `conversation_flow_id` | string | No | Conversation flow ID (required when type is conversation-flow) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List chat agents **Slug:** `RETELLAI_LIST_CHAT_AGENTS` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 1000. | | `pagination_key` | string | No | 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. | | `pagination_key_version` | integer | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List conversation flow components **Slug:** `RETELLAI_LIST_CONVERSATION_FLOW_COMPONENTS` Retrieves 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List conversation flows **Slug:** `RETELLAI_LIST_CONVERSATION_FLOWS` Tool to list all conversation flows that can be attached to an agent. Use when you need to retrieve available conversation flows for agent configuration. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List knowledge bases **Slug:** `RETELLAI_LIST_KNOWLEDGE_BASES` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Retell LLMs **Slug:** `RETELLAI_LIST_RETELL_LLMS` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 1000, default is 1000 | | `pagination_key` | string | No | The pagination key to continue fetching the next page of LLMs. Represented by a llm id | | `pagination_key_version` | integer | No | Specifies the version of the llm associated with the pagination_key | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List test case definitions **Slug:** `RETELLAI_LIST_TEST_CASE_DEFINITIONS` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("retell-llm" | "conversation-flow") | Yes | Type of response engine. Must be either 'retell-llm' or 'conversation-flow' | | `llm_id` | string | No | LLM ID (required when type is retell-llm) | | `version` | integer | No | Version of the response engine. If not specified, defaults to the latest version | | `conversation_flow_id` | string | No | Conversation flow ID (required when type is conversation-flow) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List test runs **Slug:** `RETELLAI_LIST_TEST_RUNS` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `test_case_batch_job_id` | string | Yes | Unique identifier of the batch test job to retrieve test runs for | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List voices **Slug:** `RETELLAI_LIST_VOICES` List all voices available to the user. Returns voice details including voice_id, name, provider, accent, gender, age, and preview audio URL. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Publish agent **Slug:** `RETELLAI_PUBLISH_AGENT` Publishes 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique id of the agent to be published | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Publish chat agent **Slug:** `RETELLAI_PUBLISH_CHAT_AGENT` Publishes 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique id of the chat agent to be published | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Register phone call **Slug:** `RETELLAI_REGISTER_PHONE_CALL` Register 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | The agent to use for the call. | | `metadata` | object | No | 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` | string ("inbound" | "outbound") | No | Direction of the phone call. Stored for tracking purpose. | | `to_number` | string | No | The number you want to call, in E.164 format. Stored for tracking purpose. | | `from_number` | string | No | The number you own in E.164 format. Stored for tracking purpose. | | `agent_version` | integer | No | The version of the agent to use for the call. | | `agent_override` | object | No | Override configuration for agent, retell LLM, or conversation flow settings for a specific call. | | `retell_llm_dynamic_variables` | object | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve call details **Slug:** `RETELLAI_RETRIEVE_CALL_DETAILS` Tool to retrieve call details with filtering options. Use when you need to fetch call records, analyze call history, or monitor call performance. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | 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` | string ("ascending" | "descending") | No | 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. | | `pagination_key` | string | No | 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` | object | No | Filter criteria for call retrieval | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve call details by id **Slug:** `RETELLAI_RETRIEVE_CALL_DETAILS_BY_ID` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `call_id` | string | Yes | Call Id | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve phone number details **Slug:** `RETELLAI_RETRIEVE_DETAILS_OF_A_SPECIFIC_PHONE_NUMBER` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone_number` | string | Yes | Phone number in E.164 format (e.g., +14158887777). The phone number will be automatically URL-encoded for the API request. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Retrieve details of a specific voice **Slug:** `RETELLAI_RETRIEVE_DETAILS_OF_A_SPECIFIC_VOICE` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `voice_id` | string | Yes | The unique identifier for the voice to retrieve (e.g., 'cartesia-Cleo', '11labs-Adrian') | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search community voice **Slug:** `RETELLAI_SEARCH_COMMUNITY_VOICE` Search for community voices from voice providers. Use when you need to find voices by name, description, or ID, optionally filtering by provider. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `search_query` | string | Yes | Query to find voices by name, description, or ID | | `voice_provider` | string ("elevenlabs" | "cartesia" | "minimax") | No | Provider filter for voices. Options: elevenlabs, cartesia, minimax | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update agent **Slug:** `RETELLAI_UPDATE_AGENT` Update an existing agent's latest draft version. Use when modifying agent configuration, voice settings, or behavior parameters for a Retell AI agent. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `volume` | number | No | Agent speech loudness (range 0-2) | | `agent_id` | string | Yes | Unique identifier for the agent to update | | `language` | string | No | Speech recognition language/dialect | | `voice_id` | string | No | Voice identifier for TTS output | | `agent_name` | string | No | Agent identifier for reference purposes | | `ivr_option` | object | No | Configuration for IVR handling actions | | `pii_config` | object | No | Configuration for PII scrubbing | | `voice_model` | string | No | Model selection (eleven_turbo_v2, sonic-3, gpt-4o-mini-tts, etc.) | | `voice_speed` | number | No | Speech rate adjustment (range 0.5-2) | | `webhook_url` | string | No | Event notification endpoint | | `response_engine` | string | No | Response engine configuration (OneOf: retell-llm, custom-llm, or conversation-flow) | | `voicemail_option` | object | No | Configuration for voicemail handling actions | | `custom_stt_config` | object | No | Custom STT configuration with provider and endpointing | | `user_dtmf_options` | object | No | Configuration for user DTMF input (request) | | `voice_temperature` | number | No | Speech stability control (range 0-2) | | `enable_backchannel` | boolean | No | Enable engagement vocalizations | | `max_call_duration_ms` | integer | No | Call duration cap (60,000-7,200,000ms) | | `post_call_analysis_data` | array | No | Array of analysis data objects for post-call extraction | | `end_call_after_silence_ms` | integer | No | Silence timeout minimum 10,000ms | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update call **Slug:** `RETELLAI_UPDATE_CALL` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `call_id` | string | Yes | The call id of the call to be updated | | `metadata` | object | No | 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` | object | No | Custom attributes for the call | | `data_storage_setting` | string ("everything" | "everything_except_pii" | "basic_attributes_only") | No | Data storage setting for calls | | `override_dynamic_variables` | object | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update chat agent **Slug:** `RETELLAI_UPDATE_CHAT_AGENT` Update an existing chat agent configuration. Use when modifying chat agent settings, response engine, or behavior parameters. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | Unique id of the chat agent to be updated | | `language` | string | No | Supported languages including en-US, es-ES, multi, etc. | | `is_public` | boolean | No | Public agent preview availability | | `agent_name` | string | No | Agent reference name | | `webhook_url` | string | No | Event listener endpoint | | `response_engine` | object | Yes | The response generation engine attached to the agent | | `auto_close_message` | string | No | Message displayed when chat auto-closes | | `data_storage_setting` | string | No | everything, everything_except_pii, or basic_attributes_only | | `end_chat_after_silence_ms` | integer | No | Silence duration threshold (360000-259200000 ms range) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update chat metadata **Slug:** `RETELLAI_UPDATE_CHAT_METADATA` Tool 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chat_id` | string | Yes | The chat id of the chat to be updated. | | `metadata` | object | No | 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` | object | No | Custom attributes for the chat. Values can be strings, numbers, or booleans. | | `data_storage_setting` | string ("everything" | "basic_attributes_only") | No | Data storage settings for chat | | `override_dynamic_variables` | object | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update conversation flow **Slug:** `RETELLAI_UPDATE_CONVERSATION_FLOW` Update an existing conversation flow configuration. Use when modifying conversation flow settings such as model parameters, nodes, tools, or prompt templates. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mcps` | array | No | Model Context Protocol (MCP) server configurations for external integrations | | `nodes` | array | No | Array of conversation nodes that define the flow structure and logic | | `tools` | array | No | Available tools/functions that can be called during the conversation flow | | `version` | integer | No | Specific version of conversation flow to update; defaults to latest if not specified | | `kb_config` | object | No | Knowledge base retrieval configuration settings | | `components` | array | No | Embedded sub-components within the conversation flow | | `model_choice` | object | No | Model choice settings for the conversation flow | | `global_prompt` | string | No | System prompt applied across all nodes in the conversation flow | | `start_node_id` | string | No | Entry point node identifier that determines where the conversation flow begins | | `start_speaker` | string | No | Determines who initiates the conversation; must be 'user' or 'agent' | | `is_transfer_llm` | boolean | No | Flag indicating whether this is a transfer LLM configuration | | `model_temperature` | number | No | Controls response randomness; range 0-1 where 0 is deterministic and 1 is most random | | `knowledge_base_ids` | array | No | Knowledge base IDs for RAG (Retrieval-Augmented Generation) functionality | | `conversation_flow_id` | string | Yes | Unique identifier for the conversation flow to update | | `tool_call_strict_mode` | boolean | No | Enables strict mode for tool calls to enforce stricter validation | | `default_dynamic_variables` | object | No | Pre-configured variables that can be used dynamically throughout the flow | | `begin_after_user_silence_ms` | integer | No | Milliseconds to wait after user silence before agent begins speaking | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update conversation flow component **Slug:** `RETELLAI_UPDATE_CONVERSATION_FLOW_COMPONENT` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mcps` | array | No | MCP server configurations for the component. Each configuration includes name, url, headers, query_params, and timeout_ms. | | `name` | string | No | The component's display name | | `nodes` | array | No | Array of node objects that comprise the component structure. Each node contains an id, type, and instruction configuration. | | `tools` | array | No | Array of tool configurations available within the component. Each tool includes type, name, description, and endpoint details. | | `start_node_id` | string | No | Identifier of the initial node in the component flow | | `begin_tag_display_position` | object | No | Frontend display coordinates for the begin tag in the visual editor | | `conversation_flow_component_id` | string | Yes | The unique identifier of the conversation flow component to update | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update phone number configuration **Slug:** `RETELLAI_UPDATE_PHONE_NUMBER` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `nickname` | string | No | Custom reference name for the phone number | | `transport` | string ("TLS" | "TCP" | "UDP") | No | SIP transport protocol | | `phone_number` | string | Yes | E.164 format phone number (e.g., +14157774444) | | `auth_password` | string | No | SIP authentication password | | `auth_username` | string | No | SIP authentication username | | `termination_uri` | string | No | SIP termination address | | `inbound_agent_id` | string | No | Agent ID for receiving calls, or null to prevent inbound calls | | `outbound_agent_id` | string | No | Agent ID for making outbound calls | | `inbound_webhook_url` | string | No | Webhook endpoint URL for inbound call notifications | | `inbound_agent_version` | integer | No | Inbound agent version number | | `outbound_agent_version` | integer | No | Outbound agent version number | | `inbound_allowed_countries` | array | No | ISO 3166-1 alpha-2 country codes allowed for inbound calls | | `outbound_allowed_countries` | array | No | ISO 3166-1 alpha-2 country codes allowed for outbound calls | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Retell LLM Response Engine **Slug:** `RETELLAI_UPDATE_RETELL_LLM` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mcps` | array | No | Model Context Protocol (MCP) integrations for extended capabilities. | | `model` | string ("gpt-4.1" | "gpt-4.1-mini" | "gpt-5" | "claude-4.5-sonnet" | "gemini-2.5-flash") | No | Text LLM model selection for generating responses. | | `llm_id` | string | Yes | Unique identifier of the Retell LLM Response Engine to update. | | `states` | array | No | Conversation state definitions with prompts, transitions (edges), and state-specific tools. | | `version` | integer | No | Version number of the LLM configuration. | | `kb_config` | object | No | Knowledge base configuration for RAG | | `s2s_model` | string ("gpt-4o-realtime" | "gpt-4o-mini-realtime") | No | Speech-to-speech model selection for real-time voice responses. | | `begin_message` | string | No | The first utterance spoken by the agent when the conversation starts. | | `general_tools` | array | No | Predefined tools available to the agent, such as end_call or transfer_call functions. | | `start_speaker` | string ("user" | "agent") | No | Determines who initiates the conversation. Either 'user' or 'agent'. | | `general_prompt` | string | No | System prompt applied across all conversation states. Defines agent behavior and personality. | | `starting_state` | string | No | Name of the initial conversation state when using multi-state flows. | | `model_temperature` | number | No | Controls randomness in model responses. Range: [0, 1]. Lower values are more deterministic. | | `knowledge_base_ids` | array | No | List of knowledge base IDs for RAG (Retrieval-Augmented Generation) capabilities. | | `model_high_priority` | boolean | No | Enables dedicated resources for lower latency responses. Use for high-priority agents. | | `tool_call_strict_mode` | boolean | No | Enforces strict mode for tool calls to ensure proper function execution. | | `default_dynamic_variables` | object | No | Key-value pairs injected into prompts as variables for dynamic content. | | `begin_after_user_silence_ms` | integer | No | Milliseconds to wait after user stops speaking before agent responds. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update test case definition **Slug:** `RETELLAI_UPDATE_TEST_CASE_DEFINITION` Update a test case definition for agent testing. Use when modifying test scenarios, metrics, or mock configurations for Retell AI agent validation. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | Name of the test case definition | | `metrics` | array | No | Array of metric names to evaluate | | `llm_model` | 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") | No | Available LLM models for agents | | `tool_mocks` | array | No | Mock tool calls for testing | | `user_prompt` | string | No | User prompt to simulate in the test case | | `response_engine` | string | No | Response engine for test cases. Custom LLM is not supported. | | `dynamic_variables` | object | No | Dynamic variables to inject into the response engine | | `test_case_definition_id` | string | Yes | ID of the test case definition to update | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not |