Retell AI Update Call API
The Update Call API from Retell AI — 1 operation(s) for update call.
OpenAPI Specification
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice Update Call API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: Update Call
paths:
/v2/update-call/{call_id}:
patch:
description: Update metadata and sensitive data storage settings for an existing call.
operationId: updateCallMetadata
parameters:
- in: path
name: call_id
schema:
type: string
example: call_a4441234567890777c4a4a123e6
required: true
description: The call id of the call to be updated.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
description: 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. Size limited to 50kB max.
example:
customer_id: cust_123
notes: Follow-up required
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
description: Data storage setting for this call. Overrides the agent's default setting. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata. Cannot be downgraded from more restrictive to less restrictive settings.
example: everything_except_pii
override_dynamic_variables:
type: object
additionalProperties:
type: string
example:
additional_discount: 15%
description: Override dynamic varaibles represented as key-value pairs of strings. Setting this will override or add the dynamic variables set in the agent during the call. Only need to set the delta where you want to override, no need to set the entire dynamic variables object. Setting this to null will remove any existing override.
nullable: true
custom_attributes:
type: object
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
example:
custom_attribute_1: value1
custom_attribute_2: value2
description: Custom attributes for the call
additionalProperties: false
example:
metadata:
customer_id: cust_123
notes: Follow-up required
data_storage_setting: everything_except_pii
responses:
'200':
description: Call metadata updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/V2CallResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableContent'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- Update Call
components:
schemas:
CallLatency:
type: object
properties:
p50:
type: number
description: 50 percentile of latency, measured in milliseconds.
example: 800
p90:
type: number
description: 90 percentile of latency, measured in milliseconds.
example: 1200
p95:
type: number
description: 95 percentile of latency, measured in milliseconds.
example: 1500
p99:
type: number
description: 99 percentile of latency, measured in milliseconds.
example: 2500
max:
type: number
description: Maximum latency in the call, measured in milliseconds.
example: 2700
min:
type: number
description: Minimum latency in the call, measured in milliseconds.
example: 500
num:
type: number
description: Number of data points (number of times latency is tracked).
example: 10
values:
type: array
items:
type: number
description: All the latency data points in the call, measured in milliseconds.
ToolCallResultUtterance:
type: object
required:
- role
- tool_call_id
- content
properties:
role:
type: string
enum:
- tool_call_result
description: This is the result of a tool call.
tool_call_id:
type: string
description: Tool call id, globally unique.
content:
type: string
description: Result of the tool call, can be a string, a stringified json, etc.
successful:
type: boolean
description: Whether the tool call was successful.
DisconnectionReason:
type: string
enum:
- user_hangup
- agent_hangup
- call_transfer
- voicemail_reached
- ivr_reached
- inactivity
- max_duration_reached
- concurrency_limit_reached
- no_valid_payment
- scam_detected
- dial_busy
- dial_failed
- dial_no_answer
- invalid_destination
- telephony_provider_permission_denied
- telephony_provider_unavailable
- sip_routing_error
- marked_as_spam
- user_declined
- error_llm_websocket_open
- error_llm_websocket_lost_connection
- error_llm_websocket_runtime
- error_llm_websocket_corrupt_payload
- error_no_audio_received
- error_asr
- error_retell
- error_unknown
- error_user_not_joined
- registered_call_timeout
- transfer_bridged
- transfer_cancelled
- manual_stopped
ToolCallInvocationUtterance:
type: object
required:
- role
- tool_call_id
- name
- arguments
properties:
role:
type: string
enum:
- tool_call_invocation
description: This is a tool call invocation.
tool_call_id:
type: string
description: Tool call id, globally unique.
name:
type: string
description: Name of the function in this tool call.
arguments:
type: string
description: Arguments for this tool call, it's a stringified JSON object.
thought_signature:
type: string
description: Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
ProductCost:
type: object
required:
- product
- cost
properties:
product:
type: string
description: Product name that has a cost associated with it.
example: elevenlabs_tts
unit_price:
type: number
description: Unit price of the product in cents per second.
example: 1
cost:
type: number
description: Cost for the product in cents for the duration of the call.
example: 60
is_transfer_leg_cost:
type: boolean
description: True if this cost item is for a transfer segment.
CallAnalysis:
type: object
properties:
call_summary:
type: string
example: The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.
description: A high level summary of the call.
in_voicemail:
type: boolean
example: false
description: Whether the call is entered voicemail.
user_sentiment:
type: string
enum:
- Negative
- Positive
- Neutral
- Unknown
example: Positive
description: Sentiment of the user in the call.
call_successful:
type: boolean
example: true
description: Whether the agent seems to have a successful call with the user, where the agent finishes the task, and the call was complete without being cutoff.
custom_analysis_data:
type: object
description: Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified.
V2WebCallResponse:
allOf:
- type: object
required:
- call_type
- access_token
properties:
call_type:
type: string
enum:
- web_call
example: web_call
description: Type of the call. Used to distinguish between web call and phone call.
access_token:
type: string
example: eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p
description: Access token to enter the web call room. This needs to be passed to your frontend to join the call.
- $ref: '#/components/schemas/V2CallBase'
V2CallBase:
type: object
required:
- call_id
- agent_id
- agent_version
- call_status
properties:
call_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the call. Used to identify the call in the LLM websocket and used to authenticate in the audio websocket.
agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Corresponding agent id of this call.
agent_name:
type: string
example: My Agent
description: Name of the agent.
agent_version:
type: integer
example: 1
description: The version of the agent.
call_status:
type: string
enum:
- registered
- not_connected
- ongoing
- ended
- error
example: registered
description: 'Status of call.
- `registered`: Call id issued, starting 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 hung up, or call transferred.
- `error`: Call encountered error.
'
metadata:
type: object
description: 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:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description: Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.
collected_dynamic_variables:
type: object
additionalProperties: {}
example:
last_node_name: Test node
description: Dynamic variables collected from the call. Only available after the call ends.
custom_sip_headers:
type: object
additionalProperties:
type: string
description: Custom SIP headers to be added to the call.
example:
X-Custom-Header: Custom Value
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
example: everything
description: Data storage setting for this call's agent. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata.
nullable: true
opt_in_signed_url:
type: boolean
example: true
description: Whether this agent opts in for signed URLs for public logs and recordings. When enabled, the generated URLs will include security signatures that restrict access and automatically expire after 24 hours.
start_timestamp:
type: integer
example: 1703302407333
description: Begin timestamp (milliseconds since epoch) of the call. Available after call starts.
end_timestamp:
type: integer
example: 1703302428855
description: End timestamp (milliseconds since epoch) of the call. Available after call ends.
transfer_end_timestamp:
type: integer
example: 1703302628855
description: Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.
duration_ms:
type: integer
example: 10000
description: Duration of the call in milliseconds. Available after call ends.
transcript:
type: string
example: 'Agent: hi how are you doing?
User: Doing pretty well. How are you?
Agent: That''s great to hear! I''m doing well too, thanks! What''s up?
User: I don''t have anything in particular.
Agent: Got it, just checking in!
User: Alright. See you.
Agent: have a nice day
'
description: Transcription of the call. Available after call ends.
transcript_object:
type: array
items:
$ref: '#/components/schemas/Utterance'
description: Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.
transcript_with_tool_calls:
type: array
items:
$ref: '#/components/schemas/UtteranceOrToolCall'
description: Transcript of the call weaved with tool call invocation and results. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.
scrubbed_transcript_with_tool_calls:
type: array
items:
$ref: '#/components/schemas/UtteranceOrToolCall'
description: Transcript of the call weaved with tool call invocation and results, without PII. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.
recording_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
description: Recording of the call. Available after call ends.
recording_multi_channel_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
description: Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.
scrubbed_recording_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
description: Recording of the call without PII. Available after call ends.
scrubbed_recording_multi_channel_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
description: Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.
public_log_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt
description: Public log of the call, containing details about all the requests and responses received in LLM WebSocket, latency tracking for each turntaking, helpful for debugging and tracing. Available after call ends.
knowledge_base_retrieved_contents_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt
description: URL to the knowledge base retrieved contents of the call. Available after call ends if the call utilizes knowledge base feature. It consists of the respond id and the retrieved contents related to that response. It's already rendered in call history tab of dashboard, and you can also manually download and check against the transcript to view the knowledge base retrieval results.
latency:
type: object
description: Latency tracking of the call, available after call ends. Not all fields here will be available, as it depends on the type of call and feature used.
properties:
e2e:
description: End to end latency (from user stops talking to agent start talking) tracking of the call. This latency does not account for the network trip time from Retell server to user frontend. The latency is tracked every time turn change between user and agent.
$ref: '#/components/schemas/CallLatency'
asr:
description: Transcription latency (diff between the duration of the chunks streamed and the durations of the transcribed part) tracking of the call.
$ref: '#/components/schemas/CallLatency'
llm:
description: LLM latency (from issue of LLM call to first speakable chunk received) tracking of the call. When using custom LLM. this latency includes LLM websocket roundtrip time between user server and Retell server.
$ref: '#/components/schemas/CallLatency'
llm_websocket_network_rtt:
description: LLM websocket roundtrip latency (between user server and Retell server) tracking of the call. Only populated for calls using custom LLM.
$ref: '#/components/schemas/CallLatency'
tts:
description: Text-to-speech latency (from the triggering of TTS to first byte received) tracking of the call.
$ref: '#/components/schemas/CallLatency'
knowledge_base:
description: Knowledge base latency (from the triggering of knowledge base retrival to all relevant context received) tracking of the call. Only populated when using knowledge base feature for the agent of the call.
$ref: '#/components/schemas/CallLatency'
s2s:
description: Speech-to-speech latency (from requesting responses of a S2S model to first byte received) tracking of the call. Only populated for calls that uses S2S model like Realtime API.
$ref: '#/components/schemas/CallLatency'
disconnection_reason:
$ref: '#/components/schemas/DisconnectionReason'
example: agent_hangup
description: The reason for the disconnection of the call. Read detailed description about reasons listed here at [Disconnection Reason Doc](/reliability/debug-call-disconnect#understanding-disconnection-reasons).
transfer_destination:
type: string
example: '+12137771234'
description: The destination number or identifier where the call was transferred to. Only populated when the disconnection reason was `call_transfer`. Can be a phone number or a SIP URI. SIP URIs are prefixed with "sip:" and may include a ";transport=..." portion (if transport is known) where the transport type can be "tls", "tcp" or "udp".
nullable: true
call_analysis:
description: Post call analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after call ends. Subscribe to `call_analyzed` webhook event type to receive it once ready.
$ref: '#/components/schemas/CallAnalysis'
call_cost:
description: Cost of the call, including all the products and their costs and discount.
type: object
required:
- product_costs
- total_duration_seconds
- total_duration_unit_price
- combined_cost
properties:
product_costs:
type: array
description: List of products with their unit prices and costs in cents
items:
$ref: '#/components/schemas/ProductCost'
total_duration_seconds:
type: number
description: Total duration of the call in seconds
example: 60
total_duration_unit_price:
type: number
description: Total unit duration price of all products in cents per second
example: 1
combined_cost:
type: number
description: Combined cost of all individual costs in cents
example: 70
llm_token_usage:
type: object
description: LLM token usage of the call, available after call ends. Not populated if using custom LLM, realtime API, or no LLM call is made.
required:
- values
- average
- num_requests
properties:
values:
type: array
items:
type: number
description: All the token count values in the call.
average:
type: number
description: Average token count of the call.
num_requests:
type: number
description: Number of requests made to the LLM.
Utterance:
type: object
required:
- role
- content
- words
properties:
role:
type: string
enum:
- agent
- user
- transfer_target
description: Documents whether this utterance is spoken by agent or user.
example: agent
content:
type: string
description: Transcript of the utterances.
example: hi how are you doing?
words:
type: array
example:
- word: hi
start: 0.7
end: 1.3
description: Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation.
items:
type: object
properties:
word:
type: string
description: Word transcript (with punctuation if applicable).
start:
type: number
description: Start time of the word in the call in second. This is relative audio time, not wall time.
end:
type: number
description: End time of the word in the call in second. This is relative audio time, not wall time.
UtteranceOrToolCall:
oneOf:
- $ref: '#/components/schemas/Utterance'
- $ref: '#/components/schemas/ToolCallInvocationUtterance'
- $ref: '#/components/schemas/ToolCallResultUtterance'
- $ref: '#/components/schemas/NodeTransitionUtterance'
- $ref: '#/components/schemas/DTMFUtterance'
DTMFUtterance:
type: object
required:
- role
- digit
properties:
role:
type: string
enum:
- dtmf
description: Digit pressed by the user from their phone keypad.
digit:
type: string
description: The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
example: '1'
V2PhoneCallResponse:
allOf:
- type: object
required:
- call_type
- from_number
- to_number
- direction
properties:
call_type:
type: string
enum:
- phone_call
example: phone_call
description: Type of the call. Used to distinguish between web call and phone call.
from_number:
type: string
example: '+12137771234'
description: The caller number.
to_number:
type: string
example: '+12137771235'
description: The callee number.
direction:
type: string
enum:
- inbound
- outbound
example: inbound
description: Direction of the phone call.
telephony_identifier:
type: object
description: Telephony identifier of the call, populated when available. Tracking purposes only.
properties:
twilio_call_sid:
type: string
example: CA5d0d0d8047bf685c3f0ff980fe62c123
description: Twilio call sid.
- $ref: '#/components/schemas/V2CallBase'
NodeTransitionUtterance:
type: object
required:
- role
- former_node_id
- former_node_name
- new_node_id
- new_node_name
properties:
role:
type: string
enum:
- node_transition
description: This is result of a node transition
former_node_id:
type: string
description: Former node id
former_node_name:
type: string
description: Former node name
new_node_id:
type: string
description: New node id
new_node_name:
type: string
description: New node name
transition_type:
type: string
enum:
- global
- global_go_back
- interrupt_go_back
- normal
description: How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
V2CallResponse:
oneOf:
- $ref: '#/components/schemas/V2WebCallResponse'
- $ref: '#/components/schemas/V2PhoneCallResponse'
responses:
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: An unexpected server error occurred.
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: API key is missing or invalid.
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Invalid request format, please check API reference.
UnprocessableContent:
description: Unprocessable Content
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Cannot find requested asset under given api key.
securitySchemes:
api_key:
type: http
scheme: bearer
bearerFormat: string
description: Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"