Application

An Application is a set of Answer, Hangup and Message URL which help you control your incoming calls and messages.

API Endpoint

BaseURI https://api.plivo.com/v1/Account/{auth_id}/Application/

Answer URL

Plivo will request this URL for a valid Plivo XML on an incoming call. The XML returned by this URL will decide the flow of the call. For eg. If you want to play a message on an incoming call to your Plivo number, the URL must return the XML as shown in the example response.

Plivo will request the Answer URL with the following parameters:

Parameters Plivo sends to the Answer URL

CallUUID string

A unique identifier for this call.

From string

The phone number of the party that initiated the call along with the country code. If the call is inbound, then it is the caller’s caller ID. If the call is outbound i.e. initiated via a request to the API, then this is the phone number you specify as the caller ID.

To string

The phone number of the called party with the country code. If the call is inbound, then it’s your incoming phone number. If the call is outbound, then it’s the phone number you provided to call.

ForwardedFrom string

This parameter is set only when the call received by Plivo is a forwarded call. Its value depends on the caller’s carrier. Not all carriers pass this information.

CallStatus string

Indicates the status of the call. The value is set to either ringing, in- progress,or completed. In case the call is hung up, the CallStatus is set to completed for inbound calls and to completed, busy, failed, timeout or no- answer for outbound calls.

Direction string

Indicates the direction of the call. In most cases this will be inbound, wherein the call would be in a ringing state. If you are using the Call API, the direction will be outbound, wherein the call will be in an answered state.

ALegUUID string

This contains a unique identifier which identifies the first leg of the call in case it is outbound. If the call direction is inbound, this parameter will not be present.

ALegRequestUUID string

Contains a unique request identifier which is returned by Plivo in case of a API request during an outbound call. In case the call direction is inbound, this parameter will not be present.

Hangup URL

Plivo will make an HTTP request to this URL when the call is hung up. The following parameters will be sent to the Hangup URL:

Parameters Plivo sends to the Hangup URL

CallUUID string

A unique identifier for this call.

From string

The phone number of the party that initiated the call along with the country code. If the call is inbound, then it is the caller’s caller ID. If the call is outbound i.e. initiated via a request to the API, then this is the phone number you specify as the caller ID.

To string

The phone number of the called party with the country code. If the call is inbound, then it’s your incoming phone number. If the call is outbound, then it’s the phone number you provided to call.

ForwardedFrom string

This parameter is set only when the call received by Plivo is a forwarded call. Its value depends on the caller’s carrier. Not all carriers pass this information.

CallStatus string

Indicates the status of the call. The value is set to either ringing, in-progress,or completed. In case the call is hung up, the CallStatus is set to completed for inbound calls and to completed, busy, failed, timeout or no-answer for outbound calls.

Direction string

Indicates the direction of the call. In most cases this will be inbound, wherein the call would be in a ringing state. If you are using the Call API, the direction will be outbound, wherein the call will be in an answered state.

ALegUUID string

This contains a unique identifier which identifies the first leg of the call in case it is outbound. If the call direction is inbound, this parameter will not present.

ALegRequestUUID string

Contains a unique request identifier which is returned by Plivo in case of a API request during an outbound call. In case the call direction is inbound, this parameter will not be present.

Duration string

Contains the duration of the call in seconds.

BillDuration string

Contains the billed duration of the call in seconds.

HangupCauseName string

The reason for the call hangup. Refer to this guide for a comprehensive list of hangup causes and sources.

HangupCauseCode integer

A unique integer code for the hangup cause. Refer to this guide for a comprehensive list of hangup causes and sources.

HangupSource string

The entity that triggered the call hangup. Possible hangup sources are: Caller, Callee, Plivo, API Request, Answer XML, Error, and Unknown

Refer to this guide for a comprehensive list of hangup causes and sources.

Message URL

Plivo will send all incoming messages to this URL. We expect to receive a HTTP Status Code of 200 from this URL. If a non 200 code is returned, we would keep retrying this URL once every 5 minutes for the first hour and then once every hour post that for 24 hours. Plivo will drop the message after 24 hours of retry.

The following parameters will be sent to the Message URL.

Parameters Plivo sends to the Message URL

From string

The source number of the incoming message. This will be the number of the person sending a message to a Plivo number.

To string

The number to which the message was sent. This will the your Plivo number on which the message has been received.

Type string

Type of the message. This will always be sms

Text string

The content of the message.

MessageUUID string

A unique ID for the message. Your message can be uniquely identified on Plivo by this ID.

Response

<Response>
    <Speak>Hello, thanks for call</Speak>
</Response>