Integrate Plivo voice and messaging into the workflow. Call a lead and hand the call to your own Plivo XML app or an AI voice agent such as Bolna or Vapi, hang up live calls, send SMS, MMS, and WhatsApp template messages, check call and message records, search for and buy phone numbers, and look up a number’s carrier and line type. Can also run workflows when a call ends, a message status changes, or a Plivo number receives a message. Requires a Plivo Auth ID and Auth Token.
Place an outbound phone call from a Plivo number. When the call is answered, Plivo fetches the answer URL, which must return Plivo XML telling it what to do. The answer URL can point to your own Plivo XML app, or to an AI voice platform such as Bolna or Vapi that returns the XML that connects the call to its voice agent. Returns a request UUID; the call UUID arrives in the hangup callback.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
from | string | Yes | Caller ID: a Plivo number on your account, in E.164 format (e.g. 14157654321) |
to | string | Yes | Number or SIP URI to call, in E.164 format. Separate several destinations with "<" (max 1000). |
answerUrl | string | Yes | URL Plivo requests when the call is answered. It must return valid Plivo XML, either from your own Plivo XML app or from an AI voice platform such as Bolna or Vapi. |
answerMethod | string | No | HTTP method for the answer URL: GET or POST (default POST) |
ringUrl | string | No | URL Plivo notifies when the call starts ringing |
ringMethod | string | No | HTTP method for the ring URL: GET or POST (default POST) |
hangupUrl | string | No | URL Plivo notifies when the call ends, such as a Plivo Call Status trigger URL |
hangupMethod | string | No | HTTP method for the hangup URL: GET or POST (default POST) |
fallbackUrl | string | No | URL Plivo uses if the answer URL fails after 3 retries or a 60s timeout |
fallbackMethod | string | No | HTTP method for the fallback URL: GET or POST (default POST) |
callerName | string | No | Caller name to display, up to 50 characters |
sendDigits | string | No | DTMF digits to send once connected. Use w for a 0.5s wait and W for 1s. |
timeLimit | number | No | Maximum call length in seconds (default 14400) |
hangupOnRing | number | No | Seconds after ringing starts to hang up |
ringTimeout | number | No | Seconds to ring the destination before giving up |
machineDetection | string | No | Answering machine detection: "true" to detect and report, or "hangup" to hang up on a machine |
machineDetectionTime | number | No | Milliseconds to spend detecting a machine (2000 to 10000, default 5000) |
machineDetectionUrl | string | No | URL notified with the asynchronous machine detection result |
machineDetectionMethod | string | No | HTTP method for the machine detection URL: GET or POST (default POST) |
sipHeaders | string | No | Custom SIP headers as comma-separated key=value pairs, e.g. leadId=42. Sent with an X-PH- prefix. |
| Parameter | Type | Description |
|---|
message | string | Plivo status text, "call fired" on success |
requestUuid | string | Request identifier. The hangup callback carries it as RequestUUID next to the CallUUID. |
apiId | string | Plivo API request ID |
Get the call detail record of a completed Plivo call: numbers, times, duration, cost, and why it ended.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
callUuid | string | Yes | UUID of the call (CallUUID from a callback, or call_uuid from List Calls) |
| Parameter | Type | Description |
|---|
callUuid | string | Unique call identifier (call_uuid) |
fromNumber | string | Caller ID used for the call |
toNumber | string | Number or SIP URI that was called |
callDirection | string | inbound or outbound |
answerTime | string | When the call was answered |
endTime | string | When the call ended |
initiationTime | string | When the call was started |
callDuration | number | Call duration in seconds |
billDuration | number | Actual call duration in seconds |
billedDuration | number | Duration rounded to the billing increment, in seconds |
totalAmount | string | Amount charged for the call |
totalRate | string | Per-minute rate |
parentCallUuid | string | UUID of the A-leg |
hangupCauseName | string | Why the call ended, e.g. "Normal Hangup" or "Busy Line". Use it for the outcome. |
hangupCauseCode | number | Numeric hangup cause |
hangupSource | string | Who hung up: Caller, Callee, Plivo, API Request, Answer XML, Error, or Unknown |
stirVerification | string | STIR/SHAKEN status: Verified, Not Verified, or Not Applicable |
resourceUri | string | API path of the call record |
List completed Plivo calls with optional filters. Without an end time filter Plivo searches the last 7 days; the range can be at most 30 days within the last 90 days.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
fromNumber | string | No | Only calls made from this number |
toNumber | string | No | Only calls made to this number |
callDirection | string | No | inbound or outbound |
billDurationGte | number | No | Only calls with a billed duration of at least this many seconds |
billDurationLte | number | No | Only calls with a billed duration of at most this many seconds |
endTimeGte | string | No | Only calls that ended at or after this time (YYYY-MM-DD HH:MM[:ss]) |
endTimeLte | string | No | Only calls that ended at or before this time (YYYY-MM-DD HH:MM[:ss]) |
hangupCauseCode | number | No | Only calls with this hangup cause code |
hangupSource | string | No | Only calls hung up by this source, e.g. customer or carrier |
stirVerification | string | No | STIR/SHAKEN status: Verified, Not Verified, or Not Applicable |
limit | number | No | Results per page, 1 to 20 (default 20) |
offset | number | No | Number of results to skip, for paging |
| Parameter | Type | Description |
|---|
meta | json | Pagination: limit, offset, totalCount, next, and previous |
↳ limit | number | Results per page |
↳ offset | number | Results skipped |
↳ totalCount | number | Total matching records |
↳ next | string | API path of the next page |
↳ previous | string | API path of the previous page |
calls | array | Call detail records |
↳ callUuid | string | Unique call identifier (call_uuid) |
↳ fromNumber | string | Caller ID used for the call |
↳ toNumber | string | Number or SIP URI that was called |
↳ callDirection | string | inbound or outbound |
↳ answerTime | string | When the call was answered |
↳ endTime | string | When the call ended |
↳ initiationTime | string | When the call was started |
↳ callDuration | number | Call duration in seconds |
↳ billDuration | number | Actual call duration in seconds |
↳ billedDuration | number | Duration rounded to the billing increment, in seconds |
↳ totalAmount | string | Amount charged for the call |
↳ totalRate | string | Per-minute rate |
↳ parentCallUuid | string | UUID of the A-leg |
↳ hangupCauseName | string | Why the call ended, e.g. "Normal Hangup" or "Busy Line". Use it for the outcome. |
↳ hangupCauseCode | number | Numeric hangup cause |
↳ hangupSource | string | Who hung up: Caller, Callee, Plivo, API Request, Answer XML, Error, or Unknown |
↳ stirVerification | string | STIR/SHAKEN status: Verified, Not Verified, or Not Applicable |
↳ resourceUri | string | API path of the call record |
Hang up one ongoing Plivo call by its call UUID.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
callUuid | string | Yes | UUID of the ongoing call to hang up |
| Parameter | Type | Description |
|---|
callUuid | string | UUID of the call that was hung up |
hungUp | boolean | True when Plivo accepted the hangup (HTTP 204) |
Send an SMS or MMS (or a free-form WhatsApp message in an open conversation) through Plivo. Returns one message UUID per recipient; delivery is reported later to the status URL.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
src | string | No | Sender: a Plivo number, short code, or alphanumeric sender ID. Required unless a Powerpack UUID is set. |
dst | string | Yes | Recipient in E.164 format, e.g. 14156667777. Separate several recipients with "<". |
text | string | No | Message text. SMS allows up to 1600 GSM or 737 Unicode characters; WhatsApp up to 4096. |
type | string | No | sms (default), mms, or whatsapp |
mediaUrls | string | No | Comma-separated media URLs: up to 10 for MMS (under 5 MB total), or one for WhatsApp |
url | string | No | URL Plivo sends delivery status updates to, such as a Plivo Message Status trigger URL |
method | string | No | HTTP method for the status URL: GET or POST (default POST) |
messageExpiry | number | No | Seconds the message may wait in the queue before it expires (5 to 10799) |
log | string | No | What Plivo logs: "true" (default), "false", "content_only", or "number_only" (for GDPR redaction) |
trackable | boolean | No | Mark the message as trackable, e.g. a 2FA code, for conversion feedback |
powerpackUuid | string | No | Powerpack UUID to send from a number pool instead of a single sender |
| Parameter | Type | Description |
|---|
message | string | Plivo status text, e.g. "message(s) queued" |
messageUuids | array | One message UUID per recipient. Use it with Get Message. |
apiId | string | Plivo API request ID |
Send a Meta-approved WhatsApp template message through Plivo, the only way a business can start a WhatsApp conversation. The sender must be a WhatsApp Business number connected in Plivo.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
src | string | Yes | Your WhatsApp Business number registered with Plivo, in E.164 format |
dst | string | Yes | Recipient WhatsApp number in E.164 format |
templateName | string | Yes | Name of the approved template, e.g. order_update |
language | string | Yes | Template language code, e.g. en_US or hi |
components | json | No | JSON array of template components with their dynamic values, e.g. [{"type":"body","parameters":[{"type":"text","text":"Asha"}]}]. Header parameters can be text or media; buttons take sub_type, index, and a payload or text parameter. |
url | string | No | URL Plivo sends delivery status updates to, such as a Plivo Message Status trigger URL |
method | string | No | HTTP method for the status URL: GET or POST (default POST) |
messageExpiry | number | No | Seconds the message may wait in the queue before it expires (5 to 10799) |
log | string | No | What Plivo logs: "true" (default), "false", "content_only", or "number_only" (for GDPR redaction) |
trackable | boolean | No | Mark the message as trackable, e.g. a 2FA code, for conversion feedback |
powerpackUuid | string | No | Powerpack UUID to send from a number pool instead of a single sender |
| Parameter | Type | Description |
|---|
message | string | Plivo status text, e.g. "message(s) queued" |
messageUuids | array | One message UUID per recipient. Use it with Get Message. |
apiId | string | Plivo API request ID |
Get the delivery state, cost, and error code of one Plivo SMS, MMS, or WhatsApp message.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
messageUuid | string | Yes | UUID of the message, as returned by Send Message |
| Parameter | Type | Description |
|---|
messageUuid | string | Unique message identifier (message_uuid) |
messageTime | string | When the message was sent or received |
messageDirection | string | inbound or outbound |
messageState | string | Outbound: queued, sent, failed, delivered, undelivered, or read (WhatsApp). Inbound: received, delivered, or undelivered. |
messageType | string | sms, mms, or whatsapp |
fromNumber | string | Sender |
toNumber | string | Recipient |
units | number | Number of units the message used |
totalRate | string | Charge per unit |
totalAmount | string | Total charge |
errorCode | string | Plivo error code; "000" means delivered |
conversationId | string | WhatsApp conversation ID |
conversationOrigin | string | WhatsApp conversation category: utility, authentication, marketing, or service |
List Plivo SMS, MMS, and WhatsApp message records with optional filters for direction, state, type, and time.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
messageDirection | string | No | inbound or outbound |
messageState | string | No | queued, sent, delivered, undelivered, failed, or received |
messageType | string | No | sms, mms, or whatsapp |
messageTimeGt | string | No | Only messages after this time (yyyy-MM-dd HH:mm:ss) |
messageTimeLt | string | No | Only messages before this time (yyyy-MM-dd HH:mm:ss) |
errorCode | number | No | Only messages with this Plivo error code |
subaccount | string | No | Only messages of this subaccount Auth ID |
powerpackId | string | No | Only messages sent through this Powerpack |
limit | number | No | Results per page, 1 to 20 (default 20) |
offset | number | No | Number of results to skip, for paging |
| Parameter | Type | Description |
|---|
meta | json | Pagination: limit, offset, totalCount, next, and previous |
↳ limit | number | Results per page |
↳ offset | number | Results skipped |
↳ totalCount | number | Total matching records |
↳ next | string | API path of the next page |
↳ previous | string | API path of the previous page |
messages | array | Message detail records |
↳ messageUuid | string | Unique message identifier (message_uuid) |
↳ messageTime | string | When the message was sent or received |
↳ messageDirection | string | inbound or outbound |
↳ messageState | string | Outbound: queued, sent, failed, delivered, undelivered, or read (WhatsApp). Inbound: received, delivered, or undelivered. |
↳ messageType | string | sms, mms, or whatsapp |
↳ fromNumber | string | Sender |
↳ toNumber | string | Recipient |
↳ units | number | Number of units the message used |
↳ totalRate | string | Charge per unit |
↳ totalAmount | string | Total charge |
↳ errorCode | string | Plivo error code; "000" means delivered |
↳ conversationId | string | WhatsApp conversation ID |
↳ conversationOrigin | string | WhatsApp conversation category: utility, authentication, marketing, or service |
List the phone numbers rented on your Plivo account, with their type, capabilities, monthly rate, and renewal date.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
type | string | No | local, mobile, fixed, national, or tollfree |
numberStartswith | string | No | Only numbers starting with this prefix, e.g. 91 or 1415 |
services | string | No | Only numbers with these services: voice, sms, mms, or a combination like voice,sms |
alias | string | No | Only the number with this exact alias |
subaccount | string | No | Only numbers of this subaccount Auth ID |
limit | number | No | Results per page, 1 to 20 (default 20) |
offset | number | No | Number of results to skip, for paging |
| Parameter | Type | Description |
|---|
meta | json | Pagination: limit, offset, totalCount, next, and previous |
↳ limit | number | Results per page |
↳ offset | number | Results skipped |
↳ totalCount | number | Total matching records |
↳ next | string | API path of the next page |
↳ previous | string | API path of the previous page |
numbers | array | Rented phone numbers |
↳ number | string | The phone number |
↳ alias | string | Alias |
↳ addedOn | string | Date rented (YYYY-MM-DD) |
↳ application | string | Linked application path |
↳ carrier | string | Plivo or the incoming carrier |
↳ region | string | City and country |
↳ numberType | string | local, fixed, tollfree, mobile, or national |
↳ monthlyRentalRate | string | Monthly fee in USD |
↳ renewalDate | string | Next billing date |
↳ smsEnabled | boolean | Can receive SMS |
↳ mmsEnabled | boolean | Can receive MMS |
↳ voiceEnabled | boolean | Can receive calls |
↳ resourceUri | string | API path of the number |
Search Plivo's inventory for phone numbers available to buy in a country, with their setup fee, monthly rental, capabilities, and any verification needed.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
countryIso | string | Yes | Two-letter ISO country code, e.g. US or IN |
type | string | No | tollfree, local, mobile, national, or fixed |
pattern | string | No | Digits the number should contain after the country code, e.g. 415 |
services | string | No | Required capabilities: voice, sms, mms, voice,sms, or voice,sms,mms |
city | string | No | City name, for local numbers only |
region | string | No | Region name, e.g. Frankfurt, for fixed numbers only |
npanxx | number | No | Six-digit NPA-NXX prefix (US and Canada only) |
localCallingArea | boolean | No | Expand an NPA-NXX search to its local calling area |
lata | number | No | LATA code (US and Canada only) |
rateCenter | string | No | Rate center (US and Canada only) |
limit | number | No | Results per page, 1 to 20 (default 20) |
offset | number | No | Number of results to skip, for paging |
| Parameter | Type | Description |
|---|
meta | json | Pagination: limit, offset, totalCount, next, and previous |
↳ limit | number | Results per page |
↳ offset | number | Results skipped |
↳ totalCount | number | Total matching records |
↳ next | string | API path of the next page |
↳ previous | string | API path of the previous page |
numbers | array | Numbers available to buy |
↳ number | string | Number available to buy |
↳ prefix | string | Area code |
↳ city | string | City (null for national numbers) |
↳ country | string | Country |
↳ region | string | City and country |
↳ type | string | fixed, mobile, or tollfree |
↳ subType | string | fixed, mobile, tollfree, national, or local |
↳ setupRate | string | One-time setup fee in USD |
↳ monthlyRentalRate | string | Monthly rental in USD |
↳ smsEnabled | boolean | Can receive SMS |
↳ mmsEnabled | boolean | Can receive MMS |
↳ voiceEnabled | boolean | Can receive calls |
↳ restriction | string | Verification needed: city-address, country-address, or terms-and-conditions |
↳ restrictionText | string | What verification is needed |
↳ resourceUri | string | API path of the number |
Buy (rent) a phone number found with Search Numbers and add it to your Plivo account. This charges any setup fee now and a recurring monthly rental fee until the number is released. Numbers that need verification, such as Indian numbers, stay pending until a compliance application is accepted. Must be called with main-account credentials.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
number | string | Yes | The number to buy, exactly as returned by Search Numbers, e.g. 14155559186 |
appId | string | No | Plivo application to attach for incoming calls and messages |
cnamLookup | string | No | Caller name lookup on inbound calls: enabled or disabled (US numbers only) |
complianceApplicationId | string | No | Accepted compliance application to attach, needed for numbers such as Indian numbers. If empty, Plivo picks the latest matching accepted application. |
subaccount | string | No | Subaccount Auth ID to assign the number to |
| Parameter | Type | Description |
|---|
message | string | Plivo status text, "created" on success |
status | string | Order status, e.g. fulfilled, or pending while verification is reviewed |
numbers | array | Each number in the order with its status |
↳ number | string | Phone number |
↳ status | string | Purchase status, e.g. Success |
apiId | string | Plivo API request ID |
Look up a phone number with the Plivo Lookup API: validity and formats, country, carrier name, line type (mobile, fixed, voip, toll-free), and whether it was ported (US and Canada). Plivo bills each lookup.
| Parameter | Type | Required | Description |
|---|
authId | string | Yes | Plivo Auth ID (the Basic auth username), from the Plivo console overview page |
authToken | string | Yes | Plivo Auth Token (the Basic auth password), from the Plivo console overview page |
phoneNumber | string | Yes | Phone number in E.164 format, e.g. +14155551234 |
| Parameter | Type | Description |
|---|
phoneNumber | string | The number in E.164 format |
country | json | Country of the number |
↳ name | string | Country name |
↳ iso2 | string | Two-letter ISO code |
↳ iso3 | string | Three-letter ISO code |
format | json | The number in each standard format |
↳ e164 | string | E.164 format |
↳ national | string | National format |
↳ international | string | International format |
↳ rfc3966 | string | RFC 3966 tel: URI |
carrier | json | Carrier details |
↳ mobileCountryCode | string | MCC (empty for fixed numbers) |
↳ mobileNetworkCode | string | MNC (empty for fixed numbers) |
↳ name | string | Carrier name |
↳ type | string | fixed, mobile, voip, toll-free, or unknown |
↳ ported | string | yes, no, or unknown (US and Canada only) |
apiId | string | Plivo API request ID |
A Trigger is a block that starts a workflow when an event happens in this service.
Trigger workflow when a Plivo call ends, from the hangup URL callback
| Parameter | Type | Required | Description |
|---|
signingAuthToken | string | Yes | The Auth Token of the Plivo account or subaccount that owns the number or call. Used only to verify that each request was signed by Plivo. |
| Parameter | Type | Description |
|---|
callUuid | string | Unique call identifier (CallUUID) |
requestUuid | string | Request UUID returned when the call was placed (RequestUUID) |
from | string | Caller ID of the call |
to | string | Number that was called |
direction | string | inbound or outbound |
event | string | Callback event, e.g. Hangup (or Ring on a ring URL) |
callStatus | string | completed, busy, failed, timeout, no-answer, ringing, or in-progress |
hangupCause | string | Why the call ended, e.g. NORMAL_CLEARING |
startTime | string | When the call was started |
answerTime | string | When the call was answered |
endTime | string | When the call ended |
duration | number | Call duration in seconds |
billDuration | number | Billed duration in seconds |
totalCost | string | Total cost of the call |
aLegUuid | string | UUID of the first call leg (ALegUUID) |
carrierFailoverTriggered | boolean | True only when Plivo attempted an automatic carrier failover |
raw | json | Every field Plivo sent |
Trigger workflow when a Plivo number receives an SMS, MMS, or WhatsApp message
| Parameter | Type | Required | Description |
|---|
signingAuthToken | string | Yes | The Auth Token of the Plivo account or subaccount that owns the number or call. Used only to verify that each request was signed by Plivo. |
| Parameter | Type | Description |
|---|
messageUuid | string | Unique message identifier (MessageUUID) |
from | string | Sender's phone number |
to | string | Your Plivo number that received the message |
text | string | Message text |
type | string | sms, mms, or whatsapp |
mediaUrls | array | Media URLs of an MMS, from Media0 to MediaN |
raw | json | Every field Plivo sent |
Trigger workflow when Plivo reports a delivery status for an SMS, MMS, or WhatsApp message
| Parameter | Type | Required | Description |
|---|
signingAuthToken | string | Yes | The Auth Token of the Plivo account or subaccount that owns the number or call. Used only to verify that each request was signed by Plivo. |
| Parameter | Type | Description |
|---|
messageUuid | string | Unique message identifier (MessageUUID) |
status | string | queued, sent, delivered, undelivered, failed, or read (WhatsApp) |
from | string | Sender ID of the message |
to | string | Recipient number |
errorCode | string | Plivo error code when delivery failed |
units | number | Number of message units |
totalRate | string | Charge per unit |
totalAmount | string | Total charge |
mcc | string | Mobile Country Code of the recipient |
mnc | string | Mobile Network Code of the recipient |
raw | json | Every field Plivo sent |