Skip to main content
POST
Create Agent

Authorizations

​
x-api-key
string
header
required

API key for authentication. Generate API keys from the RevRing dashboard. A key is either full access or read-only; a read-only key is refused with 403 read_only_key on any request that creates, changes or deletes.

Body

application/json

Create a new AI voice agent

​
name
string
required

Agent name

Maximum string length: 128
​
promptTemplate
string
required

System prompt with {{variable}} placeholders

​
messagingConnectionId
string | null

ID of the messaging connection this agent sends and receives texts through (see Messaging Connections).

​
messagingConfig
object

Per-agent messaging settings. A JSON object; set only the keys you need.

​
widgetConfig
object

Per-agent website chat widget settings. A JSON object; set only the keys you need. Enabling the widget the first time mints a public embed key (returned as the read-only 'widgetKey' on the agent).

​
sipTrunkId
string<uuid> | null

SIP trunk ID to use for this agent's calls

​
folderId
string<uuid> | null

Folder to place this agent in. Omit or pass null for uncategorized.

​
status
enum<string>

Agent status (active = can receive calls, disabled = inactive)

Available options:
active,
disabled
​
defaultVariables
object

Default values for template variables

​
firstMessage
string

Agent's opening message

Maximum string length: 4000
​
firstMessageOutbound
string | null

Optional outbound-specific opening. On outbound calls it is spoken instead of firstMessage; null or empty means firstMessage is used for both directions. Supports {{variables}}.

Maximum string length: 4000
​
startSpeaker
enum<string> | null

Who opens the conversation. agent (default) speaks the opening. user keeps the agent silent, including the re-engagement prompt, until the caller speaks (see beginAfterUserSilenceMs).

Available options:
agent,
user
​
firstMessageDelayMs
integer | null

Milliseconds to wait after the call is reported answered before the opening is spoken. Null or 0 speaks it immediately. Useful on routes that report a call answered while the phone is still ringing. If the caller speaks during the pause the opening is skipped.

Required range: 0 <= x <= 15000
​
startSpeakerOutbound
enum<string> | null

startSpeaker for outbound calls only. Null (default) uses startSpeaker for every call. Inbound and web calls always use startSpeaker.

Available options:
agent,
user
​
firstMessageDelayMsOutbound
integer | null

firstMessageDelayMs for outbound calls only. Null (default) uses firstMessageDelayMs for every call. 0 is a real value: no pause on outbound calls.

Required range: 0 <= x <= 15000
​
beginAfterUserSilenceMs
integer | null

For calls where the caller speaks first (startSpeaker or startSpeakerOutbound set to user): if the caller has said nothing after this many milliseconds, the agent speaks its opening. If the caller speaks first, the agent replies to them as usual. Null (default) keeps waiting. Keep it shorter than silenceEndCallTimeoutSeconds, otherwise a silent call ends before the agent speaks.

Required range: 500 <= x <= 60000
​
firstMessageMode
enum<string>

How the agent opens the call. "static" (default) speaks the first message text. "dynamic" generates the opening line from the agent's prompt, so one agent can greet inbound and outbound callers differently. When omitted, the agent speaks the first message if set, otherwise waits for the caller.

Available options:
static,
dynamic
​
turnTimeoutSeconds
integer

Seconds to wait for user response (-1 = no timeout)

Required range: x >= -1
​
silenceEndCallTimeoutSeconds
integer

Silence duration before ending call (-1 = no timeout)

Required range: x >= -1
​
maxConversationDurationSeconds
integer

Maximum call duration in seconds

Required range: x >= 1
​
llmTemperature
number

LLM temperature for response randomness (0-2)

Required range: 0 <= x <= 2
​
llmModel
enum<string>

Language model tier powering the agent. Usage is billed per minute at the tier's rate: revring-standard $0.03/min, revring-max $0.05/min, revring-ultra $0.065/min. Defaults to revring-standard.

Available options:
revring-standard,
revring-max,
revring-ultra
​
timezone
string

IANA timezone identifier (e.g., America/New_York)

​
language
string

Language code (e.g., en, es, fr)

