Application API

Create and manage applications to control incoming calls and messages

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.

sip_auth_type · string

SIP authentication mode for inbound calls to the application. Values: ip_acl, credential, ip_acl_and_credential, or "" (empty, no authentication). Inbound auth applies only when the SIP INVITE Request-URI is sip:{app_id}@app.plivo.com. Changing to a mode that does not use a credential or IP ACL automatically clears the corresponding credential_uuid / ip_acl_uuid on the application (e.g., setting to ip_acl clears any previously set credential_uuid). See SIP Authentication.

ip_acl_uuid · string

UUID (36 characters) of the IP Access Control List assigned to this application. Required when sip_auth_type is ip_acl or ip_acl_and_credential. Create via SIP Authentication API.

credential_uuid · string

UUID (36 characters) of the SIP credential assigned to this application. Required when sip_auth_type is credential or ip_acl_and_credential. Create via SIP Authentication API.

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:[e-mail]",
  "sip_auth_type": "ip_acl",
  "ip_acl_uuid": "acl-xyz789-ghi012",
  "credential_uuid": null,
  "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

Python

import plivo

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

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.create('MyApp', { answerUrl: 'https://example.com/answer' })
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

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

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->create(
    'MyApp',
    ['answer_url' => 'https://example.com/answer']);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

ApplicationCreateResponse response = Application.creator("MyApp", "https://example.com/answer")
    .create();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Create(
    appName: "MyApp",
    answerUrl: "https://example.com/answer");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.Create(plivo.ApplicationCreateParams{
        AppName:   "MyApp",
        AnswerURL: "https://example.com/answer",
    })
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"answer_url": "https://example.com/answer", "app_name": "MyApp"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Application/

Response

message · string

Status of the request. Returns created on a successful creation.

app_id · string

Unique identifier for the application.

api_id · string

Unique identifier for the API request.

{
  "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

Python

import plivo

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

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.get('15784735442685051')
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.get('15784735442685051')
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->get('15784735442685051');
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

Application response = Application.getter("15784735442685051").get();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Get(appId: "15784735442685051");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.Get("15784735442685051")
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Application/15784735442685051/

Response

answer_method · string

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

answer_url · string

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

app_id · string

Unique identifier for the application.

app_name · string

A friendly name for your Plivo application.

default_app · boolean

Whether this is the default app.

enabled · boolean

Whether the application is enabled.

fallback_answer_url · string

URL requested when answer_url fails or returns invalid XML.

fallback_method · string

HTTP method for the fallback_answer_url.

hangup_method · string

HTTP method for the hangup_url.

hangup_url · string

URL notified when the call hangs up.

message_method · string

HTTP method for the message_url.

message_url · string

URL notified when an inbound SMS is received.

public_uri · boolean

Whether the app can be called from external SIP services.

resource_uri · string

URI of the application resource.

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.

{
  "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:[e-mail]",
  "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

Python

import plivo

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

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.list({ offset: 0, limit: 5 })
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

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

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->list(['limit' => 5, 'offset' => 0]);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<Application> response = Application.lister()
    .offset(0)
    .limit(5)
    .list();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.List(limit: 5, offset: 0);
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.List(plivo.ApplicationListParams{
        Offset: 0,
        Limit:  5,
    })
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Application/

Response

api_id · string

Unique identifier for the API request.

meta · object

Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching applications).

objects · array

Array of application objects — see The Application Object.

{
  "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.

sip_auth_type · string

SIP authentication mode for inbound calls. Values: ip_acl, credential, ip_acl_and_credential, or "" (empty to disable). See SIP Authentication.

ip_acl_uuid · string

UUID of the IP Access Control List to assign. Required when sip_auth_type includes ip_acl. Create one via the SIP Authentication API.

credential_uuid · string

UUID of the SIP credential to assign. Required when sip_auth_type includes credential. Create one via the SIP Authentication API.

You cannot delete a credential or IP ACL that is currently assigned to an application. Remove the assignment first by setting sip_auth_type to empty.

Example

Python

import plivo

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

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.update('15784735442685051', { answerUrl: 'https://updated.answer.url' })
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.update(
    '15784735442685051',
    answer_url: 'https://updated.answer.url')
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->update(
    '15784735442685051',
    ['answer_url' => 'https://updated.answer.url']);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

ApplicationUpdateResponse response = Application.updater("15784735442685051")
    .answerUrl("https://updated.answer.url")
    .update();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Update(
    appId: "15784735442685051",
    answerUrl: "https://updated.answer.url");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.Update("15784735442685051", plivo.ApplicationUpdateParams{
        AnswerURL: "https://updated.answer.url",
    })
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"answer_url": "https://updated.answer.url"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/

Response

message · string

Status of the request. Returns changed on a successful update.

api_id · string

Unique identifier for the API request.

{
  "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

Python

import plivo

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

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.delete('15784735442685051')
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.delete('15784735442685051')
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->delete('15784735442685051');
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

Application.deleter("15784735442685051").delete();
System.out.println("Deleted successfully.");

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Delete(appId: "15784735442685051");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    err := client.Applications.Delete("15784735442685051")
    if err == nil {
        fmt.Println("Deleted successfully.")
    }
}

curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/

Response

HTTP Status Code: 204