Application API

An Application is a set of Answer, Hangup, and Message URLs that help you control your incoming calls and messages. API Endpoint

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

The Application Object

Attributes

app_id

string

Unique identifier for the application.

app_name

string

A friendly name for your Plivo application.

answer_url

string

URL requested when an incoming call is received. Must return valid Plivo XML.

answer_method

string

HTTP method for the answer_url. Values: GET or POST.

hangup_url

string

URL notified when the call hangs up.

hangup_method

string

HTTP method for the hangup_url.

fallback_answer_url

string

URL requested when answer_url fails or returns invalid XML.

fallback_method

string

HTTP method for the fallback_answer_url.

message_url

string

URL notified when an inbound SMS is received.

message_method

string

HTTP method for the message_url.

default_app

boolean

Whether this is the default app.

enabled

boolean

Whether the application is enabled.

public_uri

boolean

Whether the app can be called from external SIP services.

sip_uri

string

SIP URI of the application.

sub_account

string

Subaccount associated with the application. Null if main account.

log_incoming_messages

boolean

Whether incoming message content is logged. Default: true.

resource_uri

string

URI of the application resource.

Example Object

{
  "answer_method": "GET",
  "answer_url": "https://example.com/answer",
  "app_id": "20372631212782780",
  "app_name": "My Application",
  "default_app": false,
  "enabled": true,
  "fallback_answer_url": "",
  "fallback_method": "POST",
  "hangup_method": "POST",
  "hangup_url": "https://example.com/hangup",
  "message_method": "POST",
  "message_url": "",
  "public_uri": false,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Application/20372631212782780/",
  "sip_uri": "sip:[email protected]",
  "sub_account": null,
  "log_incoming_messages": true
}

Answer URL Parameters

When a call is received, Plivo sends these parameters to your answer_url:

Parameter	Description
CallUUID	Unique identifier for this call
From	Caller’s phone number with country code
To	Called phone number with country code
CallStatus	Call status: `ringing`, `in-progress`, or `completed`
Direction	Call direction: `inbound` or `outbound`
ForwardedFrom	Present only for forwarded calls
ALegUUID	First leg UUID for outbound calls
ALegRequestUUID	Request UUID for API-initiated outbound calls

Hangup URL Parameters

Parameter	Description
CallUUID	Unique identifier for this call
From	Caller’s phone number
To	Called phone number
CallStatus	Final call status
Direction	Call direction
Duration	Call duration in seconds
BillDuration	Billed duration in seconds
HangupCauseName	Reason for hangup
HangupCauseCode	Hangup cause code
HangupSource	Entity that triggered hangup

Message URL Parameters

Parameter	Description
From	Source number of incoming message
To	Your Plivo number that received the message
Type	Always `sms`
Text	Message content
MessageUUID	Unique message identifier

Create an Application

Creates a new application.

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

Arguments

app_name

string

required

Application name. Allowed: alphanumeric, hyphen (-), underscore (_).

answer_url

string

required

URL fetched when a call executes this application.

answer_method

string

HTTP method for answer_url. Default: POST.

hangup_url

string

URL notified when call hangs up. Default: answer_url.

hangup_method

string

HTTP method for hangup_url. Default: POST.

fallback_answer_url

string

Fallback URL if answer_url fails.

fallback_method

string

HTTP method for fallback_answer_url. Default: POST.

message_url

string

URL notified for inbound messages.

message_method

string

HTTP method for message_url. Default: POST.

default_number_app

boolean

Make this the default app for new numbers.

default_endpoint_app

boolean

Make this the default app for new endpoints.

subaccount

string

Subaccount ID to associate with this application.

log_incoming_messages

boolean

Log incoming message content. Default: true.

Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.create(
    app_name='MyApp',
    answer_url='https://example.com/answer')
print(response)

Response

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

Retrieve an Application

Get details of a specific application.

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

Arguments

No arguments required.

Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.get(app_id='15784735442685051')
print(response)

Response

{
  "answer_method": "GET",
  "answer_url": "https://example.com/answer",
  "app_id": "20372631212782780",
  "app_name": "My Application",
  "default_app": false,
  "enabled": true,
  "fallback_answer_url": "",
  "fallback_method": "POST",
  "hangup_method": "POST",
  "hangup_url": "https://example.com/hangup",
  "message_method": "POST",
  "message_url": "",
  "public_uri": false,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Application/20372631212782780/",
  "sip_uri": "sip:[email protected]",
  "sub_account": null,
  "log_incoming_messages": true
}

List All Applications

Returns all applications sorted by creation date.

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

Arguments

subaccount

string

Filter by subaccount ID.

app_name

string

Filter by app name prefix.

limit

integer

Results per page. Maximum 20.

offset

integer

Pagination offset.

Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.list(offset=0, limit=5)
print(response)

Response

{
  "api_id": "e5b05b26-10c4-11e4-a2d1-22000ac5040c",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "answer_method": "GET",
      "answer_url": "https://example.com/answer",
      "app_id": "20372631212782780",
      "app_name": "My Application",
      "default_app": false,
      "enabled": true,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Application/20372631212782780/"
    }
  ]
}

Update an Application

Modify an existing application.

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

Arguments

answer_url

string

URL fetched when a call executes this application.

answer_method

string

HTTP method for answer_url.

hangup_url

string

URL notified when call hangs up.

hangup_method

string

HTTP method for hangup_url.

fallback_answer_url

string

Fallback URL if answer_url fails.

fallback_method

string

HTTP method for fallback_answer_url.

message_url

string

URL notified for inbound messages.

message_method

string

HTTP method for message_url.

default_number_app

boolean

Make this the default app for new numbers.

default_endpoint_app

boolean

Make this the default app for new endpoints.

subaccount

string

Subaccount ID to associate.

log_incoming_messages

boolean

Log incoming message content.

Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.update(
    app_id='21686794894743506',
    answer_url='https://updated.answer.url')
print(response)

Response

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

Delete an Application

Permanently deletes an application.

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

Arguments

cascade

boolean

Delete associated endpoints. Default: true.

new_endpoint_application

string

App ID to reassign endpoints to when cascade is false.

Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.delete(app_id='21686794894743506')
print(response)

Response

HTTP Status Code: 204

Concepts

API Reference

Application API

The Application Object

Attributes

Example Object

Answer URL Parameters

Hangup URL Parameters

Message URL Parameters

Create an Application

Arguments

Example

Response

Retrieve an Application

Arguments

Example

Response

List All Applications

Arguments

Example

Response

Update an Application

Arguments

Example

Response

Delete an Application

Arguments

Example

Response

Concepts

API Reference

​The Application Object

​Attributes

​Example Object

​Answer URL Parameters

​Hangup URL Parameters

​Message URL Parameters

​Create an Application

​Arguments

​Example

​Response

​Retrieve an Application

​Arguments

​Example

​Response

​List All Applications

​Arguments

​Example

​Response

​Update an Application

​Arguments

​Example

​Response

​Delete an Application

​Arguments

​Example

​Response

The Application Object

Attributes

Example Object

Answer URL Parameters

Hangup URL Parameters

Message URL Parameters

Create an Application

Arguments

Example

Response

Retrieve an Application

Arguments

Example

Response

List All Applications

Arguments

Example

Response

Update an Application

Arguments

Example

Response

Delete an Application

Arguments

Example

Response