POST
/
register-call
curl --request POST \
  --url https://api.retellai.com/register-call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "audio_websocket_protocol": "twilio",
  "audio_encoding": "s16le",
  "sample_rate": 24000,
  "end_call_after_silence_ms": 600000,
  "from_number": "+12137771234",
  "to_number": "+12137771235",
  "direction": "inbound",
  "metadata": {},
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  }
}'
{
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "audio_websocket_protocol": "twilio",
  "audio_encoding": "s16le",
  "sample_rate": 24000,
  "call_status": "registered",
  "end_call_after_silence_ms": 600000,
  "from_number": "+12137771234",
  "to_number": "+12137771235",
  "direction": "inbound",
  "metadata": {},
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "drop_call_if_machine_detected": true,
  "opt_out_sensitive_data_storage": true
}

Authorizations

Authorization
string
headerrequired

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

Body

application/json
agent_id
string
required

Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call.

audio_websocket_protocol
enum<string>
required

Where the audio websocket would connect from would determine the format / protocol of websocket messages, and would determine how our server read audio bytes and send audio bytes.:

  • web: The protocol defined by Retell, commonly used for connecting from web frontend. Also useful for those who want to manipulate audio bytes directly.

  • twilio: The websocket protocol defined by Twilio, used when your system uses Twilio, and supplies Retell audio websocket url to Twilio.

Available options:
web,
twilio
audio_encoding
enum<string>
required

The audio encoding of the call. The following formats are supported:

  • s16le 16 bit linear PCM audio, the native format for web audio capture and playback.

  • mulaw non-linear audio encoding technique used in telephony. Commonly used by Twilio.

Available options:
s16le,
mulaw
sample_rate
integer
required

Sample rate of the conversation, the input and output audio bytes will all conform to this rate. Check the audio source, audio format, and voice used for the agent to select one that works. supports value ranging from [8000, 48000]. Note for Twilio mulaw encoding, the sample rate has to be 8000.

  • s16le sample rate recommendation (natively supported, lowest latency):

    • elevenlabs voices: 16000, 22050, 24000, 44100.

    • openai voices: 24000.

    • deepgram voices: 8000, 16000, 24000, 32000, 48000.

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). This value, if set, would overwrite the agent level end_call_after_silence_ms parameter.

from_number
string

The caller number. When you are using custom Twilio, we don't have this information, so you would need to specify this field if you want this information in the call history.

to_number
string

The callee number. When you are using custom Twilio, we don't have this information, so you would need to specify this field if you want this information in the call history.

direction
enum<string>

Direction of the phone call. Not populated for web call. When you are using custom Twilio, we don't have this information, so you would need to specify this field if you want this information in the call history.

Available options:
inbound,
outbound
metadata
object

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.

retell_llm_dynamic_variables
object

Add optional dynamic variables in key value pairs of string that injects into your Retell LLM prompt and tool description. Only applicable for Retell LLM.

Response

201 - application/json
call_id
string
required

Unique id of the call. Used to identify in LLM websocket and used to authenticate in audio websocket.

agent_id
string
required

Corresponding agent id of this call.

audio_websocket_protocol
enum<string>
required

Where the audio websocket would connect from would determine the format / protocol of websocket messages, and would determine how our server read audio bytes and send audio bytes.:

  • web: The protocol defined by Retell, commonly used for connecting from web frontend. Also useful for those who want to manipulate audio bytes directly.

  • twilio: The websocket protocol defined by Twilio, used when your system uses Twilio, and supplies Retell audio websocket url to Twilio.

Available options:
web,
twilio
audio_encoding
enum<string>
required

The audio encoding of the call. The following formats are supported:

  • s16le 16 bit linear PCM audio, the native format for web audio capture and playback.

  • mulaw non-linear audio encoding technique used in telephony. Commonly used by Twilio.

Available options:
s16le,
mulaw
sample_rate
integer
required

Sample rate of the conversation, the input and output audio bytes will all conform to this rate. Check the audio source, audio format, and voice used for the agent to select one that works. supports value ranging from [8000, 48000]. Note for Twilio mulaw encoding, the sample rate has to be 8000.

  • s16le sample rate recommendation (natively supported, lowest latency):

    • elevenlabs voices: 16000, 22050, 24000, 44100.

    • openai voices: 24000.

    • deepgram voices: 8000, 16000, 24000, 32000, 48000.

call_status
enum<string>
required

Status of call.

  • registered: Call id issued, ready to make a call using this id.

  • ongoing: Call connected and ongoing.

  • ended: The underlying websocket has ended for the call. Either user or agent hanged up, or call transferred.

  • error: Call encountered error.

Available options:
registered,
ongoing,
ended,
error
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). This value, if set, would overwrite the agent level end_call_after_silence_ms parameter.

from_number
string

The caller number.

to_number
string

The callee number.

direction
enum<string>

Direction of the phone call. Not populated for web call.

Available options:
inbound,
outbound
metadata
object

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.

retell_llm_dynamic_variables
object

Add optional dynamic variables in key value pairs of string that injects into your Retell LLM prompt and tool description. Only applicable for Retell LLM.

drop_call_if_machine_detected
boolean

If set, will drop the call if machine (voicemail, IVR) is detected. If not set, default value of false will apply.

opt_out_sensitive_data_storage
boolean

Whether this call opts out of sensitive data storage like transcript, recording, logging.

Was this page helpful?

Create Phone Call (Deprecated)Get Call (Deprecated)