Outbound Calls - RevRing AI Documentation

Configure your AI agents to initiate outbound phone calls for sales, surveys, reminders, and more.

How Outbound Calls Work

When you send an outbound call through RevRing:

You specify the agent, from number (caller ID), to number (recipient), and optional variables
RevRing initiates the call through your SIP trunk
When the recipient answers, the agent begins speaking based on its first message and prompt
The conversation proceeds according to your agent’s configuration
After the call ends, RevRing sends complete call details to your post-call webhook (if configured)

Sending Test Calls via Dashboard

Using the Make a Call Page

The Make a Call page is the primary way to test outbound calls from the dashboard.

Navigate to Make a Call
Select your Agent from the dropdown
Enter the From Number (must be a number on your SIP trunk, E.164 format)
Enter the To Number (the recipient’s phone number, E.164 format)
Optionally set a Caller ID Name (up to 15 characters)
Add Variables if your prompt uses dynamic content
Click Send Test Call

The Live Transcript card on the right updates in real time as the conversation progresses. After the call ends, click View full call details to see the recording, summary, and metrics.

Save frequently used configurations by entering a name and clicking Save Config. Load saved configs from the dropdown to quickly re-run tests with different scenarios.

Using the Test Panel

The test panel on the right side of the agent page lets you call your agent directly from the browser via WebRTC. This is useful for quick iteration — you can tweak the prompt and immediately test without needing a phone. Use Test Variables to set direction, customer_name, or any other variables your prompt expects. To test outbound calling over the phone network (with real caller ID and SIP routing), use the Make a Call page instead.

Sending Calls via API

For production outbound calling at scale, use the RevRing API.

Basic Outbound Call

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_id_here",
    "fromNumber": "+12025551234",
    "toNumber": "+14155552671"
  }'

With Caller ID Name

You can set a custom caller ID name (up to 15 characters) that is displayed to the recipient when the call arrives:

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_id_here",
    "fromNumber": "+12025551234",
    "toNumber": "+14155552671",
    "callerIdName": "Acme Support"
  }'

Caller ID name support depends on your SIP trunk provider and the recipient’s carrier. Not all carriers display the caller ID name.

With Custom Variables

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_id_here",
    "fromNumber": "+12025551234",
    "toNumber": "+14155552671",
    "variables": {
      "customer_name": "John Smith",
      "appointment_time": "2:00 PM today",
      "confirmation_code": "ABC123"
    }
  }'

The API returns a call object with an id that you can use to track the call’s status. See the API Reference for complete documentation.

Per-Call Content and Your Own Data

A single call can change what the agent says without editing the agent, and carry your own data:

{
  "agentId": "agent_abc123",
  "toNumber": "+14155551234",
  "fromNumber": "+14155550000",
  "firstMessage": "Hi {{first_name}}, this is Ava from Bright Smiles about tomorrow's cleaning.",
  "promptAppend": "This patient asked for an early morning slot last time.",
  "maxDurationSeconds": 300,
  "voicemailMessage": "Hi {{first_name}}, Bright Smiles here about tomorrow's cleaning. Please call us back at 555-0100.",
  "metadata": { "crmContactId": "c_8812", "campaign": "recall-q4" }
}

firstMessage: the opening line for this call (variables work as in the agent’s opening).
promptAppend: added to the end of the agent’s prompt for this call only.
maxDurationSeconds: the longest this call may run (10 to 7200).
voicemailMessage: the message left if this call reaches voicemail.
metadata: your own data, up to 16 KB. It is stored on the call, returned by GET /v1/calls/{id} and included in the call’s webhooks. The agent never sees it: use variables for anything the agent should know.

Retrying Safely

Send an Idempotency-Key header (or idempotencyKey in the body) with a value unique to the call you mean to place. If the request is retried with the same key within 24 hours, for example after a timeout, the API returns the call already placed instead of dialing the number again. Two identical requests sent at the same moment also produce a single call.

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: $REVRING_API_KEY" \
  -H "Idempotency-Key: recall-q4-c_8812" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent_abc123", "toNumber": "+14155551234", "fromNumber": "+14155550000"}'

