---
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 — 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` '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' | 'th-TH' | 'vi-VN' | 'ro-RO' | 'bg-BG' | 'ca-ES' | 'da-DK' | 'fi-FI' | 'el-GR' | 'hu-HU' | 'id-ID' | 'no-NO' | 'sk-SK' | 'sv-SE' | 'lt-LT' | 'lv-LV' | 'cs-CZ' | 'multi' — Specifies what language (and dialect) the chat will operate in. For instance, selecting `en-GB` optimizes for British English. If unset, will use default value `en-US`. Select `multi` for multilingual support, currently this supports Spanish and English.
  - `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` AnalysisData[], 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
      - 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.
      - 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.
      - BooleanAnalysisData
        - `type` 'boolean', required — Type of the variable to extract.
        - `name` string, required — Name of the variable.
        - `description` string, required — Description of the variable.
      - NumberAnalysisData
        - `type` 'number', required — Type of the variable to extract.
        - `name` string, required — Name of the variable.
        - `description` string, required — Description of the variable.
  - `post_chat_analysis_model` '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' | '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.
  - `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.
  - `is_public` boolean, nullable — Whether the agent is public. When set to true, the agent is available for public agent preview link.

## 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.
  - `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 — 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` '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' | 'th-TH' | 'vi-VN' | 'ro-RO' | 'bg-BG' | 'ca-ES' | 'da-DK' | 'fi-FI' | 'el-GR' | 'hu-HU' | 'id-ID' | 'no-NO' | 'sk-SK' | 'sv-SE' | 'lt-LT' | 'lv-LV' | 'cs-CZ' | 'multi' — Specifies what language (and dialect) the chat will operate in. For instance, selecting `en-GB` optimizes for British English. If unset, will use default value `en-US`. Select `multi` for multilingual support, currently this supports Spanish and English.
  - `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` AnalysisData[], 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
      - 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.
      - 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.
      - BooleanAnalysisData
        - `type` 'boolean', required — Type of the variable to extract.
        - `name` string, required — Name of the variable.
        - `description` string, required — Description of the variable.
      - NumberAnalysisData
        - `type` 'number', required — Type of the variable to extract.
        - `name` string, required — Name of the variable.
        - `description` string, required — Description of the variable.
  - `post_chat_analysis_model` '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' | '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.
  - `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.
  - `is_public` boolean, nullable — Whether the agent is public. When set to true, the agent is available for public agent preview link.
  - `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

## Changes

- **2026-02-23** `bcff6899fa2a` — 4 info
  - added the new optional request property `allOf[#/components/schemas/ChatAgentRequest]/analysis_user_sentiment_prompt`
  - added the new optional request property `allOf[#/components/schemas/ChatAgentRequest]/data_storage_retention_days`
  - added the optional property `allOf[#/components/schemas/ChatAgentRequest]/analysis_user_sentiment_prompt` to the response with the `201` status
  - added the optional property `allOf[#/components/schemas/ChatAgentRequest]/data_storage_retention_days` to the response with the `201` status
- **2026-02-11** `076d0088c7ed` — 1 warning, 1 info
  - added the new `cs-CZ` enum value to the `allOf[#/components/schemas/ChatAgentRequest]/language` response property for the response status `201`
  - added the new `cs-CZ` enum value to the request property `allOf[#/components/schemas/ChatAgentRequest]/language`
- **2026-02-10** `0bf5cea5dfcc` — 2 info
  - added the new optional request property `allOf[#/components/schemas/ChatAgentRequest]/webhook_events`
  - added the optional property `allOf[#/components/schemas/ChatAgentRequest]/webhook_events` to the response with the `201` status
- **2026-02-06** `dfad228ab4a4` — 2 info
  - added the new optional request property `allOf[#/components/schemas/ChatAgentRequest]/guardrail_config`
  - added the optional property `allOf[#/components/schemas/ChatAgentRequest]/guardrail_config` to the response with the `201` status

[Change history](https://skmtc.dev/retellai/apis/retell-sdk/changes/create-chat-agent/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/retellai/retell-sdk/revisions/bcff6899fa2a/schema)