import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.create(
    from_='+12025550000',
    to_='+12025551111',
    answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml',
    answer_method='GET', )
print(response)

This method lets you initiate an outbound call to a PSTN number or a SIP endpoint, and make simultaneous bulk calls.

​
API Endpoint

POST
https://api.plivo.com/v1/Account/{auth_id}/Call/

​
Arguments

ParameterDescription
from (Required)The caller ID phone number in E.164 format (e.g., 14157654321).
to (Required) Destination number(s) or SIP URI(s). Use < to separate multiple destinations (max 1000).
Examples: 14157654321, sip:john1234@phone.plivo.com, 14157654321<14153464321<sip:john1234@phone.plivo.com
answer\_url (Required)URL called when the call is answered. Must return valid Plivo XML.
answer\_methodHTTP verb for answer_url. Default is POST.
ring\_urlOptional URL notified when the call starts ringing.
ring\_methodHTTP verb for ring_url. Default is POST.
hangup\_urlOptional URL notified when the call is hung up.
hangup\_methodHTTP verb for hangup_url. Default is POST.
fallback\_urlInvoked if answer_url fails after 3 retries or 60s timeout.
fallback\_methodHTTP verb for fallback_url. Default is POST.
caller\_nameSets caller name (up to 50 characters). Defaults to caller’s name.
send\_digitsSends DTMF digits after call is connected. Use w (0.5s wait) or W (1s wait).
Example: 1w2W3 or 123@1000 (1000ms tone).
send\_on\_preanswerIf true, sends send_digits during pre-answer. Default: false.
time\_limitMax duration of call in seconds (after answered). Default: 14400 (4 hours). Calls ≥ 86400s are disconnected at 24h.
hangup\_on\_ringMax duration (in seconds) from start of ringing to hangup.
machine\_detectionDetect machine on answer. Values: true, hangup.
machine\_detection\_timeTime in ms to detect machine. Default: 5000. Allowed: 2000–10000.
machine\_detection\_urlCallback URL for asynchronous machine detection.
machine\_detection\_methodHTTP verb for machine_detection_url. Default: POST.
machine\_detection\_maximum\_speech\_lengthMax speech duration in ms. Default: 5000. Allowed: 1000–6000.
machine\_detection\_initial\_silenceMax silence after answer (ms). Default: 4500. Allowed: 2000–10000.
machine\_detection\_maximum\_wordsMax number of sentences. Default: 3. Allowed: 2–10.
machine\_detection\_initial\_greetingMax greeting length (ms). Default: 1500. Allowed: 1000–5000.
machine\_detection\_silenceSilence after greeting (in ms). (description cut off in original)

​
Callbacks

For every single voice call you make and receive, Plivo sends a status update to your URL configured as a callback. You can read and store the information on your server for analysis, and you can change the flow of ongoing calls based on the values received in the callback events.

Callbacks involve URLs such as answer_url, fallback_url, hangup_url, and ring_url.

​
List of parameters sent to ring_url

ParameterTypeDescription
FromstringThe from number used as the caller ID to initiate the call.
TostringThe destination that’s called.
RequestUUIDstringAn identifier that can uniquely identify a request.
ALegRequestUUIDstringIdentifies the first leg of the call in case there are multiple legs.
CallUUIDstringThe identifier of the call.
DirectionstringThe direction of the call. This will have the value "outbound" since this is an outbound API call.
EventstringThe event that triggered this notification. This will have the value "Ring".
CallStatusstringThe status of the call. This will have the value "ringing".
SessionStartstringA timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
STIRAttestationstringGives details about the attestation assigned to the call by Plivo.

​
List of parameters sent to answer_url and fallback_url

ParameterTypeDescription
FromstringThe from number used as the caller ID to initiate the call.
TostringThe destination that’s called.
CallerNamestringThe name of the caller, if the call was made from a SIP endpoint. This field is empty if no caller name is specified while making the call.
RequestUUIDstringAn identifier that can uniquely identify a call.
ALegRequestUUIDstringIdentifies the first leg of the call in case there are multiple legs.
CallUUIDstringThe identifier of the call.
DirectionstringThe direction of the call. This will have the value "outbound" since this is an outbound API call.
ALegUUIDstringA unique identifier for the A leg of the call.
EventstringThe event that triggered this notification. This will have the value "StartApp".
STIRVerificationstringFor outbound calls: Provides attestation details assigned by Plivo.
For inbound calls: Provides attestation details received on the inbound call to your Plivo number.
Possible values:
- Verified: The call is from a verified caller (attestation level A).
- Not Verified: Caller is not verified or uncertain (attestation level B or C).
- Not Applicable: STIR/SHAKEN doesn’t apply (e.g., non-US number or WebRTC/SIP calls). Read more about STIR/SHAKEN
CallStatusstringThe status of the call. This will have the value "in-progress".
SessionStartstringA timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
STIRAttestationstringGives details about the attestation assigned to the call by Plivo.

​
List of parameters sent to hangup_url

ParameterTypeDescription
FromstringThe from number used as the caller ID to initiate the call.
TostringThe destination that’s called.
RequestUUIDstringAn identifier that can uniquely identify a call.
ALegRequestUUIDstringIdentifies the first leg of the call in case there are multiple legs.
CallUUIDstringThe identifier of the call.
DirectionstringThe direction of the call. This will be "outbound" since this is an outbound API call.
ALegUUIDstringA unique identifier for the A leg of the call.
EventstringThe event that triggered this notification. This will have the value "Hangup".
stir_verificationstringFor outbound calls: Gives details about the attestation assigned to the call by Plivo.
For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number.

Possible values:
  • Verified: The call is from a verified caller who has authorized access to the customer’s caller ID (attestation level A).
  • Not Verified: Either the caller is not verified, or it’s uncertain whether they have access to the caller ID (attestation level B or C).
  • Not Applicable: STIR/SHAKEN doesn’t apply (e.g., not to a US number, or WebRTC/SIP calls).
Read more about STIR/SHAKEN
CallStatusstringThe status of the call. This will have the value "completed".
StartTimestringA timestamp that indicates when the call was initiated.
Timezone: Local timezone (as set in your Plivo Console)
Format: yyyy-MM-dd HH:mm:ss
AnswerTimestringA timestamp that indicates when the call was answered.
Timezone: Local timezone
Format: yyyy-MM-dd HH:mm:ss
SessionStartstringA timestamp that indicates when early media started.
Format: YYYY-MM-DD HH:mm:ss.sssss
Timezone: UTC
EndTimestringA timestamp that indicates when the call ended.
Timezone: Local timezone
Format: yyyy-MM-dd HH:mm:ss
STIRAttestationstringGives details about the attestation assigned to the call by Plivo.
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.create(
    from_='+12025550000',
    to_='+12025551111',
    answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml',
    answer_method='GET', )
print(response)