Voice API

This guide covers core Voice API concepts, rate limits, geo permissions, call quality, caller ID verification, and STIR/SHAKEN compliance.

​

Calls Per Second (CPS)

CPS limits control how many calls your account can initiate or receive per second.

​

Outbound CPS Behavior

Calls exceeding outbound CPS are queued (not dropped) and dispatched when rate drops. Example: With 10 CPS limit, initiating 12 calls:

• First 10 execute immediately
• Remaining 2 queue and execute in next interval

​

Inbound CPS Behavior

Calls exceeding inbound CPS are rejected with SIP code 486.

​

CPS vs Concurrent Calls

To increase CPS: Contact Plivo Support.

---

​

Geo Permissions

Control which countries your account can call. By default, only US and Canada are enabled.

​

Configure Geo Permissions

1. Navigate to Voice > Geo Permissions
2. Enable countries where you need to make calls
3. Keep unused countries disabled for security

​

Common Errors

​

API Configuration

Use the Voice Geo Permissions API to manage programmatically.

---

​

Caller ID

​

Domestic Caller ID Support

Plivo guarantees domestic CLI presentation in:

• United States
• Canada
• United Kingdom
• Australia
• Peru

Other regions: CLI delivered on best-effort basis.

​

Verified Caller ID

Authenticate numbers before using as outbound caller ID. Verification methods:

• Plivo Console
• APIs
• SDKs

Benefits:

• Ensures compliance with carrier requirements
• Prevents calls from failing due to unverified caller ID

​

Do Not Originate (DNO) List

Calls using numbers on the US Telecom DNO list fail with dno_caller_id hangup cause. These numbers (government agencies, financial institutions) are inbound-only.

---

​

STIR/SHAKEN

STIR/SHAKEN is the FCC-mandated call authentication framework to combat spoofing and robocalls.

​

Attestation Levels

​

Requirements

Plivo needs KYC information to authenticate calls:

• Company name and website
• Business registration number/documents
• Nature of business
• Use case for Plivo

Note: STIR/SHAKEN applies only to US businesses.

---

​

Voice Alerts

Set up alerts for traffic anomalies and configuration errors.

1. Navigate to Voice > Settings > Alerts
2. Configure thresholds for:
   • Invalid XML responses
   • Call failure rates
   • Unusual traffic patterns

---

​

Making Calls

​

Outbound API Calls

Initiate calls using the Make Call API. Key parameters:

• from: Your Plivo number (caller ID)
• to: Destination number
• answer_url: URL returning XML instructions

​

Cancel Queued Calls

Use the Hangup API with the request_uuid from the queued call.

​

PreAnswer

Play audio before the call is answered (early media). Supported elements: <Speak>, <Play>, <Wait> Limitations:

• Not supported by all carriers
• Not supported by WebRTC SDK
• Accuracy varies by destination

---

​

Call Hangup Causes

​

Determine Hangup Cause

Hangup information is available in:

• Call Detail Records (CDR) via API or Console
• Callback payloads to hangup_url
• Dial XML callbackUrl (DialHangup events)

​

Common Hangup Causes

See Hangup Causes Reference for complete list.

---

​

Export Call Detail Records (CDR)

​

Recent CDRs (Last 90 Days)

1. Navigate to Voice > Logs > Calls
2. Apply filters as needed
3. Select CDRs to export
4. Click Export > Export Filtered Results

Large exports are emailed to your registered address.

​

Historical CDRs (Last 12 Months)

1. Navigate to Voice > Logs > Calls
2. Click Export > Export Historical Data
3. Select account/subaccount and date range

CDR fields include: Call UUID, From/To numbers, direction, duration, billed amount, hangup cause, and more. Note: Numbers in CDRs older than 90 days are redacted.

---

​

Audio File Caching

Plivo caches audio files used in <Play> XML and Play API.

​

Control Caching

Each Plivo media server maintains its own cache—first requests always result in cache miss.

---

​

Applications

Link phone numbers to answer/hangup URLs for call handling.

​

Create an Application

1. Navigate to Voice > XML > Add New Application
2. Enter application name
3. Configure answer URL and other settings
4. Click Create Application

​

Assign Number to Application

1. Go to Phone Numbers > Active
2. Click on the number
3. Select XML Application
4. Choose your application
5. Save

---

​

Call Quality Issues

​

Troubleshooting

​

Monitor Application Health

Check for 4xx/5xx status codes indicating:

• Invalid XML responses
• API request failures
• Configuration errors

Set up Voice Alerts to proactively detect issues.

---

​

Country-Specific Restrictions

​

Australia

Per ACMA regulations, blocked CLI prefixes:

• +6113, +611300, +611800, +611900

CLI modifications or spoofing flagged by spam detection.

​

China

Prohibited:

• Gambling, financial services, cryptocurrency
• Marketing/spam calls
• Fraudulent calls
• Politically sensitive content

Requirements:

• Average call duration > 3 minutes recommended
• Avoid high unanswered call rates
• No toll-free caller IDs

Contact Plivo Support to enable China calling.

---

​

Pricing

Access pricing by country:

• Console: Voice > Pricing
• API: Pricing API
• Download: CSV export from console

---

​

Related Resources

• SIP Trunking (Zentrunk)
• Voice Features
• India Calling
• Voice API Reference
• XML Reference
• Voice Quickstart
• Hangup Causes