POST
/
create-agent
import Retell from 'retell-sdk';

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

async function main() {
  const agentResponse = await client.agent.create({
    response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' },
    voice_id: '11labs-Adrian',
  });

  console.log(agentResponse.agent_id);
}

main();
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "agent_name": "Jarvis",
  "version": 0,
  "voice_id": "11labs-Adrian",
  "voice_model": "eleven_turbo_v2",
  "fallback_voice_ids": [
    "openai-Alloy",
    "deepgram-Angus"
  ],
  "voice_temperature": 1,
  "voice_speed": 1,
  "volume": 1,
  "responsiveness": 1,
  "interruption_sensitivity": 1,
  "enable_backchannel": true,
  "backchannel_frequency": 0.9,
  "backchannel_words": [
    "yeah",
    "uh-huh"
  ],
  "reminder_trigger_ms": 10000,
  "reminder_max_count": 2,
  "ambient_sound": "coffee-shop",
  "ambient_sound_volume": 1,
  "language": "en-US",
  "webhook_url": "https://webhook-url-here",
  "boosted_keywords": [
    "retell",
    "kroger"
  ],
  "enable_transcription_formatting": true,
  "opt_out_sensitive_data_storage": true,
  "pronunciation_dictionary": [
    {
      "word": "actually",
      "alphabet": "ipa",
      "phoneme": "ˈæktʃuəli"
    }
  ],
  "normalize_for_speech": true,
  "end_call_after_silence_ms": 600000,
  "max_call_duration_ms": 3600000,
  "enable_voicemail_detection": true,
  "voicemail_message": "Hi, please give us a callback.",
  "voicemail_detection_timeout_ms": 30000,
  "post_call_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ]
    }
  ],
  "post_call_analysis_model": "gpt-4o-mini",
  "begin_message_delay_ms": 1000,
  "ring_duration_ms": 30000,
  "stt_mode": "fast",
  "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.

​
voice_id
string
required

Unique voice id used for the agent. Find list of available voices and their preview in Dashboard.

Example:

"11labs-Adrian"

​
agent_name
string | null

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

Example:

"Jarvis"

​
version
number | null

Version of the agent.

Example:

0

​
voice_model
enum<string> | null

Optionally set the voice model used for the selected voice. Currently only elevenlab voices have voice model selections. Set to null to remove voice model selection, and default ones will apply. Check out the dashboard for details on each voice model.

Available options:
eleven_turbo_v2,
eleven_flash_v2,
eleven_turbo_v2_5,
eleven_flash_v2_5,
eleven_multilingual_v2,
Play3.0-mini,
PlayDialog
​
fallback_voice_ids
string[] | null

When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent.

Example:
["openai-Alloy", "deepgram-Angus"]
​
voice_temperature
number

Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Currently this setting only applies to 11labs voices. If unset, default value 1 will apply.

Example:

1

​
voice_speed
number

Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply.

Example:

1

​
volume
number

If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply.

Example:

1

​
responsiveness
number

Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply.

Example:

1

​
interruption_sensitivity
number

Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted.

Example:

1

​
enable_backchannel
boolean

Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel.

Example:

true

​
backchannel_frequency
number

Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply.

Example:

0.9

​
backchannel_words
string[] | null

Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out backchannel default words for more details. Note that certain voices do not work too well with certain words, so it's recommended to expeirment before adding any words.

Example:
["yeah", "uh-huh"]
​
reminder_trigger_ms
number

If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply.

Example:

10000

​
reminder_max_count
integer

If set, controls how many times agent would remind user when user is unresponsive. Must be a non negative integer. If unset, default value of 1 will apply (remind once). Set to 0 to disable agent from reminding.

Example:

2

​
ambient_sound
enum<string> | null

If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options:

Set to null to remove ambient sound from this agent.

Available options:
coffee-shop,
convention-hall,
summer-outdoor,
mountain-outdoor,
static-noise,
call-center
​
ambient_sound_volume
number

If set, will control the volume of the ambient sound. Value ranging from [0,2]. Lower value means quieter ambient sound, while higher value means louder ambient sound. If unset, default value 1 will apply.

Example:

1

​
language
enum<string>

Specifies what language (and dialect) the speech recognition will operate in. For instance, selecting en-GB optimizes speech recognition 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,
pl-PL,
tr-TR,
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 call 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"

​
boosted_keywords
string[] | null

Provide a customized list of keywords to bias the transcriber model, so that these words are more likely to get transcribed. Commonly used for names, brands, street, etc.

Example:
["retell", "kroger"]
​
enable_transcription_formatting
boolean

If set to true, will format transcription to number, date, email, etc. If set to false, will return transcripts in raw words. If not set, default value of true will apply. This currently only applies to English.

Example:

true