Respecting Your Do-Not-Call List

Campaigns never dial a number on your do-not-call list. For single calls, set "honorDoNotCall": true and a number on the list is refused with 409 and "error": "number_on_do_not_call_list" instead of being dialed.

Steer or End a Call in Progress

Your system can talk to the agent while a call is live, for inbound and outbound calls alike. Send an instruction with the call’s id:

curl -X POST https://api.revring.ai/v1/calls/{id}/instructions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "The refund was approved a minute ago. Tell the caller it arrives in 3 to 5 days.", "speak": true }'

"speak": true (Say this now in the dashboard): the agent says it right away, in its own words. If it is in the middle of a sentence, it finishes first. If the caller talks over it before it is out, the agent brings it up again in its next reply, so the line is never lost.
"speak": false (default; Keep in mind in the dashboard): nothing is said out loud. The agent follows the note from its next reply for the rest of the call, like a whisper from a supervisor. Use it for context such as “the caller is a returning customer” or “offer the Thursday slot instead”.

Instructions appear in the call transcript as instruction items, so you can see what was sent and when. To hang up a call from your system, use End Call. Both are also available as tools in the MCP server.

Watching Calls Live in the Dashboard

The dashboard’s Live page shows every call in progress, with its running time and what the caller and the agent are saying as they say it. From each call you can:

Listen to the call without anyone on it hearing you or knowing you are there.
Tell the agent something: Say this now or Keep in mind (the same as /instructions above).
End the call after a confirmation.

Calls that ended in the last 30 minutes are listed below, so a call that just finished is one click away. Filter by agent or direction; the filters stay in the page address, so a filtered view can be bookmarked.

Configuring Outbound Agent Behavior

First Message

For outbound calls, the first message is critical since you’re initiating contact. Configure it in the Overview tab:

Hi {{customer_name}}, this is Alex calling from Acme Corp regarding your appointment scheduled for {{appointment_time}}. Is now a good time to talk?

Unlike inbound calls where leaving first message empty makes sense, outbound calls should almost always include a first message to properly introduce the purpose of the call.

When the Phone Is Still Ringing

Some carrier routes report a call as answered before the person has actually picked up, occasionally by 15 seconds or more. Anything the agent says in that window is spoken into a ringing phone, and the person hears nothing or only the tail of the opening. Two settings control this, and both default to current behavior so existing agents are unchanged. Pause before speaking. Set firstMessageDelayMs to wait that many milliseconds after the call is reported answered before the opening is spoken. Tune it to the route: start around 2000 to 3000 and adjust. If the person speaks during the pause, the opening is skipped and the agent simply replies to them, so the two never talk over each other.

{ "firstMessageDelayMs": 2500 }

Let the caller speak first. Set startSpeaker to "user" and the agent stays silent until the person says something, then opens the conversation from its prompt. Nothing is spoken during ringing at all. The re-engagement prompt is held as well, so the silence is genuine rather than a short delay.

{ "startSpeaker": "user" }

If the person never speaks. When the caller speaks first, set beginAfterUserSilenceMs and the agent opens the call itself once the person has said nothing for that many milliseconds (500 to 60000). If they speak first, the agent replies to them as usual. With a static first message the agent speaks it; otherwise it generates its opening from the prompt. Leave it unset to keep waiting. Keep it shorter than the silence end call timeout, otherwise a silent call ends before the agent speaks.

{ "startSpeaker": "user", "beginAfterUserSilenceMs": 4000 }

Use the pause when you want the agent to open the call but slightly later, and startSpeaker when you would rather the person open it. A third option needs no settings at all: keep the opening to a short line such as “Hi, is this Alex?” so that little is lost if part of it is missed.

Different Opening Settings for Outbound Calls

An agent that handles both directions can open each one differently: greet inbound callers straight away, but wait for the person to say “Hello?” on calls it places. startSpeakerOutbound and firstMessageDelayMsOutbound apply to outbound calls only. Left unset, outbound calls use startSpeaker and firstMessageDelayMs like every other call, so existing agents are unchanged. In the dashboard, tick Use different opening settings for outbound calls on the Overview tab.

