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.

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:20372631212782780@app.plivo.com",
  "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

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

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:20372631212782780@app.plivo.com",
  "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)

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.

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

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

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

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

​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