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)