​
preCallWebhookUrl
string<uri>

Webhook URL called before answering (optional)

​
postCallWebhookUrl
string<uri>

Webhook URL called after call ends (optional)

​
postCallWebhookFormat
enum<string>
default:revring

Payload shape of the post-call webhook. retell sends Retell's call_ended and call_analyzed events; elevenlabs sends post_call_transcription (or call_initiation_failure for dials that never connected). See compatibility formats.

Available options:
revring,
retell,
elevenlabs
​
webhookEvents
enum<string>[]

Extra events sent to the post-call webhook URL. call.started is sent once when a call connects; transfer.started, transfer.bridged and transfer.cancelled report transfers as they happen.

Available options:
call.started,
transfer.started,
transfer.bridged,
transfer.cancelled
​
postCallExtraction
object · null · null

Fields to extract from the transcript after every call (see PostCallExtractionConfig). null = off

Example:
​
postCallEvaluation
object · null · null

Success criteria judged after every call (see PostCallEvaluationConfig). null = off

Example:
​
storageMode
enum<string> | null

What call content is kept. full keeps everything; redact_pii removes personal details from the transcript and summary before the call is stored or sent. See Data Controls.

Available options:
full,
redact_pii
​
piiCategories
enum<string>[] | null

Personal detail categories removed in redact_pii mode. Default: all.

Available options:
person_name,
phone_number,
email,
address,
date_of_birth,
government_id,
payment_card,
bank_account,
account_number,
password_or_pin,
medical_record_number
​
endCallEnabled
boolean

Allow agent to end calls

​
endCallRulesOverride
string

Custom instructions for ending calls

​
transferEnabled
boolean

Allow agent to transfer calls

​
transferRoutes
object[]

Available transfer destinations

​
transferDescriptionOverride
string

Custom transfer instructions

​
voicemailEnabled
boolean

Detect voicemail

​
voicemailAction
enum<string>

Action when voicemail detected

Available options:
hangup,
leave_message
​
voicemailMessage
string

Message to leave on voicemail. Supports {{variables}} like the prompt and first message.

​
voiceId
string

Voice ID (copy from dashboard Voice Library)

​
fallbackVoiceId
string | null

Backup voice ID for seamless voice continuity: in the rare case the primary voice is temporarily unavailable, the agent switches to this voice automatically. Omit or set null to let the platform pick a standard backup voice.

​
voiceTemperature
number

Voice expressiveness (0 = consistent, 1 = more varied). Default 0.7.

Required range: 0 <= x <= 1
​
voiceSpeed
number

Speaking rate multiplier (0.5 = half speed, 2.0 = double speed). Default 1.0.

Required range: 0.5 <= x <= 2
​
voiceVolume
number

Output level in decibels (-20 to 20; 0 = standard). Default 0.

Required range: -20 <= x <= 20
​
voiceTopP
number

Advanced sampling range (0 to 1). Default 0.7.

Required range: 0 <= x <= 1
​
runtimeConfig
object

Advanced runtime configuration (optional)

​
mode
enum<string>

Agent mode (immutable after creation). Defaults to single_prompt.

Available options:
single_prompt,
conversation_flow
​
flowDefinition
object | null

Conversation flow definition (only used when mode is conversation_flow)

​
testVariables
object | null

Variables used for test calls initiated from the dashboard

​
llmReasoningEffort
enum<string>

Controls the reasoning effort of the language model. Higher values produce more thorough but slower responses.

Available options:
low,
medium,
high
​
disableInterruptions
boolean

When enabled, the agent will not be interrupted by the caller while speaking

​
interruptionThresholdMs
integer
default:500

Minimum speech duration (ms) before the caller's speech is registered as an interruption. Lower values make the agent easier to interrupt. Range: 100-2000, default 500.

Required range: 100 <= x <= 2000
​
interruptionIgnoreWords
string[] | null

Acknowledgment words or short phrases that never interrupt the agent while it is speaking (for example "okay", "yeah", "uh-huh"). Anything beyond a brief acknowledgment still interrupts normally, and these words behave normally when the agent is not speaking. null (default) uses the recommended platform list, [] disables the feature, and a list fully replaces the recommended list.

