Skip to main content
PATCH
/
update-chat-agent
/
{agent_id}
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const chatAgentResponse = await client.chatAgent.update('16b980523634a6dc504898cda492e939');

console.log(chatAgentResponse.agent_id);
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "last_modification_timestamp": 1703413636133,
  "version": 0,
  "base_version": 12,
  "assigned_tags": [
    "<string>"
  ],
  "is_published": false,
  "agent_name": "Jarvis",
  "auto_close_message": "Thank you for chatting. The conversation has ended.",
  "end_chat_after_silence_ms": 3600000,
  "language": "en-US",
  "webhook_url": "https://webhook-url-here",
  "webhook_events": [
    "chat_started"
  ],
  "webhook_timeout_ms": 10000,
  "data_storage_setting": "everything",
  "data_storage_retention_days": 30,
  "opt_in_signed_url": true,
  "signed_url_expiration_ms": 86400000,
  "post_chat_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ],
      "required": true,
      "conditional_prompt": "<string>"
    }
  ],
  "post_chat_analysis_model": "gpt-4.1-mini",
  "analysis_successful_prompt": "The agent finished the task and the call was complete without being cutoff.",
  "analysis_summary_prompt": "Summarize the call in a few sentences.",
  "analysis_user_sentiment_prompt": "Evaluate the user's sentiment based on their tone and satisfaction level.",
  "pii_config": {
    "mode": "post_call",
    "categories": []
  },
  "guardrail_config": {
    "output_topics": [
      "harassment"
    ],
    "input_topics": [
      "platform_integrity_jailbreaking"
    ]
  },
  "handbook_config": {
    "default_personality": true,
    "high_empathy": true,
    "ai_disclosure": true,
    "scope_boundaries": true
  },
  "timezone": "America/New_York",
  "is_public": false
}

Documentation Index

Fetch the complete documentation index at: https://docs.retellai.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Path Parameters

​
agent_id
string
required

Unique id of the chat agent to be updated.

Minimum string length: 1
Example:

"16b980523634a6dc504898cda492e939"

Query Parameters

​
version

Optional version of the API to use for this request. Default to latest version. Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version (or latest) is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.

Required range: x >= 0
Example:

1

Body

application/json
​
response_engine
object

The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent.

Example:
{
  "type": "retell-llm",
  "llm_id": "llm_234sdertfsdsfsdf",
  "version": 0
}
​
agent_name
string | null

The name of the chat agent. Only used for your own reference.

Example:

"Jarvis"

​
auto_close_message
string | null

Message to display when the chat is automatically closed.

Example:

"Thank you for chatting. The conversation has ended."

​
end_chat_after_silence_ms
integer | null

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).

Example:

3600000

​
language

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.

Available options:
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
Example:

"en-US"

​
webhook_url
string | null

The webhook for agent to listen to chat events. See what events it would get at webhook doc. 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.

Example:

"https://webhook-url-here"

​
webhook_events
enum<string>[] | null

Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed.

Available options:
chat_started,
chat_ended,
chat_analyzed,
transcript_updated
​
webhook_timeout_ms
integer

The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply.

Example:

10000

​
data_storage_setting
enum<string> | null

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".

Available options:
everything,
everything_except_pii,
basic_attributes_only
Example:

"everything"

​
data_storage_retention_days
integer | null

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).

Required range: 1 <= x <= 730
Example:

30

​
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.

Example:

true

​
signed_url_expiration_ms
integer | null

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.

Example:

86400000

​
post_chat_analysis_data
object[] | null

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.

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).

​
post_chat_analysis_model
enum<string> | null

The model to use for post chat analysis. Default to gpt-4.1.

Available options:
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
Example:

"gpt-4.1-mini"

​
analysis_successful_prompt
string | null

The prompt to use for post call analysis to evaluate whether the call is successful. Set to null to use the default prompt.

Example:

"The agent finished the task and the call was complete without being cutoff."

​
analysis_summary_prompt
string | null

The prompt to use for post call analysis to summarize the call. Set to null to use the default prompt.

Example:

"Summarize the call in a few sentences."

​
analysis_user_sentiment_prompt
string | null

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.

Maximum string length: 2000
Example:

"Evaluate the user's sentiment based on their tone and satisfaction level."

​
pii_config
object

Configuration for PII scrubbing from transcripts and recordings.

​
guardrail_config
object

Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input.

​
handbook_config
object

Toggle behavior presets on/off to influence agent response style and behaviors. Voice-only presets are not available for chat agents.

​
timezone
string | null

IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set.

Example:

"America/New_York"

​
is_public
boolean | null

Whether the agent is public. When set to true, the agent is available for public agent preview link.

Example:

false

Response

Successfully updated the chat agent.

​
agent_id
string
required

Unique id of chat agent.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
response_engine
object
required

The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent.

Example:
{
  "type": "retell-llm",
  "llm_id": "llm_234sdertfsdsfsdf",
  "version": 0
}
​
last_modification_timestamp
integer
required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example:

1703413636133

​
version
integer

The version of the chat agent.

Example:

0

​
base_version
integer | null

Version that this draft was based on. Null for initial versions.

Example:

12

​
assigned_tags
string[]

Tags assigned to this chat agent version. Preferred tag is listed first.

​
is_published
boolean

Whether the chat agent is published.

Example:

false

​
agent_name
string | null

The name of the chat agent. Only used for your own reference.

Example:

"Jarvis"

​
auto_close_message
string | null

Message to display when the chat is automatically closed.

Example:

"Thank you for chatting. The conversation has ended."

​
end_chat_after_silence_ms
integer | null

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).

Example:

3600000

​
language

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.

Available options:
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
Example:

"en-US"

​
webhook_url
string | null

The webhook for agent to listen to chat events. See what events it would get at webhook doc. 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.

Example:

"https://webhook-url-here"

​
webhook_events
enum<string>[] | null

Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed.

Available options:
chat_started,
chat_ended,
chat_analyzed,
transcript_updated
​
webhook_timeout_ms
integer

The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply.

Example:

10000

​
data_storage_setting
enum<string> | null

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".

Available options:
everything,
everything_except_pii,
basic_attributes_only
Example:

"everything"

​
data_storage_retention_days
integer | null

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).

Required range: 1 <= x <= 730
Example:

30

​
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.

Example:

true

​
signed_url_expiration_ms
integer | null

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.

Example:

86400000

​
post_chat_analysis_data
object[] | null

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.

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).

​
post_chat_analysis_model
enum<string> | null

The model to use for post chat analysis. Default to gpt-4.1.

Available options:
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
Example:

"gpt-4.1-mini"

​
analysis_successful_prompt
string | null

The prompt to use for post call analysis to evaluate whether the call is successful. Set to null to use the default prompt.

Example:

"The agent finished the task and the call was complete without being cutoff."

​
analysis_summary_prompt
string | null

The prompt to use for post call analysis to summarize the call. Set to null to use the default prompt.

Example:

"Summarize the call in a few sentences."

​
analysis_user_sentiment_prompt
string | null

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.

Maximum string length: 2000
Example:

"Evaluate the user's sentiment based on their tone and satisfaction level."

​
pii_config
object

Configuration for PII scrubbing from transcripts and recordings.

​
guardrail_config
object

Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input.

​
handbook_config
object

Toggle behavior presets on/off to influence agent response style and behaviors. Voice-only presets are not available for chat agents.

​
timezone
string | null

IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set.

Example:

"America/New_York"

​
is_public
boolean | null

Whether the agent is public. When set to true, the agent is available for public agent preview link.

Example:

false