​
opt_out_sensitive_data_storage
boolean

Whether this agent opts out of sensitive data storage like transcript, recording, logging, inbound/outbound phone numbers, etc. These data can still be accessed securely via webhooks. If not set, default value of false will apply.

Example:

true

​
pronunciation_dictionary
object[] | null

A list of words / phrases and their pronunciation to be used to guide the audio synthesize for consistent pronunciation. Currently only supported for English & 11labs voices. Set to null to remove pronunciation dictionary from this agent.

​
normalize_for_speech
boolean

If set to true, will normalize the some part of text (number, currency, date, etc) to spoken to its spoken form for more consistent speech synthesis (sometimes the voice synthesize system itself might read these wrong with the raw text). For example, it will convert "Call my number 2137112342 on Jul 5th, 2024 for the $24.12 payment" to "Call my number two one three seven one one two three four two on july fifth, twenty twenty four for the twenty four dollars twelve cents payment" before starting audio generation.

Example:

true

​
end_call_after_silence_ms
integer

If users stay silent for a period after agent speech, end the call. The minimum value allowed is 10,000 ms (10 s). By default, this is set to 600000 (10 min).

Example:

600000

​
max_call_duration_ms
integer

Maximum allowed length for the call, will force end the call if reached. The minimum value allowed is 60,000 ms (1 min), and maximum value allowed is 7,200,000 (2 hours). By default, this is set to 3,600,000 (1 hour).

Example:

3600000

​
enable_voicemail_detection
boolean

If set to true, will detect whether the call enters a voicemail. Note that this feature is only available for phone calls.

Example:

true

​
voicemail_message
string

The message to be played when the call enters a voicemail. Note that this feature is only available for phone calls. If you want to hangup after hitting voicemail, set this to empty string.

Example:

"Hi, please give us a callback."

​
voicemail_detection_timeout_ms
integer

Configures when to stop running voicemail detection, as it becomes unlikely to hit voicemail after a couple minutes, and keep running it will only have negative impact. The minimum value allowed is 5,000 ms (5 s), and maximum value allowed is 180,000 (3 minutes). By default, this is set to 30,000 (30 s).

Example:

30000

​
post_call_analysis_data
object[] | null

Post call analysis data to extract from the call. This data will augment the pre-defined variables extracted in the call analysis. This will be available after the call ends.

​
post_call_analysis_model
enum<string>

The model to use for post call analysis. Currently only supports gpt-4o-mini and gpt-4o. Default to gpt-4o-mini.

Available options:
gpt-4o-mini,
gpt-4o
Example:

"gpt-4o-mini"

​
begin_message_delay_ms
integer

If set, will delay the first message by the specified amount of milliseconds, so that it gives user more time to prepare to take the call. Valid range is [0, 5000]. If not set or set to 0, agent will speak immediately. Only applicable when agent speaks first.

Example:

1000

​
ring_duration_ms
integer

If set, the phone ringing will last for the specified amount of milliseconds. This applies for both outbound call ringtime, and call transfer ringtime. Default to 30000 (30 s). Valid range is [5000, 90000].

Example:

30000

​
stt_mode
enum<string>

If set, determines whether speech to text should focus on latency or accuracy. Default to fast mode.

Available options:
fast,
accurate
Example:

"fast"

Response

201
application/json
Successfully created a new agent.
​
agent_id
string
required

Unique id of 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

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

​
agent_name
string | null

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

Example:

"Jarvis"

​
version
number | null

Version of the agent.

Example:

0

​
voice_id
string

Unique voice id used for the agent. Find list of available voices and their preview in Dashboard.

Example:

"11labs-Adrian"

​
voice_model
enum<string> | null

Optionally set the voice model used for the selected voice. Currently only elevenlab voices have voice model selections. Set to null to remove voice model selection, and default ones will apply. Check out the dashboard for details on each voice model.

Available options:
eleven_turbo_v2,
eleven_flash_v2,
eleven_turbo_v2_5,
eleven_flash_v2_5,
eleven_multilingual_v2,
Play3.0-mini,
PlayDialog
​
fallback_voice_ids
string[] | null

When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent.

Example:
["openai-Alloy", "deepgram-Angus"]
​
voice_temperature
number

Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Currently this setting only applies to 11labs voices. If unset, default value 1 will apply.

Example:

1

​
voice_speed
number

Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply.

Example:

1

​
volume
number

If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply.

Example:

1

​
responsiveness
number

Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply.

Example:

1

​
interruption_sensitivity
number

Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted.

Example:

1

​
enable_backchannel
boolean

Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel.

Example:

true

​
backchannel_frequency
number

Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply.

Example:

0.9

​
backchannel_words
string[] | null

Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out backchannel default words for more details. Note that certain voices do not work too well with certain words, so it's recommended to expeirment before adding any words.