{
  "startSpeaker": "agent",
  "startSpeakerOutbound": "user",
  "beginAfterUserSilenceMs": 4000
}

Per-Call Opening Overrides

POST /v1/calls accepts startSpeaker, firstMessageDelayMs and beginAfterUserSilenceMs to change how a single call opens, for example a longer pause for a list known to answer late, without editing the agent. For each setting, a value sent with the call takes precedence over the agent’s outbound setting, which takes precedence over its general setting. The agent’s saved settings are unchanged.

{
  "agentId": "agent_123",
  "toNumber": "+15551234567",
  "fromNumber": "+15557654321",
  "startSpeaker": "user",
  "beginAfterUserSilenceMs": 3000
}

Separate Inbound and Outbound Openings

Agents that handle both directions often need different openings: “Thank you for calling…” inbound versus “Hi, this is … calling from …” outbound. Set the Outbound First Message field (API: firstMessageOutbound) with the outbound text, and keep First Message as the inbound text. On outbound calls the agent speaks the outbound text; on inbound calls (or when the outbound field is empty) it speaks First Message, so existing agents are unaffected until you set it. Both fields support {{variables}} with the same substitution as the prompt, so per-call personalization works in either direction. This applies to static first messages; in dynamic mode the opening is generated from the prompt, which can branch on the {{direction}} variable instead.

Outbound-Specific Prompts

Tailor your prompt for outbound scenarios:

You are making an outbound call to confirm a customer's appointment. Your goals:

1. Verify the customer is available to talk (ask permission)
2. Confirm their appointment for {{appointment_time}}
3. Answer any questions about the appointment
4. Offer to reschedule if needed
5. Thank them and end the call politely

If they ask to be removed from future calls, acknowledge and confirm you'll update their preferences.

Keep the call brief (under 2 minutes) and respectful of their time.

Using Variables for Personalization

Variables allow you to customize each call without changing the agent configuration:

Reference variables in your prompt and first message using {{variable_name}} syntax
Pass variable values when sending the call via API or dashboard
The agent will replace placeholders with the actual values during the conversation

Common variable use cases:

Customer name, account number, order ID
Appointment dates and times
Custom messages or offers
Callback reasons or context

Voicemail Detection

Voicemail detection is particularly useful for outbound calling to avoid wasting resources on unanswered calls.

Enable Voicemail Detection

Navigate to the Tools tab
Locate Voicemail Detection under System Tools
Click Configure
Choose your action:
- Hangup: End the call immediately when voicemail is detected (saves costs)
- Leave Message: Speak a pre-recorded message before hanging up
If leaving a message, configure the voicemail message:
Hi {{first_name}}, this is Acme Corp calling to confirm your appointment. Please call us back at 1-800-555-0123 at your earliest convenience. Thank you.
The voicemail message supports {{variables}}, just like your prompt and first message. Variables are filled in from the call’s variables (for example, first_name). If a variable has no value, the placeholder is left as-is.
Click Save

For high-volume outbound campaigns, choose “Hangup” to minimize costs and focus agent time on live conversations.

When Nobody Speaks

Some voicemail systems answer without any greeting the agent can hear, so there is nothing for voicemail detection to key on. The platform closes these calls automatically: if nobody has spoken by the third re-engagement attempt (and the call is at least 20 seconds old), the agent says a short sign-off and ends the call with hangup cause SILENCE_TIMEOUT. This applies only while the other side has said nothing at all. Once a person has spoken, the agent stays patient through quiet stretches and keeps re-engaging normally.

Call Pacing and Concurrency

Understanding Concurrency Limits

RevRing enforces a concurrency limit on the maximum number of simultaneous calls per organization. You can view your current limit and usage on the Billing page.

Call Queuing

When you send an outbound call and all concurrent call slots are in use, RevRing automatically queues the call. Queued calls are dispatched in approximate order as slots become available. While a call is waiting, its status is QUEUED. Once a slot opens and the call is dispatched, the status transitions to INITIATED and then ONGOING when the recipient answers.

