Make an outbound call

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

Parameter	Description
`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_method`	HTTP verb for `answer_url`. Default is `POST`.
`ring_url`	Optional URL notified when the call starts ringing.
`ring_method`	HTTP verb for `ring_url`. Default is `POST`.
`hangup_url`	Optional URL notified when the call is hung up.
`hangup_method`	HTTP verb for `hangup_url`. Default is `POST`.
`fallback_url`	Invoked if `answer_url` fails after 3 retries or 60s timeout.
`fallback_method`	HTTP verb for `fallback_url`. Default is `POST`.
`caller_name`	Sets caller name (up to 50 characters). Defaults to caller’s name.
`send_digits`	Sends DTMF digits after call is connected. Use `w` (0.5s wait) or `W` (1s wait). Example: `1w2W3` or `123@1000` (1000ms tone).
`send_on_preanswer`	If `true`, sends `send_digits` during pre-answer. Default: `false`.
`time_limit`	Max duration of call in seconds (after answered). Default: `14400` (4 hours). Calls ≥ 86400s are disconnected at 24h.
`hangup_on_ring`	Max duration (in seconds) from start of ringing to hangup.
`machine_detection`	Detect machine on answer. Values: `true`, `hangup`.
`machine_detection_time`	Time in ms to detect machine. Default: `5000`. Allowed: `2000`–`10000`.
`machine_detection_url`	Callback URL for asynchronous machine detection.
`machine_detection_method`	HTTP verb for `machine_detection_url`. Default: `POST`.
`machine_detection_maximum_speech_length`	Max speech duration in ms. Default: `5000`. Allowed: `1000`–`6000`.
`machine_detection_initial_silence`	Max silence after answer (ms). Default: `4500`. Allowed: `2000`–`10000`.
`machine_detection_maximum_words`	Max number of sentences. Default: `3`. Allowed: `2`–`10`.
`machine_detection_initial_greeting`	Max greeting length (ms). Default: `1500`. Allowed: `1000`–`5000`.
`machine_detection_silence`	Silence 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

Parameter	Type	Description
`From`	`string`	The from number used as the caller ID to initiate the call.
`To`	`string`	The destination that’s called.
`RequestUUID`	`string`	An identifier that can uniquely identify a request.
`ALegRequestUUID`	`string`	Identifies the first leg of the call in case there are multiple legs.
`CallUUID`	`string`	The identifier of the call.
`Direction`	`string`	The direction of the call. This will have the value `"outbound"` since this is an outbound API call.
`Event`	`string`	The event that triggered this notification. This will have the value `"Ring"`.
`CallStatus`	`string`	The status of the call. This will have the value `"ringing"`.
`SessionStart`	`string`	A timestamp that indicates when early media started. Format: `YYYY-MM-DD HH:mm:ss.sssss` Timezone: UTC
`STIRAttestation`	`string`	Gives details about the attestation assigned to the call by Plivo.

List of parameters sent to answer_url and fallback_url

Parameter	Type	Description
`From`	`string`	The from number used as the caller ID to initiate the call.
`To`	`string`	The destination that’s called.
`CallerName`	`string`	The 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.
`RequestUUID`	`string`	An identifier that can uniquely identify a call.
`ALegRequestUUID`	`string`	Identifies the first leg of the call in case there are multiple legs.
`CallUUID`	`string`	The identifier of the call.
`Direction`	`string`	The direction of the call. This will have the value `"outbound"` since this is an outbound API call.
`ALegUUID`	`string`	A unique identifier for the A leg of the call.
`Event`	`string`	The event that triggered this notification. This will have the value `"StartApp"`.
`STIRVerification`	`string`	For 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
`CallStatus`	`string`	The status of the call. This will have the value `"in-progress"`.
`SessionStart`	`string`	A timestamp that indicates when early media started. Format: `YYYY-MM-DD HH:mm:ss.sssss` Timezone: UTC
`STIRAttestation`	`string`	Gives details about the attestation assigned to the call by Plivo.

List of parameters sent to hangup_url

Parameter	Type	Description
`From`	`string`	The from number used as the caller ID to initiate the call.
`To`	`string`	The destination that’s called.
`RequestUUID`	`string`	An identifier that can uniquely identify a call.
`ALegRequestUUID`	`string`	Identifies the first leg of the call in case there are multiple legs.
`CallUUID`	`string`	The identifier of the call.
`Direction`	`string`	The direction of the call. This will be `"outbound"` since this is an outbound API call.
`ALegUUID`	`string`	A unique identifier for the A leg of the call.
`Event`	`string`	The event that triggered this notification. This will have the value `"Hangup"`.
`stir_verification`	`string`	For 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
`CallStatus`	`string`	The status of the call. This will have the value `"completed"`.
`StartTime`	`string`	A timestamp that indicates when the call was initiated. Timezone: Local timezone (as set in your Plivo Console) Format: `yyyy-MM-dd HH:mm:ss`
`AnswerTime`	`string`	A timestamp that indicates when the call was answered. Timezone: Local timezone Format: `yyyy-MM-dd HH:mm:ss`
`SessionStart`	`string`	A timestamp that indicates when early media started. Format: `YYYY-MM-DD HH:mm:ss.sssss` Timezone: UTC
`EndTime`	`string`	A timestamp that indicates when the call ended. Timezone: Local timezone Format: `yyyy-MM-dd HH:mm:ss`
`STIRAttestation`	`string`	Gives 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)

The Call object Machine detection

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)

Request

Response

Call

Multiparty call

Conference

Audio Stream

Verified Caller ID

Endpoint

Recording

Make an outbound call

API Endpoint

Arguments

Callbacks

List of parameters sent to ring_url

List of parameters sent to answer_url and fallback_url

List of parameters sent to hangup_url

Request

Response

Call

Multiparty call

Conference

Audio Stream

Verified Caller ID

Endpoint

Recording

​API Endpoint

​Arguments

​Callbacks

​List of parameters sent to ring_url

​List of parameters sent to answer_url and fallback_url

​List of parameters sent to hangup_url

API Endpoint

Arguments

Callbacks

List of parameters sent to ring_url

List of parameters sent to answer_url and fallback_url

List of parameters sent to hangup_url