Example:
["yeah", "uh-huh"]
​
reminder_trigger_ms
number

If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply.

Example:

10000

​
reminder_max_count
integer

If set, controls how many times agent would remind user when user is unresponsive. Must be a non negative integer. If unset, default value of 1 will apply (remind once). Set to 0 to disable agent from reminding.

Example:

2

​
ambient_sound
enum<string> | null

If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options:

Set to null to remove ambient sound from this agent.

Available options:
coffee-shop,
convention-hall,
summer-outdoor,
mountain-outdoor,
static-noise,
call-center
​
ambient_sound_volume
number

If set, will control the volume of the ambient sound. Value ranging from [0,2]. Lower value means quieter ambient sound, while higher value means louder ambient sound. If unset, default value 1 will apply.

Example:

1

​
language
enum<string>

Specifies what language (and dialect) the speech recognition will operate in. For instance, selecting en-GB optimizes speech recognition 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,
pl-PL,
tr-TR,
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 call 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"

​
boosted_keywords
string[] | null

Provide a customized list of keywords to bias the transcriber model, so that these words are more likely to get transcribed. Commonly used for names, brands, street, etc.

Example:
["retell", "kroger"]
​
enable_transcription_formatting
boolean

If set to true, will format transcription to number, date, email, etc. If set to false, will return transcripts in raw words. If not set, default value of true will apply. This currently only applies to English.

Example:

true

​
opt_out_sensitive_data_storage
boolean

Whether this agent opts out of sensitive data storage like transcript, recording, logging, inbound/outbound phone numbers, etc. These data can still be accessed securely via webhooks. If not set, default value of false will apply.

Example:

true

​
pronunciation_dictionary
object[] | null

A list of words / phrases and their pronunciation to be used to guide the audio synthesize for consistent pronunciation. Currently only supported for English & 11labs voices. Set to null to remove pronunciation dictionary from this agent.

​
normalize_for_speech
boolean

If set to true, will normalize the some part of text (number, currency, date, etc) to spoken to its spoken form for more consistent speech synthesis (sometimes the voice synthesize system itself might read these wrong with the raw text). For example, it will convert "Call my number 2137112342 on Jul 5th, 2024 for the $24.12 payment" to "Call my number two one three seven one one two three four two on july fifth, twenty twenty four for the twenty four dollars twelve cents payment" before starting audio generation.

Example:

true

​
end_call_after_silence_ms
integer

If users stay silent for a period after agent speech, end the call. The minimum value allowed is 10,000 ms (10 s). By default, this is set to 600000 (10 min).

Example:

600000

​
max_call_duration_ms
integer

Maximum allowed length for the call, will force end the call if reached. The minimum value allowed is 60,000 ms (1 min), and maximum value allowed is 7,200,000 (2 hours). By default, this is set to 3,600,000 (1 hour).

Example:

3600000

​
enable_voicemail_detection
boolean

If set to true, will detect whether the call enters a voicemail. Note that this feature is only available for phone calls.

Example:

true

​
voicemail_message
string

The message to be played when the call enters a voicemail. Note that this feature is only available for phone calls. If you want to hangup after hitting voicemail, set this to empty string.

Example:

"Hi, please give us a callback."

​
voicemail_detection_timeout_ms
integer

Configures when to stop running voicemail detection, as it becomes unlikely to hit voicemail after a couple minutes, and keep running it will only have negative impact. The minimum value allowed is 5,000 ms (5 s), and maximum value allowed is 180,000 (3 minutes). By default, this is set to 30,000 (30 s).

Example:

30000

​
post_call_analysis_data
object[] | null

Post call analysis data to extract from the call. This data will augment the pre-defined variables extracted in the call analysis. This will be available after the call ends.

​
post_call_analysis_model
enum<string>

The model to use for post call analysis. Currently only supports gpt-4o-mini and gpt-4o. Default to gpt-4o-mini.

Available options:
gpt-4o-mini,
gpt-4o
Example:

"gpt-4o-mini"

​
begin_message_delay_ms
integer

If set, will delay the first message by the specified amount of milliseconds, so that it gives user more time to prepare to take the call. Valid range is [0, 5000]. If not set or set to 0, agent will speak immediately. Only applicable when agent speaks first.

Example:

1000

​
ring_duration_ms
integer

If set, the phone ringing will last for the specified amount of milliseconds. This applies for both outbound call ringtime, and call transfer ringtime. Default to 30000 (30 s). Valid range is [5000, 90000].

Example:

30000

​
stt_mode
enum<string>

If set, determines whether speech to text should focus on latency or accuracy. Default to fast mode.

Available options:
fast,
accurate
Example:

"fast"

Was this page helpful?