Queued calls have a maximum wait time of approximately 4 hours. If a slot does not open within that window, or if the call fails to dispatch for another reason, the call transitions to FAILED rather than remaining QUEUED indefinitely. Inspect the errorMessage field to see why.

You can check a call’s status at any time:

curl https://api.revring.ai/v1/calls/{callId} \
  -H "x-api-key: YOUR_API_KEY"

To cancel a queued call before it is dispatched:

curl -X POST https://api.revring.ai/v1/calls/{callId}/cancel \
  -H "x-api-key: YOUR_API_KEY"

Only calls with status QUEUED can be cancelled. Once a call moves to INITIATED or ONGOING, it cannot be cancelled through this endpoint.

Keeping Lines Free for Inbound Callers

If the same organization makes outbound calls and also takes inbound calls or website calls, a busy dialer can use every line. An inbound reserve keeps a number of lines that outbound calls (API calls, campaigns and tests) never take, so callers and website visitors always get through. Inbound and website calls can still use every line. Contact support to set the reserve for your organization; GET /v1/analytics/active reports it as concurrency.inboundReserve, and concurrency.limit is what outbound calls may use.

Opting Out of Queuing

If you prefer to handle queuing in your own system, pass skipQueue: true when creating the call. This tells RevRing to return an immediate 429 error instead of queuing when the concurrency limit is reached:

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_id_here",
    "fromNumber": "+12025551234",
    "toNumber": "+14155552671",
    "skipQueue": true
  }'

Response when at capacity (429):

{
  "error": "concurrency_limit"
}

Best Practices for High Volume

Leverage built-in queuing: Let RevRing queue calls automatically rather than managing pacing yourself
Monitor active calls: Track concurrent calls via the Analytics API
Cancel unnecessary queued calls: If priorities change, cancel queued calls that are no longer needed
Handle errors gracefully: Implement retry logic with exponential backoff for non-queued calls
Respect time zones: Schedule calls during appropriate hours for the recipient’s location

Monitoring Outbound Calls

Why a Call Failed

When a call ends with status FAILED, its errorMessage (in the API, the dashboard and the post-call webhook) says why. Reasons that come from your carrier or the person you called are plain sentences; the others are short codes.

`errorMessage`	What happened	What to do
`no answer: the callee did not pick up`	The number rang and nobody answered.	Retry later, or let a campaign retry by outcome.
`call rejected by the callee (busy or declined)`	The person was busy or declined the call.	Retry later.
`call rejected (SIP <code>: <reason>)`	Your carrier or the far end refused the call and gave a SIP code, for example `SIP 503: Trunk CPS limit exceeded` (your trunk’s calls-per-second limit) or `SIP 404: Not Found`.	Check the code with your carrier; for a calls-per-second limit, slow your dialing or raise the limit on your trunk.
`carrier rejected the call`	Your carrier refused the call without a SIP reason.	Check the number and your trunk.
`no response from the carrier`	Your carrier did not answer the call request.	Check your trunk’s address and credentials.
`the line disconnected before the call was answered`	The line dropped while ringing.	Retry.
`concurrency_limit`	All of your plan’s concurrent call slots were in use.	Queue calls (the default) or raise your concurrency.
`billing_inactive`	Your plan is not active.	Update billing in the dashboard.
`agent_unavailable`	The agent could not join the call.	Placing the call again usually works. If it repeats, contact support with the call ID.
`flow_not_configured` / `flow_invalid`	The agent’s conversation flow is missing or has an error.	Open the agent’s flow and fix the highlighted node.
`trunk_not_configured`	The agent’s phone number has no outbound trunk set up.	Assign a trunk to the number on the Phone Numbers page.
`the call could not be completed`	Any other reason.	Retry; contact support with the call ID if it repeats.

Real-Time Monitoring

View active outbound calls on the Overview page:

Active Calls: See current ongoing outbound calls
Filter by agent to monitor specific campaigns

Calls

Track all outbound calls in Calls:

