Skip to main content
POST
/
create-chat-agent
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const chatAgentResponse = await client.chatAgent.create({
  response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' },
});

console.log(chatAgentResponse.agent_id);
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "version": 0,
  "is_published": false,
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "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_timeout_ms": 10000,
  "data_storage_setting": "everything",
  "opt_in_signed_url": true,
  "post_chat_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ]
    }
  ],
  "post_chat_analysis_model": "gpt-4.1-mini",
  "pii_config": {
    "mode": "post_call",
    "categories": []
  },
  "last_modification_timestamp": 1703413636133
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
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.

  • Option 1
  • Option 2
  • Option 3
​
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

If users stay silent for a period after agent speech, end the chat. The minimum value allowed is 360,000 ms (0.1 hours). 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
enum<string>

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.

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,
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,
multi
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_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"

​
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

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

  • Option 1
  • Option 2
  • Option 3
  • Option 4
​
post_chat_analysis_model
enum<string>

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

Available options:
gpt-4o,
gpt-4o-mini,
gpt-4.1,
gpt-4.1-mini,
gpt-4.1-nano,
gpt-5,
gpt-5.1,
gpt-5-mini,
gpt-5-nano,
claude-4.5-sonnet,
claude-4.0-sonnet,
claude-3.7-sonnet,
claude-3.5-haiku,
gemini-2.0-flash,
gemini-2.0-flash-lite,
gemini-2.5-flash,
gemini-2.5-flash-lite
Example:

"gpt-4.1-mini"

​
pii_config
object

Configuration for PII scrubbing from transcripts and recordings.

Response

Successfully created a new chat agent.

​
agent_id
string
required

Unique id of chat agent.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
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

​
is_published
boolean

Whether the chat agent is published.

Example:

false

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

  • Option 1
  • Option 2
  • Option 3
​
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

If users stay silent for a period after agent speech, end the chat. The minimum value allowed is 360,000 ms (0.1 hours). 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
enum<string>

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.

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,
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,
multi
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_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"

​
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

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

  • Option 1
  • Option 2
  • Option 3
  • Option 4
​
post_chat_analysis_model
enum<string>

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

Available options:
gpt-4o,
gpt-4o-mini,
gpt-4.1,
gpt-4.1-mini,
gpt-4.1-nano,
gpt-5,
gpt-5.1,
gpt-5-mini,
gpt-5-nano,
claude-4.5-sonnet,
claude-4.0-sonnet,
claude-3.7-sonnet,
claude-3.5-haiku,
gemini-2.0-flash,
gemini-2.0-flash-lite,
gemini-2.5-flash,
gemini-2.5-flash-lite
Example:

"gpt-4.1-mini"

​
pii_config
object

Configuration for PII scrubbing from transcripts and recordings.