Skip to main content
POST
Send Call

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.

Headers

Idempotency-Key
string

Makes a retried request return the call already placed (24 hours).

Maximum string length: 200

Body

application/json
agentId
string<uuid>
required
toNumber
string
required

Destination number (E.164)

Pattern: ^\+[1-9]\d{1,14}$
fromNumber
string
required

Caller ID number (E.164)

Pattern: ^\+[1-9]\d{1,14}$
variables
object

Template variables for this call

callerIdName
string

Caller ID name displayed to the recipient (max 15 characters)

Required string length: 1 - 15
skipQueue
boolean
default:false

When true, returns a 429 error immediately if the concurrency limit is reached instead of queuing the call

voicemailAction
enum<string>

Override the agent's voicemail behavior for this call only. 'leave_message' leaves the agent's configured voicemail when an answering machine is detected; 'hangup' ends the call without leaving a message. Omit to use the agent's saved setting. The agent must have voicemail detection enabled for this to take effect. Useful for multi-attempt outreach where only the final attempt should leave a voicemail.

Available options:
hangup,
leave_message
voiceId
string

Override the agent's voice for this call only. Takes a voice id from GET /voices (a system voice or one owned by your organization). Lets one agent speak with different voices per call - for example rotating across a set of voices, or matching the voice to what you know about the person being called - without editing the agent between calls. The agent's saved voice is unchanged and its backup-voice behavior still applies. An unknown or unusable voice id is rejected with 400 voice_not_found.

startSpeaker
enum<string>

Override who opens the conversation for this call only. Takes precedence over the agent's startSpeakerOutbound and startSpeaker. The agent's saved settings are unchanged.

Available options:
agent,
user
firstMessageDelayMs
integer

Override the pause before the agent speaks for this call only, in milliseconds. 0 means no pause. Takes precedence over the agent's firstMessageDelayMsOutbound and firstMessageDelayMs.

Required range: 0 <= x <= 15000
beginAfterUserSilenceMs
integer

Override beginAfterUserSilenceMs for this call only: when the caller speaks first and stays silent this many milliseconds, the agent speaks its opening.

Required range: 500 <= x <= 60000
environment
string

Agent environment to run this call on. Omit for production: the published version in manual publish mode, the agent as saved otherwise. Unknown names are refused with 400 environment_not_found before anything is dialed

Pattern: ^[a-z][a-z0-9-]{0,31}$
language
string

Language for this call only (e.g. es, pt-BR); the agent's preset for that language supplies the voice and opening line. See Language per call.

firstMessage
string

The opening line for this call only (variables work as in the agent's opening).

Required string length: 1 - 4000
promptAppend
string

Added to the end of the agent's prompt for this call only.

Required string length: 1 - 8000
maxDurationSeconds
integer

The longest this call may run, in seconds.

Required range: 10 <= x <= 7200
voicemailMessage
string

The message left if this call reaches voicemail.

Required string length: 1 - 2000
metadata
object

Your own data for this call, up to 16 KB: stored on the call, returned by GET /v1/calls/{id} and sent in the call's webhooks. Never shown to the agent (use variables for that).

idempotencyKey
string

A retried request with the same key within 24 hours returns the call already placed instead of dialing again. Also accepted as the Idempotency-Key header (the body field wins).

Required string length: 1 - 200
honorDoNotCall
boolean

Refuse to dial a number on your do-not-call list (409 number_on_do_not_call_list). Campaigns always honour the list.

Response

Outbound call initiated

data
object

Phone call record