Filter by Direction: Select “Outbound”
Filter by Status: View completed, failed, ongoing, or canceled calls
Filter by Agent: Focus on specific agents or campaigns
Click any call to view:
- Complete transcript
- Call recording
- Duration and timestamps
- Variables used
- Hangup cause and error messages (if applicable)

To list the calls that ended a particular way, filter by hang-up cause: GET /v1/calls?hangupCause=VOICEMAIL_DETECTED (several, comma-separated). The CSV export (GET /v1/calls/export) takes the same filter. The dashboard Overview shows your Voicemail Rate: the share of answered outbound calls that reached a voicemail box.

Success Metrics

Monitor key metrics to optimize your outbound campaigns:

Connection rate: Percentage of calls that connect vs. no answer/busy
Average duration: Typical call length for successful connections
Completion rate: Calls that reach the intended outcome
Cost per call: Track expenses across campaigns

Advanced Features

Post-Call Webhooks

Receive call results immediately after each call ends:

Configure Post-call Webhook URL in the Advanced tab:

https://api.yourcompany.com/webhooks/post-call

RevRing will POST complete call details including:
- Transcript
- Recording URL
- Call duration and timestamps
- Variables used
- AI-generated summary

Use this to:

Update your CRM with call outcomes
Trigger follow-up actions
Track campaign performance
Schedule callbacks for unsuccessful attempts

See the Webhooks guide for implementation details.

Call Transfer

Enable transfers to allow the agent to escalate to a human representative:

Navigate to the Tools tab
Click Configure on the Transfer tool
Add transfer routes:
- To number: +12025559999 (your sales team)
- Condition: When the customer wants to speak with a human or has complex questions
Click Save

The agent will offer to transfer when the condition is met.

End Call Control

Configure when the agent should end calls:

Navigate to the Tools tab
Click Configure on the End Call tool

Set custom end call rules:

End the call when:
- The customer confirms their appointment
- The customer declines and asks not to be called again
- The customer is not available and asks to call back later
- You've been speaking for more than 3 minutes

Click Save

Compliance and Best Practices

Legal Requirements

When making outbound calls, ensure compliance with:

TCPA (US): Obtain prior express written consent for marketing calls
TSR (US): Maintain do-not-call lists and honor opt-out requests (RevRing can add callers who ask automatically)
GDPR (EU): Respect data protection and privacy regulations
Local regulations: Follow country-specific telemarketing laws

You are responsible for ensuring compliance with all applicable laws and regulations. RevRing provides the technical platform but does not provide legal advice.

Best Practices

Respect time zones: Call during appropriate hours (typically 9 AM - 9 PM local time)
Honor opt-outs: Immediately stop calling anyone who requests removal
Clear identification: Always identify your company and purpose clearly
Keep it brief: Respect the recipient’s time with concise, focused calls
Professional tone: Use appropriate language and maintain a professional demeanor
Quality over quantity: Focus on successful conversations, not just call volume

Common Use Cases

Appointment Reminders

Hi {{customer_name}}, this is Acme Dental calling to remind you about your appointment tomorrow at {{appointment_time}} with Dr. {{doctor_name}}. 

Please respond with "confirm" if you'll be able to make it, or let me know if you need to reschedule.

Sales Follow-Up

Hi {{lead_name}}, this is {{agent_name}} from {{company_name}}. You recently expressed interest in {{product_name}} on our website. 

I'm calling to see if you have any questions and to share how we can help {{solve_problem}}.

Survey and Feedback

Hi {{customer_name}}, this is a brief call from Acme Corp. We recently helped you with {{service_type}} and would love to get your feedback. 

On a scale of 1 to 10, how satisfied were you with our service?

Payment Reminders

Hi {{customer_name}}, this is Acme Billing. We're calling about invoice {{invoice_number}} with a balance of {{amount}} due on {{due_date}}.

Are you able to make a payment today, or would you like to discuss payment options?

Troubleshooting

Calls fail to connect

