Application

The Application API lets you perform actions on your Plivo application. A Plivo application is a set of Answer, Hangup and Message URL which help you control your incoming call and message.

The following actions can be performed with the Application API.

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 following XML.

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

Plivo will request the Answer URL with the following parameters

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.

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.

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.
HangupCause
string Contains the standard telephony hangup cause of a call (inbound and outbound).
Duration
string Contains the duration of the call in seconds.
BillDuration
string Contains the billed duration of the call in seconds.

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.

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.

Create an Application

Create an application on Plivo by calling this API. Creating an application is usually the first step, after which you would attach this application either to a number or an endpoint.

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

Arguments

Parameter Description
answer_url (mandatory) The URL Plivo will fetch when a call executes this application. More details
app_name (mandatory) The name of your application
answer_method (optional) The method used to call the answer_url. Defaults to POST.
hangup_url (optional) The URL that will be notified by Plivo when the call hangs up. Defaults to answer_url. More details
hangup_method (optional) The method used to call the hangup_url. Defaults to POST.
fallback_answer_url (optional) Invoked by Plivo only if answer_url is unavailable or the XML response is invalid. Should contain a XML response.
fallback_method (optional) The method used to call the fallback_answer_url. Defaults to POST.
message_url (optional) The URL that will be notified by Plivo when an inbound message is received. Defaults not set. More details
message_method (optional) The method used to call the message_url. Defaults to POST.
default_number_app (optional) Boolean parameter. If set to true, this parameter ensures that newly created numbers, which don't have an app_id, point to this application.
default_endpoint_app (optional) Boolean parameter. If set to true, this parameter ensures that newly created endpoints, which don't have an app_id, point to this application.
subaccount (optional) Id of the subaccount, in case only subaccount applications are needed.

Response

HTTP Status Code: 201

{
  "message": "created",
  "app_id": "15784735442685051",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}

Get Details of All Applications

Theis API is used to get details of all the application that have been created under your Plivo account.

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

Arguments

Parameter Description
subaccount (optional) Id of the subaccount, in case only subaccount applications are needed.
limit (optional) Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset (optional) Denotes the number of value items by which the results should be offset. Eg:- If the result contains a 1000 values and limit is set to 10 and offset is set to 705, then values 706 through 715 are displayed in the results. This parameter is also used for pagination of the results.

Response

HTTP Status Code: 200

{
    "api_id": "e5b05b26-10c4-11e4-a2d1-22000ac5040c",
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 19
    },
    "objects": [
        {
            "answer_url": "http://webapp.com/dial.xml",
            "answer_method": "GET",
            "app_id": "20372631212782780",
            "app_name": "Dial Office",
            "default_app": false,
            "enabled": true,
            "fallback_answer_url": "",
            "fallback_method": "POST",
            "hangup_method": "POST",
            "hangup_url": "http://webapp.com/dial.xml",
            "message_method": "POST",
            "message_url": "",
            "public_uri": false,
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/20372631212782780/",
            "sip_uri": "sip:20372631212782780@app.plivo.com",
            "sub_account": null
        },
        {
            "answer_url": "https://webapp.com/conference_court.xml",
            "answer_method": "GET",
            "app_id": "14260623927192078",
            "app_name": "Conference_Court",
            "default_app": false,
            "enabled": true,
            "fallback_answer_url": "",
            "fallback_method": "POST",
            "hangup_method": "POST",
            "hangup_url": "https://webapp.com/conference_court.xml",
            "message_method": "POST",
            "message_url": "",
            "public_uri": false,
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/14260623927192078/",
            "sip_uri": "sip:142606239271920703@app.plivo.com",
            "sub_account": null
        }
    ]
}

Response Attributes

answer_url
string On receiving an incoming call on a number of an endpoint attached to the application, Plivo will send a request to the answer_url with the attributes of the call. We expect a valid Plivo XML to be returned as a response to the request Plivo makes.
answer_method
string The HTTP method which will be used to request the answer_url when an incoming call is answered on the number or the endpoint attached to the application.
app_name
string A friendly name for your Plivo application.
default_app
string Default app.
enabled
boolean Set to true if the application is enabled.
fallback_answer_url
string Plivo will request this URL with the same parameters sent to the answer_url if the answer_url returns a non 200 HTTP status code.
fallback_answer_method
string The HTTP method which will be used to request the fallback_answer_url when the answer_url returns a non 200 HTTP status code.
hangup_url
string When the incoming call is hung up on a number or an endpoint attached to the application, Plivo will send a request to the hangup_url with the attributes of the call.
hangup_method
string The HTTP method which will be used to request the hangup_url when an incoming call is hung up on the number or the endpoint attached to the application.
message_url
string When an incoming message (SMS) is received to a number attached to the application, Plivo will make a request to the message_url with the parameters documented here.
message_method
string The HTTP method which will be used to request the message_url when an incoming message (SMS) is received on the number attached to the application
public_uri
boolean Set to true is the application can be called from an external SIP service. By default the application is not public, and external SIP services cannot call your application SIP URI.
sip_uri
string The SIP URI of the application. All Plivo applications can be called directly without attaching them to a number or an endpoint. When an incoming call is received on this URI, Plivo will follow the same flow as it does with a number or an endpoint.
subaccount
string The subaccount associated with the application. If the application belongs to the main account, this field will be null

Get Details of a Single Application

Get details of an particular application by passing the app_id. This API returns all the information linked with the application.

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

Arguments

None

Response

HTTP Status Code:200

{
    "answer_method": "GET",
    "answer_url": "http://webapp.com/dial.xml",
    "app_id": "20372631212782780",
    "app_name": "Dial Office",
    "default_app": false,
    "enabled": true,
    "fallback_answer_url": "",
    "fallback_method": "POST",
    "hangup_method": "POST",
    "hangup_url": "http://webapp.com/dial.xml",
    "message_method": "POST",
    "message_url": "",
    "public_uri": false,
    "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/20372631212782780/",
    "sip_uri": "sip:20372631212782780@app.plivo.com",
    "sub_account": null
}

Modify an Application

Modify an application using this API.

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

Arguments

Parameter Description
answer_url (optional) The URL invoked by Plivo when a call executes this application.
answer_method (optional) The method used to call the answer_url. Defaults to POST
hangup_url (optional) The URL that is notified by Plivo when the call hangs up.
hangup_method (optional) The method used to call the hangup_url. Defaults to POST
fallback_answer_url (optional) Invoked by Plivo only if answer_url is unavailable or the XML response is invalid. Should contain a XML response.
fallback_method (optional) The method used to call the fallback_answer_url. Defaults to POST.
message_url (optional) The URL that is notified by Plivo when an inbound message is received. Defaults not set.
message_method (optional) The method used to call the message_url. Defaults to POST.
default_number_app (optional) If set to true, associates all newly created Plivo numbers that have not specified an app_id, to this application.Takes a value of True or False.
default_endpoint_app (optional) If set to true, associates all newly created Plivo endpoints that have not specified an app_id, to this application.Takes a values of True or False.
subaccount (optional) Id of the subaccount, in case only subaccount applications are needed.

Response

HTTP Status Code: 202

{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}

Delete an Application

This API would delete the Plivo application. Use this API wisely, once an application is deleted, it cannot be retrived.

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

Arguments

None

Response

HTTP Status Code: 204