Maximum array length: 50
Required string length: 1 - 40
​
sttKeyterms
string[] | null

Names or terms to boost in speech recognition, such as brand names, product names, or uncommon personal names. Merged with the stt_keyterms call variable and automatic boosting of name variables. Null means none.

Maximum array length: 50
Required string length: 1 - 60
​
noiseCancellation
enum<string>
default:on

Background noise suppression on the caller's audio before the agent listens: background noise and competing voices are suppressed so the agent hears the person on the line. On by default for every agent; set off to disable for this agent.

Available options:
on,
off
​
minInterruptionWords
integer
default:1

Number of transcribed words required before the caller's speech interrupts the agent while it is speaking. Default 1 keeps the agent responsive. Higher values make the agent harder to interrupt. 0 interrupts on any caller sound, including background noise.

Required range: 0 <= x <= 10
​
transferMode
enum<string>

Transfer mode. cold disconnects the AI before connecting to the destination. warm keeps the AI on the line to introduce the caller.

Available options:
cold,
warm
​
warmTransferConfig
object | null

Configuration for warm transfers (only used when transferMode is warm)

​
playKeypadTouchToneEnabled
boolean

Enable the keypad input (DTMF) tool, allowing callers to press phone keys during the conversation

​
playKeypadTouchToneDescriptionOverride
string | null

Custom instructions for the keypad input tool behavior

Maximum string length: 2000
​
knowledgeBaseRetrievalMode
enum<string>

How the agent queries linked knowledge bases. automatic retrieves context on every turn. query_tool lets the agent decide when to search.

Available options:
automatic,
query_tool
​
knowledgeBaseChunks
integer

Number of text chunks to retrieve per knowledge base query

Required range: 1 <= x <= 20
​
knowledgeBaseSimilarityThreshold
number

Minimum similarity score for retrieved chunks (0-1). Higher values return only highly relevant results.

Required range: 0 <= x <= 1
​
languagePresets
object | null

Voice and opening line per language code (e.g. es, pt-BR), used when a call runs in that language. See Language presets.

​
doNotCallDetection
boolean
default:false

After each call, detect a caller's request not to be called again; when they asked, the call shows doNotCallRequested: true and their number goes on your do-not-call list. See Do-not-call list.

​
inboundCallbacks
object | null

Callback recognition: an inbound caller your account dialed within windowDays is treated as calling back. The call carries the outbound call's variables plus is_callback, callback_call_id, last_call_time and last_call_outcome, the agent is told how that call went, and it greets a returning caller (your greeting, or its first message adapted) instead of an opening written for calls it places. On by default. See Callbacks.

​
contactMemory
object | null

Contact memory: update adds what each call taught about the person to a memory kept for their phone number; read gives the agent that memory at the start of inbound and outbound calls. Both off by default. See Contact memory.

​
guardrails
object | null

What the agent refuses to be pulled into, on calls, in tests, over SMS and in web chat; null = off. See the Guardrails guide.

​
booking
object | null

Live booking on a connected calendar: the agent gets check_availability and book_appointment. See Integrations.

​
handoffRoutes
object[] | null

Agents this agent can hand the caller to on the same call. See Hand Off to Another Agent.

Maximum array length: 10
​
mcpServers
object[] | null

MCP servers whose tools the agent can use (single-prompt agents). See MCP Servers.

Maximum array length: 5
​
recordingEnabled
boolean | null
default:true

Record the agent's calls. false: no audio is recorded. See Data Controls.

​
pronunciations
object[] | null

How the agent says specific words on calls; transcripts keep the word as written. Words are unique (ignoring case). See Pronunciation.

Maximum array length: 200
​
keypadInput
object | null

Digits the caller presses reach the agent as their turn (single-prompt agents). Off unless set. See Caller Keypad Input.

​
backchannels
boolean

Beta. Short listening sounds ("mm-hmm", "right") in the agent's voice at natural pauses in long caller turns. Never takes the turn. Default false.

Response

Agent created

​
data
object

AI Voice Agent configuration