--- title: "POST /create-chat-agent" method: POST path: "/create-chat-agent" --- # POST /create-chat-agent `POST /create-chat-agent` Create a new chat agent ## Request body - object - `response_engine` union, required - ResponseEngineRetellLm - `type` 'retell-llm', required — type of the Response Engine. - `llm_id` string, required — id of the Retell LLM Response Engine. - `version` number, nullable — Version of the Retell LLM Response Engine. - ResponseEngineCustomLm - `type` 'custom-llm', required — type of the Response Engine. - `llm_websocket_url` string, required — LLM websocket url of the custom LLM. - ResponseEngineConversationFlow - `type` 'conversation-flow', required — type of the Response Engine. - `conversation_flow_id` string, required — ID of the Conversation Flow Response Engine. - `version` number, nullable — Version of the Conversation Flow Response Engine. - `agent_name` string, nullable — The name of the chat agent. Only used for your own reference. - `auto_close_message` string, nullable — Message to display when the chat is automatically closed. - `end_chat_after_silence_ms` integer, nullable — If users stay silent for a period after agent speech, end the chat. The minimum value allowed is 120,000 ms (2 minutes). The maximum value allowed is 259,200,000 ms (72 hours). By default, this is set to 3,600,000 (1 hour). - `language` union — Specifies what language(s) the agent will operate in. Accepts either a single scalar locale (e.g. `en-US`), the legacy scalar value `multi` for multilingual support, or an array of concrete locale codes for explicit multi-locale selection (e.g. `["en-US","es-ES"]`). The array form must contain concrete locale codes only — the `multi` value is valid only as the scalar legacy form and must not appear inside an array. Single-element arrays are normalized to the equivalent scalar on output. If unset, defaults to `en-US`. - union — Legacy single-string language format. Accepts any concrete locale from `Language`, plus the special scalar value `multi` for multilingual support. If unset, will use default value `en-US`. - 'en-US' | 'en-IN' | 'en-GB' | 'en-AU' | 'en-NZ' | 'de-DE' | 'es-ES' | 'es-419' | 'hi-IN' | 'fr-FR' | 'fr-CA' | 'ja-JP' | 'pt-PT' | 'pt-BR' | 'zh-CN' | 'ru-RU' | 'it-IT' | 'ko-KR' | 'nl-NL' | 'nl-BE' | 'pl-PL' | 'tr-TR' | 'vi-VN' | 'ro-RO' | 'bg-BG' | 'ca-ES' | 'th-TH' | 'da-DK' | 'fi-FI' | 'el-GR' | 'hu-HU' | 'id-ID' | 'no-NO' | 'sk-SK' | 'sv-SE' | 'lt-LT' | 'lv-LV' | 'cs-CZ' | 'ms-MY' | 'af-ZA' | 'ar-SA' | 'az-AZ' | 'bs-BA' | 'cy-GB' | 'fa-IR' | 'fil-PH' | 'gl-ES' | 'he-IL' | 'hr-HR' | 'hy-AM' | 'is-IS' | 'kk-KZ' | 'kn-IN' | 'mk-MK' | 'mr-IN' | 'ne-NP' | 'sl-SI' | 'sr-RS' | 'sw-KE' | 'ta-IN' | 'ur-IN' | 'yue-CN' | 'uk-UA' — Specifies what language (and dialect) the agent will operate in. For instance, selecting `en-GB` optimizes speech recognition for British English and indexes knowledge bases with English. If unset, will use default value `en-US`. This enum does not include the legacy scalar value `multi`. - 'multi' - Language[] - `webhook_url` string, nullable — The webhook for agent to listen to chat events. See what events it would get at [webhook doc](/features/webhook). If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to `null` to remove webhook url from this agent. - `webhook_events` string[], nullable — Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed. - `webhook_timeout_ms` integer — The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply. - `data_storage_setting` 'everything' | 'everything_except_pii' | 'basic_attributes_only', nullable — Controls what data is stored for this agent. "everything" stores all data including transcripts and recordings. "everything_except_pii" stores data but excludes PII when possible based on PII configuration. "basic_attributes_only" stores only basic metadata. If not set, defaults to "everything". - `data_storage_retention_days` integer, nullable — Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion). - `opt_in_signed_url` boolean — Whether this agent opts in to signed url for public log. If not set, default value of false will apply. - `signed_url_expiration_ms` integer, nullable — The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply. - `post_chat_analysis_data` PostChatAnalysisData[], nullable — Post chat analysis data to extract from the chat. This data will augment the pre-defined variables extracted in the chat analysis. This will be available after the chat ends. - union — Post-chat analysis item (custom data or chat preset). Use for chat agent post_chat_analysis_data; validates only chat presets (chat_summary, chat_successful, user_sentiment). - union - StringAnalysisData - `type` 'string', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `examples` string[] — Examples of the variable value to teach model the style and syntax. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - EnumAnalysisData - `type` 'enum', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `choices` string[], required — The possible values of the variable, must be non empty array. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - BooleanAnalysisData - `type` 'boolean', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - NumberAnalysisData - `type` 'number', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - ChatPresetAnalysisData — System preset for post-chat analysis (chat agents). Use in post_chat_analysis_data to override prompts or mark fields optional. - `type` 'system-presets', required — Identifies this item as a system preset. - `name` 'chat_summary' | 'chat_successful' | 'user_sentiment', required — Preset identifier for chat agent analysis. - `description` string — Prompt or description for this preset. - `required` boolean — If false, this field is optional in the analysis. If true or unset, the field is required. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. - `post_chat_analysis_model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' | 'null', nullable — Available LLM models for agents. - `analysis_successful_prompt` string, nullable — The prompt to use for post call analysis to evaluate whether the call is successful. Set to null to use the default prompt. - `analysis_summary_prompt` string, nullable — The prompt to use for post call analysis to summarize the call. Set to null to use the default prompt. - `analysis_user_sentiment_prompt` string, nullable — Prompt to guide how the post chat analysis should evaluate user sentiment. When unset, the default system prompt is used. Set to null to use the default prompt. - `pii_config` PIIConfig - `mode` 'post_call', required — The processing mode for PII scrubbing. Currently only post-call is supported. - `categories` string[], required — List of PII categories to scrub from transcripts and recordings. PII redaction is only active when this list is non-empty; an empty array means no PII scrubbing is performed. - `guardrail_config` GuardrailConfig - `output_topics` string[], nullable — Selected prohibited agent topic categories to check. When agent messages contain these topics, they will be replaced with a placeholder message. - `input_topics` string[], nullable — Selected prohibited user topic categories to check. When user messages contain these topics, the agent will respond with a placeholder message instead of processing the request. - `handbook_config` ChatHandbookConfig — Behavior presets for chat agents. Voice-only presets are excluded. - `default_personality` boolean — Professional call center rep baseline. - `high_empathy` boolean — Warm acknowledgment of caller concerns. - `ai_disclosure` boolean — When asked, acknowledge being a virtual assistant. - `scope_boundaries` boolean — Stay within prompt/context scope, don't invent details. - `timezone` string, nullable — IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set. ## Response `201` Successfully created a new chat agent. - ChatAgentResponse - `agent_id` string, required — Unique id of chat agent. - `version` integer — The version of the chat agent. - `base_version` integer, nullable — Version that this draft was based on. Null for initial versions. - `assigned_tags` string[] — Tags assigned to this chat agent version. Preferred tag is listed first. - `is_published` boolean — Whether the chat agent is published. - `response_engine` union - ResponseEngineRetellLm - `type` 'retell-llm', required — type of the Response Engine. - `llm_id` string, required — id of the Retell LLM Response Engine. - `version` number, nullable — Version of the Retell LLM Response Engine. - ResponseEngineCustomLm - `type` 'custom-llm', required — type of the Response Engine. - `llm_websocket_url` string, required — LLM websocket url of the custom LLM. - ResponseEngineConversationFlow - `type` 'conversation-flow', required — type of the Response Engine. - `conversation_flow_id` string, required — ID of the Conversation Flow Response Engine. - `version` number, nullable — Version of the Conversation Flow Response Engine. - `agent_name` string, nullable — The name of the chat agent. Only used for your own reference. - `auto_close_message` string, nullable — Message to display when the chat is automatically closed. - `end_chat_after_silence_ms` integer, nullable — If users stay silent for a period after agent speech, end the chat. The minimum value allowed is 120,000 ms (2 minutes). The maximum value allowed is 259,200,000 ms (72 hours). By default, this is set to 3,600,000 (1 hour). - `language` union — Specifies what language(s) the agent will operate in. Accepts either a single scalar locale (e.g. `en-US`), the legacy scalar value `multi` for multilingual support, or an array of concrete locale codes for explicit multi-locale selection (e.g. `["en-US","es-ES"]`). The array form must contain concrete locale codes only — the `multi` value is valid only as the scalar legacy form and must not appear inside an array. Single-element arrays are normalized to the equivalent scalar on output. If unset, defaults to `en-US`. - union — Legacy single-string language format. Accepts any concrete locale from `Language`, plus the special scalar value `multi` for multilingual support. If unset, will use default value `en-US`. - 'en-US' | 'en-IN' | 'en-GB' | 'en-AU' | 'en-NZ' | 'de-DE' | 'es-ES' | 'es-419' | 'hi-IN' | 'fr-FR' | 'fr-CA' | 'ja-JP' | 'pt-PT' | 'pt-BR' | 'zh-CN' | 'ru-RU' | 'it-IT' | 'ko-KR' | 'nl-NL' | 'nl-BE' | 'pl-PL' | 'tr-TR' | 'vi-VN' | 'ro-RO' | 'bg-BG' | 'ca-ES' | 'th-TH' | 'da-DK' | 'fi-FI' | 'el-GR' | 'hu-HU' | 'id-ID' | 'no-NO' | 'sk-SK' | 'sv-SE' | 'lt-LT' | 'lv-LV' | 'cs-CZ' | 'ms-MY' | 'af-ZA' | 'ar-SA' | 'az-AZ' | 'bs-BA' | 'cy-GB' | 'fa-IR' | 'fil-PH' | 'gl-ES' | 'he-IL' | 'hr-HR' | 'hy-AM' | 'is-IS' | 'kk-KZ' | 'kn-IN' | 'mk-MK' | 'mr-IN' | 'ne-NP' | 'sl-SI' | 'sr-RS' | 'sw-KE' | 'ta-IN' | 'ur-IN' | 'yue-CN' | 'uk-UA' — Specifies what language (and dialect) the agent will operate in. For instance, selecting `en-GB` optimizes speech recognition for British English and indexes knowledge bases with English. If unset, will use default value `en-US`. This enum does not include the legacy scalar value `multi`. - 'multi' - Language[] - `webhook_url` string, nullable — The webhook for agent to listen to chat events. See what events it would get at [webhook doc](/features/webhook). If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to `null` to remove webhook url from this agent. - `webhook_events` string[], nullable — Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed. - `webhook_timeout_ms` integer — The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply. - `data_storage_setting` 'everything' | 'everything_except_pii' | 'basic_attributes_only', nullable — Controls what data is stored for this agent. "everything" stores all data including transcripts and recordings. "everything_except_pii" stores data but excludes PII when possible based on PII configuration. "basic_attributes_only" stores only basic metadata. If not set, defaults to "everything". - `data_storage_retention_days` integer, nullable — Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion). - `opt_in_signed_url` boolean — Whether this agent opts in to signed url for public log. If not set, default value of false will apply. - `signed_url_expiration_ms` integer, nullable — The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply. - `post_chat_analysis_data` PostChatAnalysisData[], nullable — Post chat analysis data to extract from the chat. This data will augment the pre-defined variables extracted in the chat analysis. This will be available after the chat ends. - union — Post-chat analysis item (custom data or chat preset). Use for chat agent post_chat_analysis_data; validates only chat presets (chat_summary, chat_successful, user_sentiment). - union - StringAnalysisData - `type` 'string', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `examples` string[] — Examples of the variable value to teach model the style and syntax. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - EnumAnalysisData - `type` 'enum', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `choices` string[], required — The possible values of the variable, must be non empty array. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - BooleanAnalysisData - `type` 'boolean', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - NumberAnalysisData - `type` 'number', required — Type of the variable to extract. - `name` string, required — Name of the variable. - `description` string, required — Description of the variable. - `required` boolean — Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. - ChatPresetAnalysisData — System preset for post-chat analysis (chat agents). Use in post_chat_analysis_data to override prompts or mark fields optional. - `type` 'system-presets', required — Identifies this item as a system preset. - `name` 'chat_summary' | 'chat_successful' | 'user_sentiment', required — Preset identifier for chat agent analysis. - `description` string — Prompt or description for this preset. - `required` boolean — If false, this field is optional in the analysis. If true or unset, the field is required. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. - `post_chat_analysis_model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' | 'null', nullable — Available LLM models for agents. - `analysis_successful_prompt` string, nullable — The prompt to use for post call analysis to evaluate whether the call is successful. Set to null to use the default prompt. - `analysis_summary_prompt` string, nullable — The prompt to use for post call analysis to summarize the call. Set to null to use the default prompt. - `analysis_user_sentiment_prompt` string, nullable — Prompt to guide how the post chat analysis should evaluate user sentiment. When unset, the default system prompt is used. Set to null to use the default prompt. - `pii_config` PIIConfig - `mode` 'post_call', required — The processing mode for PII scrubbing. Currently only post-call is supported. - `categories` string[], required — List of PII categories to scrub from transcripts and recordings. PII redaction is only active when this list is non-empty; an empty array means no PII scrubbing is performed. - `guardrail_config` GuardrailConfig - `output_topics` string[], nullable — Selected prohibited agent topic categories to check. When agent messages contain these topics, they will be replaced with a placeholder message. - `input_topics` string[], nullable — Selected prohibited user topic categories to check. When user messages contain these topics, the agent will respond with a placeholder message instead of processing the request. - `handbook_config` ChatHandbookConfig — Behavior presets for chat agents. Voice-only presets are excluded. - `default_personality` boolean — Professional call center rep baseline. - `high_empathy` boolean — Warm acknowledgment of caller concerns. - `ai_disclosure` boolean — When asked, acknowledge being a virtual assistant. - `scope_boundaries` boolean — Stay within prompt/context scope, don't invent details. - `timezone` string, nullable — IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set. - `last_modification_timestamp` integer, required — Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `402` — Payment Required - `500` — Internal Server Error --- [API](https://skmtc.net/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.net/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/retellai/retell-sdk/versions/2a182bedbfc5/schema)