Run outbound voice AI calls with Retell AI. Place single calls with per-call dynamic variables and metadata, launch batch calling campaigns, read transcripts, recordings, and post-call analysis (summary, sentiment, success, custom extracted data), list and filter calls, end or delete calls, and look up agents and phone numbers. Retell can also trigger workflows when a call starts, ends, or is analyzed.
Start an outbound Retell calling campaign: one call per task, each with its own number, dynamic variables, and metadata. Send now or schedule a start time, optionally limited to calling windows.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
fromNumber | string | Yes | Caller number in E.164 format; must be purchased from or imported to Retell |
tasks | json | Yes | Array of calls, e.g. [{"to_number": "+12137774445", "retell_llm_dynamic_variables": {"customer_name": "John"}}]. Each task may also set override_agent_id, override_agent_version, metadata, and custom_sip_headers |
batchName | string | No | Batch name, for your own reference |
triggerTimestamp | string | No | When to start, as Unix milliseconds or an ISO 8601 date-time. Leave empty to start now |
reservedConcurrency | number | No | Concurrency kept free for other calls, such as inbound calls |
callTimeWindow | json | No | Allowed calling windows, e.g. {"windows": [{"start": 540, "end": 1020}], "timezone": "America/New_York", "day": ["Monday", "Tuesday"]} (minutes since local midnight) |
| Parameter | Type | Description |
|---|
batchCallId | string | Batch call ID; filter List Calls by it |
name | string | Batch name |
fromNumber | string | Caller number |
scheduledTimestamp | number | When the batch starts (epoch ms) |
totalTaskCount | number | Number of calls in the batch |
callTimeWindow | json | Calling windows, when set |
Place an outbound phone call from a Retell voice AI agent. Pass per-call dynamic variables to personalize the agent prompt and metadata to tag the call. Returns the call ID used to track it.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
fromNumber | string | Yes | Caller number in E.164 format (e.g. +14157774444); must be purchased from or imported to Retell |
toNumber | string | Yes | Number to call in E.164 format (e.g. +12137774445). Retell-purchased numbers can only call US numbers |
overrideAgentId | string | No | Agent to use for this call only, instead of the agent bound to the from number's outbound setting |
overrideAgentVersion | string | No | Agent version for this call only: a number or a tag such as latest, latest_published, or prod |
dynamicVariables | json | No | String key-value pairs injected into the agent prompt, e.g. {"customer_name": "John Doe"} fills {{customer_name}} |
metadata | json | No | Arbitrary object stored on the call (e.g. your internal customer ID); returned on the call and its webhooks |
customSipHeaders | json | No | Custom SIP headers as string key-value pairs |
agentOverride | json | No | Per-call agent configuration overrides (agent, retell_llm, or conversation_flow settings) |
idempotencyKey | string | No | Retry key (5-255 letters, digits, _ or -). Retrying with the same key within an hour does not create another call |
ignoreE164Validation | boolean | No | Skip E.164 validation of the from number (custom telephony only) |
honorInternalDnc | boolean | No | Reject the call when the contact for the to number is marked do-not-call |
| Parameter | Type | Description |
|---|
callId | string | Call ID |
callType | string | phone_call or web_call |
agentId | string | Agent ID |
agentName | string | Agent name |
agentVersion | number | Agent version used by the call |
callStatus | string | registered, not_connected, ongoing, ended, or error |
direction | string | inbound or outbound |
fromNumber | string | Caller number |
toNumber | string | Callee number |
batchCallId | string | Batch call ID |
metadata | json | Metadata stored on the call |
dynamicVariables | json | Dynamic variables passed to the agent |
collectedDynamicVariables | json | Dynamic variables collected during the call |
startTimestamp | number | Call start (epoch ms) |
endTimestamp | number | Call end (epoch ms) |
durationMs | number | Call duration in milliseconds |
durationSeconds | number | Call duration in seconds |
transcript | string | Call transcript |
transcriptObject | json | Transcript utterances with timings |
recordingUrl | string | Call recording URL |
recordingMultiChannelUrl | string | Multi-channel recording URL |
publicLogUrl | string | Public debug log URL |
disconnectionReason | string | Why the call ended |
transferDestination | string | Transfer target |
callAnalysis | json | Post-call analysis (callSummary, inVoicemail, userSentiment, callSuccessful, customAnalysisData) |
callCost | json | Cost in cents (combinedCost, totalDurationSeconds, totalDurationUnitPrice, productCosts) |
stopped | boolean | Whether the call was stopped |
deleted | boolean | Whether the call was deleted |
calls | json | Calls on this page (same fields as Get Call) |
total | number | Total matching calls (when requested) |
hasMore | boolean | Whether another page is available |
paginationKey | string | Key for the next page |
agents | json | Agents (agentId, agentName, channel, isSuspended, isTransferAgent, userModifiedTimestamp, tags) |
version | number | Agent version returned by Get Agent |
isPublished | boolean | Whether the agent version is published |
responseEngine | json | Agent response engine |
voiceId | string | Agent voice ID |
language | json | Agent language |
webhookUrl | string | Agent webhook URL |
lastModificationTimestamp | number | Last modified (epoch ms) |
agent | json | Full agent object |
phoneNumbers | json | Phone numbers (phoneNumber, phoneNumberPretty, phoneNumberType, nickname, inboundAgents, outboundAgents, ...) |
name | string | Batch name |
scheduledTimestamp | number | Batch start (epoch ms) |
totalTaskCount | number | Number of calls in the batch |
callTimeWindow | json | Batch calling windows |
Permanently delete a Retell call and its associated data (transcript, recording, and analysis).
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
callId | string | Yes | ID of the call to delete |
| Parameter | Type | Description |
|---|
callId | string | ID of the deleted call |
deleted | boolean | Whether the call was deleted |
Get a Retell voice agent's configuration: name, version, publish state, response engine, voice, language, webhook URL, and the full agent object.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
agentId | string | Yes | ID of the agent to read |
agentVersion | string | No | Version to read: a number or a tag such as latest or latest_published (default latest) |
| Parameter | Type | Description |
|---|
agentId | string | Agent ID |
agentName | string | Agent name |
version | number | Agent version returned |
isPublished | boolean | Whether this version is published |
responseEngine | json | Response engine (type plus llm_id, conversation_flow_id, or custom LLM) |
voiceId | string | Voice ID |
language | json | Language code, or a list of codes for multilingual agents |
webhookUrl | string | Agent-level webhook URL for call events |
lastModificationTimestamp | number | Last modified (epoch ms) |
agent | json | Full agent object as Retell returned it |
Get a Retell call by ID: status, transcript, recording, disconnection reason, cost, and post-call analysis (summary, sentiment, success, and custom extracted data). Transcript and recording appear once the call ends; analysis once it is analyzed.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
callId | string | Yes | Call ID returned by Create Phone Call or a call webhook |
| Parameter | Type | Description |
|---|
callId | string | Call ID |
callType | string | phone_call or web_call |
agentId | string | Agent ID |
agentName | string | Agent name |
agentVersion | number | Agent version used by the call |
callStatus | string | registered, not_connected, ongoing, ended, or error |
direction | string | inbound or outbound |
fromNumber | string | Caller number |
toNumber | string | Callee number |
batchCallId | string | Batch call ID |
metadata | json | Metadata stored on the call |
dynamicVariables | json | Dynamic variables passed to the agent |
collectedDynamicVariables | json | Dynamic variables collected during the call |
startTimestamp | number | Call start (epoch ms) |
endTimestamp | number | Call end (epoch ms) |
durationMs | number | Call duration in milliseconds |
durationSeconds | number | Call duration in seconds |
transcript | string | Call transcript |
transcriptObject | json | Transcript utterances with timings |
recordingUrl | string | Call recording URL |
recordingMultiChannelUrl | string | Multi-channel recording URL |
publicLogUrl | string | Public debug log URL |
disconnectionReason | string | Why the call ended |
transferDestination | string | Transfer target |
callAnalysis | json | Post-call analysis (callSummary, inVoicemail, userSentiment, callSuccessful, customAnalysisData) |
callCost | json | Cost in cents (combinedCost, totalDurationSeconds, totalDurationUnitPrice, productCosts) |
stopped | boolean | Whether the call was stopped |
deleted | boolean | Whether the call was deleted |
calls | json | Calls on this page (same fields as Get Call) |
total | number | Total matching calls (when requested) |
hasMore | boolean | Whether another page is available |
paginationKey | string | Key for the next page |
agents | json | Agents (agentId, agentName, channel, isSuspended, isTransferAgent, userModifiedTimestamp, tags) |
version | number | Agent version returned by Get Agent |
isPublished | boolean | Whether the agent version is published |
responseEngine | json | Agent response engine |
voiceId | string | Agent voice ID |
language | json | Agent language |
webhookUrl | string | Agent webhook URL |
lastModificationTimestamp | number | Last modified (epoch ms) |
agent | json | Full agent object |
phoneNumbers | json | Phone numbers (phoneNumber, phoneNumberPretty, phoneNumberType, nickname, inboundAgents, outboundAgents, ...) |
name | string | Batch name |
scheduledTimestamp | number | Batch start (epoch ms) |
totalTaskCount | number | Number of calls in the batch |
callTimeWindow | json | Batch calling windows |
List Retell agents with their IDs, names, channel (voice or chat), and suspension status, optionally searching by name or ID.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
query | string | No | Case-insensitive search over agent name and agent ID |
channel | string | No | Only voice or chat agents |
limit | number | No | Maximum agents to return (default 50, max 1000) |
sortOrder | string | No | ascending or descending (default descending) |
paginationKey | string | No | Pagination key from the previous page |
| Parameter | Type | Description |
|---|
agents | array | Agents on this page |
↳ agentId | string | Agent ID |
↳ agentName | string | Agent name |
↳ channel | string | voice or chat |
↳ isSuspended | boolean | Whether suspended |
↳ isTransferAgent | boolean | Whether used for warm transfer |
↳ userModifiedTimestamp | number | Last modified (epoch ms) |
↳ tags | json | Version tags keyed by name |
List Retell calls, newest first by default, filtered by agent, status, or any documented filter (numbers, timestamps, sentiment, success, disconnection reason, metadata, custom analysis data). Items carry status, numbers, timings, recording, and analysis but not the transcript; use Get Call for that.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
agentId | string | No | Only calls handled by this agent |
callStatus | string | No | Only calls with this status: not_connected, ongoing, ended, or error |
filterCriteria | json | No | Raw Retell filter_criteria object, e.g. {"user_sentiment": {"type": "enum", "op": "in", "value": ["Negative"]}, "start_timestamp": {"type": "range", "op": "bt", "value": [1735689600000, 1735776000000]}} |
sortOrder | string | No | ascending or descending by start time (default descending) |
limit | number | No | Maximum calls to return (default 50, max 1000) |
skip | number | No | Number of calls to skip |
paginationKey | string | No | Pagination key from the previous page |
includeTotal | boolean | No | Also return the total number of matching calls |
| Parameter | Type | Description |
|---|
calls | array | Calls on this page |
total | number | Total matching calls (only when Include Total is on) |
List the phone numbers in your Retell account with their type, nickname, and the inbound and outbound agents bound to them.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
limit | number | No | Maximum numbers to return (default 50, max 1000) |
sortOrder | string | No | ascending or descending (default descending) |
paginationKey | string | No | Pagination key from the previous page |
| Parameter | Type | Description |
|---|
phoneNumbers | array | Phone numbers on this page |
↳ phoneNumber | string | Number in E.164 format |
↳ phoneNumberPretty | string | Formatted number |
↳ phoneNumberType | string | retell-twilio, retell-telnyx, or custom |
↳ nickname | string | Nickname |
↳ areaCode | number | US area code |
↳ inboundAgents | array | Inbound agents with weights (agent_id, agent_version, weight) |
↳ outboundAgents | array | Outbound agents with weights (agent_id, agent_version, weight) |
↳ inboundWebhookUrl | string | Inbound call webhook URL |
↳ lastModificationTimestamp | number | Last modified (epoch ms) |
End an ongoing Retell call immediately.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Retell API key (Retell dashboard → Settings → API Keys) |
callId | string | Yes | ID of the ongoing call to end |
| Parameter | Type | Description |
|---|
callId | string | ID of the stopped call |
stopped | boolean | Whether the call was stopped |
A Trigger is a block that starts a workflow when an event happens in this service.
Trigger workflow when a Retell call starts, ends, or finishes post-call analysis, with its transcript, recording, and analysis
| Parameter | Type | Required | Description |
|---|
eventFilter | string | No | Which Retell event runs the workflow. Call Analyzed carries the transcript and post-call analysis. |
webhookApiKey | string | Yes | Used to verify the x-retell-signature header on each delivery. Only the API key with the webhook badge signs webhooks. |
| Parameter | Type | Description |
|---|
event | string | Event name: call_started, call_ended, or call_analyzed |
callId | string | Unique call ID |
callType | string | phone_call or web_call |
callStatus | string | registered, not_connected, ongoing, ended, or error |
direction | string | inbound or outbound |
agentId | string | Agent that handled the call |
agentName | string | Name of the agent |
agentVersion | number | Agent version used |
fromNumber | string | Caller number (E.164) |
toNumber | string | Callee number (E.164) |
batchCallId | string | Batch call the call belongs to, if any |
startTimestamp | number | Call start (epoch ms) |
endTimestamp | number | Call end (epoch ms) |
durationMs | number | Call duration in milliseconds |
durationSeconds | number | Call duration in seconds |
disconnectionReason | string | Why the call ended (e.g. user_hangup, agent_hangup, voicemail_reached) |
transferDestination | string | Transfer target, if transferred |
transcript | string | Call transcript (call_ended and call_analyzed) |
transcriptObject | json | Transcript utterances with role, content, and word timings |
recordingUrl | string | Call recording URL |
recordingMultiChannelUrl | string | Recording with each party on its own channel |
publicLogUrl | string | Public debug log URL |
callAnalysis | object | callAnalysis output from the tool |
↳ callSummary | string | High-level summary of the call |
↳ inVoicemail | boolean | Whether the call reached voicemail |
↳ userSentiment | string | User sentiment: Negative, Positive, Neutral, or Unknown |
↳ callSuccessful | boolean | Whether the agent finished its task without the call being cut off |
↳ customAnalysisData | json | Custom post-call extraction fields configured on the agent |
callCost | object | callCost output from the tool |
↳ combinedCost | number | Total cost in cents |
↳ totalDurationSeconds | number | Billed duration in seconds |
↳ totalDurationUnitPrice | number | Combined unit price in cents per second |
↳ productCosts | json | Per-product costs in cents |
metadata | json | Metadata stored on the call |
dynamicVariables | json | Dynamic variables passed to the agent |
collectedDynamicVariables | json | Dynamic variables collected during the call |
payload | json | The full webhook payload as Retell delivered it |