Verify the from number is assigned to your SIP trunk
Ensure the to number is in valid E.164 format
Check your SIP trunk has sufficient capacity and balance
Review your telephony provider’s outbound restrictions
Confirm the destination country is allowed by your provider

Voicemail detection not working

Ensure voicemail detection is enabled in the Tools tab
Verify the action (hangup or leave message) is configured
Check the call recording to confirm voicemail was actually reached
Some voicemail systems may not be detectable - this is a known limitation

Variables not populating

Verify variable names match exactly between API call and prompt (case-sensitive)
Check that variables are passed in the API request body
Ensure variable syntax in prompt uses double curly braces: {{variable}}
Review the call transcript to see what was actually spoken

High failure rate

Check if you’re calling valid, reachable numbers
Verify caller ID (from number) is not flagged as spam
Consider time of day - avoid early morning or late evening
Review hangup causes in call logs to identify patterns
Ensure your first message clearly identifies the caller

Hit concurrency limit (429 error)

Implement exponential backoff and retry logic
Reduce call pacing or batch size
Check your current limit and usage at Billing
Monitor active calls before sending new batches
Contact support to discuss increasing your organization’s limit

Next Steps

Tools

Configure transfer, voicemail, and custom tools

Webhooks

Implement post-call webhooks to capture results

API Reference

View complete API documentation for sending calls

Calls

Query and analyze call history via API

​How Outbound Calls Work

​Sending Test Calls via Dashboard

​Using the Make a Call Page

​Using the Test Panel

​Sending Calls via API

​Basic Outbound Call

​With Caller ID Name

​With Custom Variables

​Per-Call Content and Your Own Data

​Retrying Safely

​Respecting Your Do-Not-Call List

​Steer or End a Call in Progress

​Watching Calls Live in the Dashboard

​Configuring Outbound Agent Behavior

​First Message

​When the Phone Is Still Ringing

​Different Opening Settings for Outbound Calls

​Per-Call Opening Overrides

​Separate Inbound and Outbound Openings

​Outbound-Specific Prompts

​Using Variables for Personalization

​Voicemail Detection

​Enable Voicemail Detection

​When Nobody Speaks

​Call Pacing and Concurrency

​Understanding Concurrency Limits

​Call Queuing

​Keeping Lines Free for Inbound Callers

​Opting Out of Queuing

​Best Practices for High Volume

​Monitoring Outbound Calls

​Why a Call Failed

​Real-Time Monitoring

​Calls

​Success Metrics

​Advanced Features

​Post-Call Webhooks

​Call Transfer

​End Call Control

​Compliance and Best Practices

​Legal Requirements

​Best Practices

​Common Use Cases

​Appointment Reminders

​Sales Follow-Up

​Survey and Feedback

​Payment Reminders

​Troubleshooting

​Next Steps

Tools

Webhooks

API Reference

Calls

How Outbound Calls Work

Sending Test Calls via Dashboard

Using the Make a Call Page

Using the Test Panel

Sending Calls via API

Basic Outbound Call

With Caller ID Name

With Custom Variables

Per-Call Content and Your Own Data

Retrying Safely

Respecting Your Do-Not-Call List

Steer or End a Call in Progress

Watching Calls Live in the Dashboard

Configuring Outbound Agent Behavior

First Message

When the Phone Is Still Ringing

Different Opening Settings for Outbound Calls

Per-Call Opening Overrides

Separate Inbound and Outbound Openings

Outbound-Specific Prompts

Using Variables for Personalization

Voicemail Detection

Enable Voicemail Detection

When Nobody Speaks

Call Pacing and Concurrency

Understanding Concurrency Limits

Call Queuing

Keeping Lines Free for Inbound Callers

Opting Out of Queuing

Best Practices for High Volume

Monitoring Outbound Calls

Why a Call Failed

Real-Time Monitoring

Calls

Success Metrics

Advanced Features

Post-Call Webhooks

Call Transfer

End Call Control

Compliance and Best Practices

Legal Requirements

Best Practices

Common Use Cases

Appointment Reminders

Sales Follow-Up

Survey and Feedback

Payment Reminders

Troubleshooting

Next Steps