# Account API Source: https://plivo.com/docs/account/api/account Retrieve and update your Plivo account details The `Account` object lets you perform actions on your Plivo account. You can retrieve and update account details using this API. **API Endpoint** ``` https://api.plivo.com/v1/Account/{auth_id}/ ``` *** ## The Account Object ### Attributes Account type. Values: `standard` for paid accounts, `developer` for free trial. Postal address of the account, displayed on invoices. Auth ID of the account. Whether automatic recharge is enabled when credits fall below threshold. Billing mode. Values: `prepaid` or `postpaid`. Account credits in USD. City of the account holder. Name of the account holder. URI of the account resource. State or region of the account. Time zone used in the Plivo dashboard. See [IANA Time Zone Database](https://www.iana.org/time-zones). ### Example Object ```json theme={null} { "account_type": "standard", "address": "Wayne Enterprises Inc.", "api_id": "150892a0-922a-11e7-b6f4-061564b78b75", "auth_id": "MA2025RK4E639VJFZAGV", "auto_recharge": false, "billing_mode": "prepaid", "cash_credits": "1.80900", "city": "Gotham", "name": "Bruce Wayne", "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/", "state": "NY", "timezone": "America/New_York" } ``` *** ## Retrieve Account Details Retrieves the details of your account. ``` GET https://api.plivo.com/v1/Account/{auth_id}/ ``` ### Arguments No arguments required. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.account.get() print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.accounts.get() .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.account.details puts response ``` ```php PHP theme={null} ', ''); $response = $client->accounts->get(); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Account; Plivo.init("", ""); Account response = Account.getter().get(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Account.Get(); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Accounts.Get() fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ https://api.plivo.com/v1/Account/{auth_id}/ ``` ### Response Account type. Values: `standard` for paid accounts, `developer` for free trial. Postal address of the account, displayed on invoices. Unique identifier for the API request. Auth ID of the account. Whether automatic recharge is enabled when credits fall below threshold. Billing mode. Values: `prepaid` or `postpaid`. Account credits in USD. City of the account holder. Name of the account holder. URI of the account resource. State or region of the account. Time zone used in the Plivo dashboard. See [IANA Time Zone Database](https://www.iana.org/time-zones). ```json theme={null} { "account_type": "standard", "address": "Wayne Enterprises Inc.", "api_id": "150892a0-922a-11e7-b6f4-061564b78b75", "auth_id": "MA2025RK4E639VJFZAGV", "auto_recharge": false, "billing_mode": "prepaid", "cash_credits": "1.80900", "city": "Gotham", "name": "Bruce Wayne", "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/", "state": "NY", "timezone": "America/New_York" } ``` *** ## Update Account Details Updates the `Account` object. Parameters not provided remain unchanged. ``` POST https://api.plivo.com/v1/Account/{auth_id}/ ``` ### Arguments Postal address of the account, displayed on invoices. Name of the account holder. City of the account holder. State or region of the account. Time zone for the Plivo dashboard. See [IANA Time Zone Database](https://www.iana.org/time-zones). ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.account.update( name='Lucius Fox', city='New York', address='Times Square') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.accounts.update({ name: 'Lucius Fox', city: 'New York', address: 'Times Square' }).then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.account.update( city: 'New York', name: 'Lucius Fox', address: 'Times Square') puts response ``` ```php PHP theme={null} ', ''); $response = $client->accounts->update( 'Lucius Fox', 'New York', 'Times Square'); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Account; Plivo.init("", ""); AccountUpdateResponse response = Account.updater() .name("Lucius Fox") .city("New York") .address("Times Square") .update(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Account.Update( city: "New York", name: "Lucius Fox", address: "Times Square"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Accounts.Update(plivo.AccountUpdateParams{ Name: "Lucius Fox", City: "New York", Address: "Times Square", }) fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ -H "Content-Type: application/json" \ -d '{"name": "Lucius Fox", "city": "New York", "address": "Times Square"}' \ https://api.plivo.com/v1/Account/{auth_id}/ ``` ### Response Unique identifier for the API request. Status of the request. Returns `changed` on a successful update. ```json theme={null} { "api_id": "02bbdbaa-9303-11e7-8bc8-065f6a74a84a", "message": "changed" } ``` # Application API Source: https://plivo.com/docs/account/api/application 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 Unique identifier for the application. A friendly name for your Plivo application. URL requested when an incoming call is received. Must return valid Plivo XML. HTTP method for the answer\_url. Values: `GET` or `POST`. URL notified when the call hangs up. HTTP method for the hangup\_url. URL requested when answer\_url fails or returns invalid XML. HTTP method for the fallback\_answer\_url. URL notified when an inbound SMS is received. HTTP method for the message\_url. Whether this is the default app. Whether the application is enabled. Whether the app can be called from external SIP services. SIP URI of the application. 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](/docs/voice/concepts/sip-authentication/). 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](/docs/account/api/sip-authentication/). 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](/docs/account/api/sip-authentication/). Subaccount associated with the application. Null if main account. Whether incoming message content is logged. Default: `true`. URI of the application resource. ### Example Object ```json theme={null} { "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 Application name. Allowed: alphanumeric, hyphen (-), underscore (\_). URL fetched when a call executes this application. HTTP method for answer\_url. Default: `POST`. URL notified when call hangs up. Default: answer\_url. HTTP method for hangup\_url. Default: `POST`. Fallback URL if answer\_url fails. HTTP method for fallback\_answer\_url. Default: `POST`. URL notified for inbound messages. HTTP method for message\_url. Default: `POST`. Make this the default app for new numbers. Make this the default app for new endpoints. Subaccount ID to associate with this application. Log incoming message content. Default: `true`. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.applications.create( app_name='MyApp', answer_url='https://example.com/answer') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.applications.create('MyApp', { answerUrl: 'https://example.com/answer' }) .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.applications.create( 'MyApp', answer_url: 'https://example.com/answer') puts response ``` ```php PHP theme={null} ', ''); $response = $client->applications->create( 'MyApp', ['answer_url' => 'https://example.com/answer']); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.application.Application; Plivo.init("", ""); ApplicationCreateResponse response = Application.creator("MyApp", "https://example.com/answer") .create(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Application.Create( appName: "MyApp", answerUrl: "https://example.com/answer"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Applications.Create(plivo.ApplicationCreateParams{ AppName: "MyApp", AnswerURL: "https://example.com/answer", }) fmt.Println(response) } ``` ```bash cURL theme={null} 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 Status of the request. Returns `created` on a successful creation. Unique identifier for the application. Unique identifier for the API request. ```json theme={null} { "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 Python theme={null} import plivo client = plivo.RestClient('', '') response = client.applications.get(app_id='15784735442685051') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.applications.get('15784735442685051') .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.applications.get('15784735442685051') puts response ``` ```php PHP theme={null} ', ''); $response = $client->applications->get('15784735442685051'); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.application.Application; Plivo.init("", ""); Application response = Application.getter("15784735442685051").get(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Application.Get(appId: "15784735442685051"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Applications.Get("15784735442685051") fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ https://api.plivo.com/v1/Account/{auth_id}/Application/15784735442685051/ ``` ### Response HTTP method for the answer\_url. Values: `GET` or `POST`. URL requested when an incoming call is received. Must return valid Plivo XML. Unique identifier for the application. A friendly name for your Plivo application. Whether this is the default app. Whether the application is enabled. URL requested when answer\_url fails or returns invalid XML. HTTP method for the fallback\_answer\_url. HTTP method for the hangup\_url. URL notified when the call hangs up. HTTP method for the message\_url. URL notified when an inbound SMS is received. Whether the app can be called from external SIP services. URI of the application resource. SIP URI of the application. Subaccount associated with the application. Null if main account. Whether incoming message content is logged. Default: `true`. ```json theme={null} { "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 Filter by subaccount ID. Filter by app name prefix. Results per page. Maximum 20. Pagination offset. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.applications.list(offset=0, limit=5) print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.applications.list({ offset: 0, limit: 5 }) .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.applications.list(limit: 5, offset: 0) puts response ``` ```php PHP theme={null} ', ''); $response = $client->applications->list(['limit' => 5, 'offset' => 0]); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.application.Application; Plivo.init("", ""); ListResponse response = Application.lister() .offset(0) .limit(5) .list(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Application.List(limit: 5, offset: 0); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Applications.List(plivo.ApplicationListParams{ Offset: 0, Limit: 5, }) fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ https://api.plivo.com/v1/Account/{auth_id}/Application/ ``` ### Response Unique identifier for the API request. Pagination metadata: `limit` (results per page), `offset` (items skipped), `total_count` (total matching applications). Array of application objects — see [The Application Object](#the-application-object). ```json theme={null} { "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 URL fetched when a call executes this application. HTTP method for answer\_url. URL notified when call hangs up. HTTP method for hangup\_url. Fallback URL if answer\_url fails. HTTP method for fallback\_answer\_url. URL notified for inbound messages. HTTP method for message\_url. Make this the default app for new numbers. Make this the default app for new endpoints. Subaccount ID to associate. Log incoming message content. SIP authentication mode for inbound calls. Values: `ip_acl`, `credential`, `ip_acl_and_credential`, or `""` (empty to disable). See [SIP Authentication](/docs/voice/concepts/sip-authentication/). UUID of the IP Access Control List to assign. Required when `sip_auth_type` includes `ip_acl`. Create one via the [SIP Authentication API](/docs/account/api/sip-authentication/). UUID of the SIP credential to assign. Required when `sip_auth_type` includes `credential`. Create one via the [SIP Authentication API](/docs/account/api/sip-authentication/). 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 Python theme={null} import plivo client = plivo.RestClient('', '') response = client.applications.update( app_id='21686794894743506', answer_url='https://updated.answer.url') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.applications.update('15784735442685051', { answerUrl: 'https://updated.answer.url' }) .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.applications.update( '15784735442685051', answer_url: 'https://updated.answer.url') puts response ``` ```php PHP theme={null} ', ''); $response = $client->applications->update( '15784735442685051', ['answer_url' => 'https://updated.answer.url']); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.application.Application; Plivo.init("", ""); ApplicationUpdateResponse response = Application.updater("15784735442685051") .answerUrl("https://updated.answer.url") .update(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Application.Update( appId: "15784735442685051", answerUrl: "https://updated.answer.url"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Applications.Update("15784735442685051", plivo.ApplicationUpdateParams{ AnswerURL: "https://updated.answer.url", }) fmt.Println(response) } ``` ```bash cURL theme={null} 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 Status of the request. Returns `changed` on a successful update. Unique identifier for the API request. ```json theme={null} { "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 Delete associated endpoints. Default: `true`. App ID to reassign endpoints to when cascade is `false`. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.applications.delete(app_id='21686794894743506') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.applications.delete('15784735442685051') .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.applications.delete('15784735442685051') puts response ``` ```php PHP theme={null} ', ''); $response = $client->applications->delete('15784735442685051'); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.application.Application; Plivo.init("", ""); Application.deleter("15784735442685051").delete(); System.out.println("Deleted successfully."); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Application.Delete(appId: "15784735442685051"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) err := client.Applications.Delete("15784735442685051") if err == nil { fmt.Println("Deleted successfully.") } } ``` ```bash cURL theme={null} 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 ``` # API Overview Source: https://plivo.com/docs/account/api/overview Authentication, request format, responses, and pagination for Plivo APIs All Plivo APIs use HTTP verbs and standard HTTP status codes. To secure requests, all APIs are served over HTTPS. **API Endpoint** ``` https://api.plivo.com/v1/ ``` The current version of the APIs is `v1`. Server SDKs are versioned as `latest` and `legacy`. *** ## Authentication All requests to Plivo API are authenticated with `BasicAuth` using your `AUTH ID` and `AUTH TOKEN`. Find your credentials on the [Plivo console](https://cx.plivo.com/home). ```python Python theme={null} import plivo client = plivo.RestClient('', '') ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') ``` ```php PHP theme={null} ', ''); ``` ```java Java theme={null} import com.plivo.api.Plivo; Plivo.init("", ""); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); ``` ```go Go theme={null} package main import "github.com/plivo/plivo-go/v7" func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) } ``` ```bash cURL theme={null} curl -u ":" \ https://api.plivo.com/v1/Account/{auth_id}/ ``` *** ## Content Type Plivo only accepts input of type `application/json`. * **POST requests**: Arguments must be passed as JSON with `Content-Type: application/json` * **GET and DELETE requests**: Arguments must be passed in the query string *** ## Timeouts and Proxies Server SDKs support specifying timeouts and proxy settings for API requests. ```python Python theme={null} import plivo proxies = { 'http': 'https://username:password@proxyurl:proxyport', 'https': 'https://username:password@proxyurl:proxyport' } client = plivo.RestClient('', '', proxies=proxies, timeout=5) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); let options = { 'timeout': 5000, 'host': 'https://proxyurl', 'port': 'proxyport', auth: { username: 'my-user', password: 'my-password' } }; const client = new plivo.Client('', '', options); ``` ```ruby Ruby theme={null} require 'plivo' proxy = { proxy_host: "https://proxyurl", proxy_port: "proxyport", proxy_user: "username", proxy_pass: "password" } client = Plivo::RestClient.new('', '', proxy, timeout=5) ``` ```php PHP theme={null} ', '', 'https://proxyurl', 'proxyport', 'username', 'password'); $client->client->setTimeout(5); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi( "", "", "https://proxyurl", "proxyport", "username", "password"); api.Client.SetTimeout(10); ``` ```go Go theme={null} package main import "github.com/plivo/plivo-go/v7" func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{ Timeout: 5 * time.Second, }) } ``` *** ## Pagination Plivo uses offset-based pagination to list resources. | Parameter | Description | | --------- | ------------------------------------------------------ | | `limit` | Number of results to return. Range: 1-20. Default: 20. | | `offset` | Number of results to skip for pagination. | For example, with 100 results, `limit=10` and `offset=50` returns objects 51-60. *** ## Asynchronous Requests All Plivo API requests can be made asynchronous. When an async call is made, Plivo returns a generic response with the `api_id`, and the actual response is sent to your callback URL. | Parameter | Description | | ----------------- | ---------------------------------------------- | | `callback_url` | URL to receive the API response. | | `callback_method` | HTTP method for the callback. Default: `POST`. | ```json Async Response theme={null} { "message": "async api spawned", "api_id": "63f0761a-e0ed-11e1-8ea7-12313924e3a6" } ``` *** ## HTTP Status Codes | Code | Description | | ----- | -------------------------------- | | `200` | Request executed successfully | | `201` | Resource created | | `202` | Resource changed | | `204` | Resource deleted | | `400` | Parameter missing or invalid | | `401` | Authentication failed | | `403` | Forbidden | | `404` | Resource not found | | `405` | HTTP method not allowed | | `429` | Too many requests (rate limited) | | `500` | Server error | ### Troubleshooting Common Errors | Code | Common Causes | Solution | | ----- | ----------------------------------------------- | ----------------------------------------------------------------------------- | | `400` | Missing required parameter, invalid JSON format | Check all required parameters. Verify JSON syntax | | `401` | Invalid Auth ID or Auth Token | Verify credentials at Console → API Keys | | `403` | Account not verified, feature not enabled | Complete account verification. Contact support | | `404` | Invalid resource ID, typo in endpoint URL | Verify the resource exists. Check endpoint spelling | | `429` | Rate limit exceeded (300 requests/5 sec) | Implement exponential backoff | | `500` | Temporary server issue | Retry after a few seconds. Check [status.plivo.com](https://status.plivo.com) | *** ## Response Format All API responses are in JSON format. Every response includes an `api_id` to uniquely identify your request. | Field | Description | | --------- | ------------------------------------- | | `api_id` | Unique identifier for the request. | | `message` | Information about the request result. | | `error` | Error details if the request failed. | ```json Success theme={null} { "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb", "message": "call fired", "request_uuid": "75b26856-8638-11e0-802c-6d99d509954e" } ``` ```json Error theme={null} { "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb", "error": "answer_url parameter is missing" } ``` # SIP Authentication API Source: https://plivo.com/docs/account/api/sip-authentication Manage SIP credentials and IP Access Control Lists for securing inbound calls to your Plivo applications The SIP Authentication API lets you create and manage two resources used to secure inbound calls to your Plivo applications: * **SIP Credentials** — username and password pairs used for SIP digest authentication * **IP Access Control Lists (IP ACLs)** — lists of trusted IP addresses or CIDR ranges allowed to call your application Once created, assign these resources to an application via the [Application API](/docs/account/api/application/) by setting `sip_auth_type`, `ip_acl_uuid`, and `credential_uuid`. For an overview of how SIP authentication works, see [SIP Authentication concepts](/docs/voice/concepts/sip-authentication/). ### Account Quotas | Resource | Limit | | ----------------------- | ----- | | IP ACLs per account | 100 | | Credentials per account | 200 | | Entries per IP ACL | 50 | ### Error Responses All endpoints return standard HTTP status codes with a JSON error body: | Status | Meaning | | ------ | ---------------------------------------------------------------- | | `400` | Validation error (missing field, invalid format, exceeds limits) | | `404` | Resource not found | | `409` | Conflict (duplicate username, resource in use) | | `429` | Rate limited | Unique identifier for the API request. Human-readable description of the error. ```json theme={null} { "api_id": "...", "error": "This credential is currently assigned to an application. Remove the assignment first by setting sip_auth_type to empty." } ``` If your integration is receiving unexpected 403 responses on inbound calls, see the [Rate-limit lockout](/docs/voice/concepts/sip-authentication/#rate-limiting-and-lockout) section on the SIP Authentication concept page. **API Endpoint** ``` https://api.plivo.com/v1/Account/{auth_id}/SipAuth/ ``` *** ## The Credential Object A SIP credential is a username/password pair used for SIP digest authentication. ### Attributes Unique identifier for the credential. The SIP username. Authentication realm. Default: `app.plivo.com`. URI of the credential resource. Passwords are stored as one-way hashes (HA1) and are never returned in API responses. ### Example Object ```json theme={null} { "credential_uuid": "cred-abc123-def456", "username": "sipuser1", "realm": "app.plivo.com", "resource_uri": "/v1/Account/{auth_id}/SipAuth/Credential/cred-abc123-def456/" } ``` *** ## Create a Credential Create a new SIP credential. ``` POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/ ``` ### Arguments 3-64 characters. Allowed: alphanumeric, period (`.`), underscore (`_`), hyphen (`-`). Must be unique within your account. 8-128 characters. Must include at least one uppercase letter, one lowercase letter, and one digit. ### Example ```bash cURL theme={null} curl -X POST "https://api.plivo.com/v1/Account//SipAuth/Credential/" \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "username": "sipuser1", "password": "" }' ``` ### Response (201 Created) Unique identifier for the API request. Unique identifier for the credential. The SIP username. Authentication realm. Default: `app.plivo.com`. URI of the credential resource. ```json theme={null} { "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949", "credential_uuid": "cred-abc123-def456", "username": "sipuser1", "realm": "app.plivo.com", "resource_uri": "/v1/Account/{auth_id}/SipAuth/Credential/cred-abc123-def456/" } ``` *** ## Retrieve a Credential Get details of a specific credential. ``` GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/ ``` ### Example ```bash cURL theme={null} curl "https://api.plivo.com/v1/Account//SipAuth/Credential/cred-abc123-def456/" \ -u ":" ``` *** ## List All Credentials Returns all SIP credentials for your account. ``` GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/ ``` ### Example ```bash cURL theme={null} curl "https://api.plivo.com/v1/Account//SipAuth/Credential/" \ -u ":" ``` *** ## Update a Credential Update the password on an existing credential. The username cannot be changed. ``` POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/ ``` ### Arguments New password. Minimum 8 characters. Must include uppercase, lowercase, and digit. ### Example ```bash cURL theme={null} curl -X POST "https://api.plivo.com/v1/Account//SipAuth/Credential/cred-abc123-def456/" \ -u ":" \ -H "Content-Type: application/json" \ -d '{"password": ""}' ``` *** ## Delete a Credential Permanently delete a credential. ``` DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/ ``` You cannot delete a credential currently assigned to an application. First remove the assignment by setting the application's `sip_auth_type` to empty (`""`). ### Example ```bash cURL theme={null} curl -X DELETE "https://api.plivo.com/v1/Account//SipAuth/Credential/cred-abc123-def456/" \ -u ":" ``` ### Response `HTTP Status Code: 204` *** ## The IP Access Control List Object An IP ACL is a list of trusted IP addresses or CIDR ranges allowed to make inbound calls to your application. ### Attributes Unique identifier for the IP ACL. Friendly name for the IP ACL. List of IP entries. Each entry includes `entry_id`, `ip`, `cidr_prefix`, and `description`. URI of the IP ACL resource. ### Example Object ```json theme={null} { "ip_acl_uuid": "acl-abc123", "name": "Office Network", "entries": [ { "entry_id": "entry-001", "ip": "203.0.113.10", "cidr_prefix": 32, "description": "Primary PBX" } ], "resource_uri": "/v1/Account/{auth_id}/SipAuth/IpAccessControlList/acl-abc123/" } ``` *** ## Create an IP ACL Create a new IP Access Control List. ``` POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/ ``` ### Arguments Friendly name. 1-120 characters. Optional list of IP entries to add at creation time. Maximum 50 entries per ACL. ### Example ```bash cURL theme={null} curl -X POST "https://api.plivo.com/v1/Account//SipAuth/IpAccessControlList/" \ -u ":" \ -H "Content-Type: application/json" \ -d '{"name": "Office Network"}' ``` ### Response (201 Created) Unique identifier for the API request. Unique identifier for the IP ACL. ```json theme={null} { "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949", "ip_acl_uuid": "acl-abc123" } ``` *** ## Retrieve an IP ACL Get details of a specific IP ACL, including all entries. ``` GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/ ``` *** ## List All IP ACLs Returns all IP ACLs for your account. ``` GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/ ``` *** ## Update an IP ACL Update the name of an existing IP ACL. ``` POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/ ``` ### Arguments New name for the IP ACL. *** ## Delete an IP ACL Permanently delete an IP ACL and all its entries. ``` DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/ ``` You cannot delete an IP ACL currently assigned to an application. First remove the assignment by setting the application's `sip_auth_type` to empty (`""`). ### Response `HTTP Status Code: 204` *** ## Add an Entry to an IP ACL Add a new IP address or CIDR range to an existing IP ACL. Maximum 50 entries per ACL. ``` POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/Entry/ ``` ### Arguments Valid IPv4 address. CIDR prefix. Range: 0-32. Default: `32` (single host for IPv4). `0` allows all IPs. Description of this entry. Up to 255 characters. ### Example ```bash cURL theme={null} curl -X POST "https://api.plivo.com/v1/Account//SipAuth/IpAccessControlList/acl-abc123/Entry/" \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "ip": "203.0.113.10", "cidr_prefix": 32, "description": "Primary PBX" }' ``` ### Response (201 Created) Unique identifier for the API request. Unique identifier for the IP ACL entry. ```json theme={null} { "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949", "entry_id": "entry-001" } ``` *** ## Remove an Entry from an IP ACL Permanently delete an entry from an IP ACL. ``` DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/Entry/{entry_id}/ ``` ### Response `HTTP Status Code: 204` *** ## Related * [SIP Authentication concepts](/docs/voice/concepts/sip-authentication/) — How SIP auth works, options, flow diagrams, and security best practices * [Application API](/docs/account/api/application/) — Assign credentials and IP ACLs to applications * [Voice API: Make a Call](/docs/voice/api/calls#make-a-call/) — Outbound SIP authentication via `sip_auth_username` and `sip_auth_password` * [Dial XML](/docs/voice/xml/routing#dial/) — Outbound SIP authentication via `sipAuthUsername` and `sipAuthPassword` # Subaccount API Source: https://plivo.com/docs/account/api/subaccount Create and manage subaccounts to segment usage and isolate traffic Subaccounts let you manage multiple customer accounts under your main account. Each subaccount has its own Auth ID and Token, while charges deduct from the main account. **API Endpoint** ``` https://api.plivo.com/v1/Account/{auth_id}/Subaccount/ ``` *** ## The Subaccount Object ### Attributes Auth ID of the subaccount. Auth Token of the subaccount. Name of the subaccount. Whether the subaccount is enabled. URI to the parent account. Date the subaccount was created. Date the subaccount was last modified. URI to the subaccount resource. ### Example Object ```json theme={null} { "account": "/v1/Account/MA2025RK4E639VJFZAGV/", "api_id": "968f0a22-9237-11e7-a51d-0245fa790d9e", "auth_id": "SA2025RK4E639VJFZAMM", "auth_token": "NWM3YjliMjk0ZGYxMGM2YjJiYWE0MjEwZDM5YWU5", "created": "2022-09-05", "enabled": true, "modified": null, "name": "Subaccount Test", "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Subaccount/SA2025RK4E639VJFZAMM/" } ``` *** ## Create a Subaccount Creates a new subaccount. ``` POST https://api.plivo.com/v1/Account/{auth_id}/Subaccount/ ``` ### Arguments A human-readable name for the subaccount. Whether the subaccount should be enabled. Default: `false`. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.subaccounts.create( name='Wayne Enterprises Subaccount', enabled=True) print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.subAccounts.create('Test Subaccount', true) .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.subaccounts.create('Test Subaccount', true) puts response ``` ```php PHP theme={null} ', ''); $response = $client->subaccounts->create('Test Subaccount', true); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Subaccount; Plivo.init("", ""); SubaccountCreateResponse response = Subaccount.creator("Test Subaccount") .enabled(true) .create(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Subaccount.Create( enabled: true, name: "Test Subaccount"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Subaccounts.Create(plivo.SubaccountCreateParams{ Name: "Test Subaccount", Enabled: true, }) fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ -H "Content-Type: application/json" \ -d '{"name": "Test Subaccount", "enabled": true}' \ https://api.plivo.com/v1/Account/{auth_id}/Subaccount/ ``` ### Response Unique identifier for the API request. Auth ID of the subaccount. Auth Token of the subaccount. Status of the request. Returns `created` on a successful creation. ```json theme={null} { "api_id": "324a7dd8-0db2-11e4-8a4a-123140008edf", "auth_id": "SA2025RK4E639VJFZAMM", "auth_token": "MTZjYWM0YzVjNjMwZmVmODFiNWJjNPJmOGJjZjgw", "message": "created" } ``` *** ## Retrieve a Subaccount Get details of a specific subaccount. ``` GET https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/ ``` ### Arguments No arguments required. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.subaccounts.get(auth_id='SA2025RK4E639VJFZAMM') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.subaccounts.get('SA2025RK4E639VJFZAMM') .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.subaccounts.get('SA2025RK4E639VJFZAMM') puts response ``` ```php PHP theme={null} ', ''); $response = $client->subaccounts->get('SA2025RK4E639VJFZAMM'); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Subaccount; Plivo.init("", ""); Subaccount response = Subaccount.getter("SA2025RK4E639VJFZAMM").get(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Subaccount.Get(id: "SA2025RK4E639VJFZAMM"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Subaccounts.Get("SA2025RK4E639VJFZAMM") fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/ ``` ### Response URI to the parent account. Unique identifier for the API request. Auth ID of the subaccount. Auth Token of the subaccount. Date the subaccount was created. Whether the subaccount is enabled. Date the subaccount was last modified. Name of the subaccount. URI to the subaccount resource. ```json theme={null} { "account": "/v1/Account/MA2025RK4E639VJFZAGV/", "api_id": "323972b2-0db3-11e4-a2d1-22000ac5040c", "auth_id": "SA2025RK4E639VJFZAMM", "auth_token": "MTZjYWM0YzVjNjMwZmVmODFiNWJjNWJmOGJjZjgw", "created": "2022-07-17", "enabled": false, "modified": null, "name": "Han Solo", "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Subaccount/SA2025RK4E639VJFZAMM/" } ``` *** ## List All Subaccounts Returns all subaccounts sorted by creation date, newest first. ``` GET https://api.plivo.com/v1/Account/{auth_id}/Subaccount/ ``` ### Arguments Results per page. Maximum 20. Pagination offset. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.subaccounts.list(offset=0, limit=5) print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.subaccounts.list({ offset: 0, limit: 5 }) .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.subaccounts.list(limit: 5, offset: 0) puts response ``` ```php PHP theme={null} ', ''); $response = $client->subaccounts->list(3, 2); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Subaccount; Plivo.init("", ""); ListResponse response = Subaccount.lister() .offset(0) .limit(5) .list(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Subaccount.List(limit: 5, offset: 0); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Subaccounts.List(plivo.SubaccountListParams{ Offset: 0, Limit: 5, }) fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ https://api.plivo.com/v1/Account/{auth_id}/Subaccount/ ``` ### Response Unique identifier for the API request. Pagination metadata: `limit` (results per page), `offset` (items skipped), `total_count` (total matching subaccounts). Array of subaccount objects — see [The Subaccount Object](#the-subaccount-object). ```json theme={null} { "api_id": "b38bf42e-0db4-11e4-8a4a-123140008edf", "meta": { "limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2 }, "objects": [ { "account": "/v1/Account/MA2025RK4E639VJFZAGV/", "auth_id": "SA2025RK4E639VJFZAMM", "auth_token": "MTZjYWM0YzVjNjMwZmVmODFiNWJjNWJmOGJjZjgw", "created": "2022-07-17", "enabled": false, "modified": null, "name": "Chewbacca", "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Subaccount/SA2025RK4E639VJFZAMM/" } ] } ``` *** ## Update a Subaccount Updates a subaccount. Parameters not provided remain unchanged. ``` POST https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/ ``` ### Arguments Name of the subaccount. Whether the subaccount should be enabled. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.subaccounts.update( auth_id='SA2025RK4E639VJFZAMM', name='Updated Subaccount Name') print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.subaccounts.update('SA2025RK4E639VJFZAMM', 'Updated Subaccount Name') .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.subaccounts.update( 'SA2025RK4E639VJFZAMM', 'Updated Subaccount Name', false) puts response ``` ```php PHP theme={null} ', ''); $response = $client->subaccounts->update( 'SA2025RK4E639VJFZAMM', 'Updated Subaccount Name'); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Subaccount; Plivo.init("", ""); SubaccountUpdateResponse response = Subaccount.updater("SA2025RK4E639VJFZAMM", "Updated Subaccount Name") .update(); System.out.println(response); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Subaccount.Update( id: "SA2025RK4E639VJFZAMM", name: "Updated Subaccount Name"); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) response, _ := client.Subaccounts.Update("SA2025RK4E639VJFZAMM", plivo.SubaccountUpdateParams{ Name: "Updated Subaccount Name", }) fmt.Println(response) } ``` ```bash cURL theme={null} curl -i --user AUTH_ID:AUTH_TOKEN \ -H "Content-Type: application/json" \ -d '{"name": "Updated Subaccount Name"}' \ https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/ ``` ### Response Status of the request. Returns `changed` on a successful update. Unique identifier for the API request. ```json theme={null} { "message": "changed", "api_id": "5a9fcb68-523d-11e1-86da-6ff39efcb949" } ``` *** ## Delete a Subaccount Permanently deletes a subaccount. ``` DELETE https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/ ``` ### Arguments If `true`, deletes associated Applications, Endpoints, and Numbers. If `false`, maps them to the main account. Default: `false`. ### Example ```python Python theme={null} import plivo client = plivo.RestClient('', '') response = client.subaccounts.delete( auth_id='SA2025RK4E639VJFZAMM', cascade=True) print(response) ``` ```javascript Node.js theme={null} const plivo = require('plivo'); const client = new plivo.Client('', ''); client.subaccounts.delete('SA2025RK4E639VJFZAMM', true) .then(response => console.log(response)); ``` ```ruby Ruby theme={null} require 'plivo' client = Plivo::RestClient.new('', '') response = client.subaccounts.delete('SA2025RK4E639VJFZAMM', true) puts response ``` ```php PHP theme={null} ', ''); $response = $client->subaccounts->delete('SA2025RK4E639VJFZAMM', true); print_r($response); ``` ```java Java theme={null} import com.plivo.api.Plivo; import com.plivo.api.models.account.Subaccount; Plivo.init("", ""); Subaccount.deleter("SA2025RK4E639VJFZAMM").cascade(true).delete(); System.out.println("Deleted successfully."); ``` ```csharp .NET theme={null} using Plivo; var api = new PlivoApi("", ""); var response = api.Subaccount.Delete( id: "SA2025RK4E639VJFZAMM", cascade: true); Console.WriteLine(response); ``` ```go Go theme={null} package main import ( "fmt" "github.com/plivo/plivo-go/v7" ) func main() { client, _ := plivo.NewClient("", "", &plivo.ClientOptions{}) err := client.Subaccounts.Delete("SA2025RK4E639VJFZAMM", plivo.SubaccountDeleteParams{Cascade: true}) if err == nil { fmt.Println("Deleted successfully.") } } ``` ```bash cURL theme={null} curl -X DELETE --user AUTH_ID:AUTH_TOKEN \ https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/ ``` ### Response ``` HTTP Status Code: 204 ``` # Usage Summary API Source: https://plivo.com/docs/account/api/usage-summary Retrieve a windowed, bucketed usage and spend summary for your Plivo account across messaging, voice, SIP Trunking, and transcription. The `UsageSummary` object returns aggregated usage and spend for your account over a date window, bucketed by the granularity you choose and optionally filtered by subaccount, product, country, direction, error code, or hangup cause. Telecom traffic (messaging, voice, SIP Trunking, transcription) is returned in `usage`, and non-telecom billing rows (number charges, lookups, fees, taxes, adjustments) are returned in `other_charges`. Detail rows are paginated with an opaque cursor. **API Endpoint** ``` https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/ ``` Authentication uses HTTP Basic Auth with your `AUTH ID` and `AUTH TOKEN`, the same as all Plivo Messaging APIs. The `auth_id` is taken from the URL path; any `auth_id` passed as a query parameter is silently ignored. At general availability this endpoint is available over the REST API only. Server SDK wrappers will be added in a future release. *** ## Retrieve Usage Summary Retrieves a paginated usage summary for the requested window. ``` GET https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/ ``` ### Arguments Only the parameters below are forwarded upstream. Any unknown query keys are silently dropped. Scope the summary to a single subaccount. Must be non-empty if provided. Omit to summarize the parent account and all subaccounts. Bucket size for `usage` rows. One of `hour`, `day`, `month`, or `year`. Start of the reporting window in `YYYY-MM-DD` format. Inclusive. End of the reporting window in `YYYY-MM-DD` format. **Exclusive** — rows with timestamps at or after `to_date` are not returned. Restrict `usage` rows to one or more products. Repeatable, or pass as a comma-separated list. Valid values: `message`, `voice`, `zentrunk`, `transcription`, `other`. Filter messaging rows by rolled-up DLR error code. Ignored for non-messaging products. See [Error Codes](/docs/messaging/troubleshooting/error-codes) for the full list. Filter voice and SIP Trunking rows by hangup cause. Ignored for other products. See [Hangup Causes](/docs/voice/troubleshooting/hangup-causes) for the full list. Filter rows by direction. One of `inbound` or `outbound`. Filter rows by ISO-3166-1 alpha-2 country code (for example, `US`, `GB`, `IN`). Number of `usage` rows per page. Range: `1`–`1000`. Opaque cursor returned as `next_page_token` on the previous response. Pass it back to fetch the next page. Unlike most Plivo list endpoints, `UsageSummary` uses cursor-based pagination (`page_token` / `next_page_token`) rather than the `limit` / `offset` model described in the [API Overview](/docs/account/api/overview). See [Pagination](#pagination) below. ### Window limits per granularity The reporting window (`to_date` − `from_date`) is capped based on the `granularity` you request: | Granularity | Maximum window | | ----------- | ------------------------------------- | | `hour` | 7 days | | `day` | 92 days | | `month` | 24 months | | `year` | Unlimited (bounded by data retention) | Exceeding the cap returns a `400` response that suggests the next-coarser granularity. ### Example ```bash cURL theme={null} curl -G https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/ \ -u ':' \ --data-urlencode "granularity=month" \ --data-urlencode "from_date=2026-05-01" \ --data-urlencode "to_date=2026-06-10" \ --data-urlencode "page_size=100" ``` ### Response Unique identifier for the request. Summary metadata, window totals, and pagination cursor. See [meta](#meta) below. Paginated telecom-traffic rows for `message`, `voice`, `zentrunk`, and `transcription`. See [usage item](#usage-item) below. Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See [other charges item](#other-charges-item) below. ```json theme={null} { "api_id": "c85662b6-0f35-4ea9-b8c3-22fa1e35a4c5", "meta": { "auth_id": "MAsampleaccountxxxx", "granularity": "month", "from_date": "2026-05-01T00:00:00Z", "to_date": "2026-06-10T00:00:00Z", "currency": "USD", "page_size": 100, "total_spend": 640.6663, "subaccount_spend": { "SAsamplesubacct0001": 0.192, "SAsamplesubacct0002": 19.7532 } }, "usage": [ { "from_date": "2026-05-01T00:00:00Z", "to_date": "2026-06-01T00:00:00Z", "product": "message", "type": "sms", "country": "US", "direction": "outbound", "total_units": 1058, "total_amount": 5.6074, "surcharge": 3.703 }, { "from_date": "2026-05-01T00:00:00Z", "to_date": "2026-06-01T00:00:00Z", "product": "message", "type": "sms", "country": "PR", "direction": "outbound", "total_units": 5, "total_amount": 0.17145, "error_code": "200", "error_reason": "Opt-out block" }, { "from_date": "2026-05-01T00:00:00Z", "to_date": "2026-06-01T00:00:00Z", "product": "message", "type": "sms", "subaccount_auth": "SAsamplesubacct0001", "country": "US", "direction": "outbound", "total_units": 1055, "total_amount": 6.6465, "surcharge": 4.7475 }, { "from_date": "2026-05-01T00:00:00Z", "to_date": "2026-06-01T00:00:00Z", "product": "voice", "type": "pstn", "country": "US", "direction": "outbound", "total_units": 52503, "duration_seconds": 52241, "total_amount": 0 } ], "other_charges": [ { "from_date": "2026-05-01T00:00:00Z", "to_date": "2026-06-01T00:00:00Z", "description": "Number Charges", "total_units": 129, "total_amount": 102.1245 }, { "from_date": "2026-06-01T00:00:00Z", "to_date": "2026-07-01T00:00:00Z", "description": "CNAM Lookup", "total_units": 48, "total_amount": 0.192 } ] } ``` *** ## The Usage Summary Object A successful response has three top-level fields: `api_id`, `meta`, and the two row arrays `usage` and `other_charges`. Unique identifier for the request. Summary metadata, window totals, and pagination cursor. See [meta](#meta) below. Paginated telecom-traffic rows for `message`, `voice`, `zentrunk`, and `transcription`. See [usage item](#usage-item) below. All `usage` filters (`product`, `country`, `direction`, `error_code`, `hangup_cause`, `subaccount_auth`) apply to this array. Non-telecom billing rows — number charges, lookups, fees, taxes, adjustments. See [other charges item](#other-charges-item) below. **`other_charges` is page-1-only.** It is also omitted entirely when `subaccount_auth` is set or when the `product` filter excludes `other`. The reporting window applies to both arrays, but all other filters apply only to `usage`. ### meta Account auth ID the summary belongs to. Present only when the request was scoped to a subaccount via `subaccount_auth`. Granularity used for bucketing `usage` rows. Reporting window start (ISO-8601 timestamp). Reporting window end (ISO-8601 timestamp). Exclusive. Currency of all monetary amounts in the response. Number of `usage` rows per page. Opaque cursor for the next page. Omitted on the last page. Grand total (`usage` + `other_charges`) over the entire reporting window. **Returned on page 1 only.** Window usage total for the scoped subaccount. Present only when the request was filtered by `subaccount_auth`. **Returned on page 1 only.** Per-subaccount usage spend breakdown, keyed by subaccount auth ID. **Returned on page 1 only, and only when the request was not filtered by `subaccount_auth`.** Parent-level rows and `other_charges` are excluded from this map. ### usage item Bucket start (ISO-8601 timestamp). Inclusive. Bucket end (ISO-8601 timestamp). Exclusive. One of `message`, `voice`, `zentrunk`, or `transcription`. Product sub-type. For example, `sms` or `mms` for `message`, or `pstn` for `voice`. Present for subaccount-scoped rows; omitted for parent-level rows. ISO-3166-1 alpha-2 country code. Omitted for products that don't carry a country dimension. `inbound` or `outbound`. Omitted for products that don't carry a direction dimension. Units for this bucket. The unit depends on the product — see [Per-product unit meaning](#per-product-unit-meaning) below. Billed duration in seconds, for `voice`, `zentrunk`, and `transcription` rows. Omitted for other products. Total charge for the bucket. Surcharge component of `total_amount`, when applicable. Rolled-up DLR error code on messaging rows. Empty on successful delivery. See [Error Codes](/docs/messaging/troubleshooting/error-codes). Rolled-up hangup cause on voice and SIP Trunking rows. See [Hangup Causes](/docs/voice/troubleshooting/hangup-causes). Human-readable label for whichever of `error_code` or `hangup_cause` is set on the row. #### Per-product unit meaning | Product | `total_units` means | `duration_seconds` means | | --------------- | ------------------- | ------------------------ | | `message` | Message segments | Not returned | | `voice` | Call count | Billed call duration | | `zentrunk` | Call count | Billed call duration | | `transcription` | Transcription count | Recording duration | ### other charges item Charge window start (ISO-8601 timestamp). Charge window end (ISO-8601 timestamp). Customer-facing label for the charge. Examples: `Number Charges`, `CNAM Lookup`, `Other Charges`. Number of units billed. Total amount charged. Always positive. *** ## Pagination `usage` rows are paginated with an opaque cursor. When `meta.next_page_token` is present, pass it back as the `page_token` query parameter — keeping all other filters unchanged — to fetch the next page. The last page omits `next_page_token`. `total_spend`, `total_subaccount_spend`, `subaccount_spend`, and the entire `other_charges` array are returned **only on page 1** of a traversal. If you paginate, accumulate them from the first response — they will not appear on subsequent pages. ### Example: fetching page 2 ```bash cURL theme={null} curl -G https://api.plivo.com/v1/Account/{auth_id}/UsageSummary/ \ -u ':' \ --data-urlencode "granularity=month" \ --data-urlencode "from_date=2026-05-01" \ --data-urlencode "to_date=2026-06-10" \ --data-urlencode "page_size=100" \ --data-urlencode "page_token=" ``` *** ## Rate limits This endpoint allows up to 20 requests per 60 seconds per account. Exceeding this limit returns a `429` response; retry after a short backoff. *** ## Response codes | Code | Meaning | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `200` | Success. Returns a usage summary body. | | `400` | Bad request. The upstream error message is surfaced verbatim so the caller can self-correct (for example, exceeding the window cap for the requested granularity). | | `401` | Unauthorized. Invalid `AUTH ID` or `AUTH TOKEN`. | | `403` | Forbidden. The request originated from a non-whitelisted IP. See [IP Whitelisting](/docs/account/concepts/ip-whitelisting). | | `429` | Rate limit exceeded. See [Rate limits](#rate-limits). | | `502` | Upstream service failure. | ### Example: window cap exceeded ```json theme={null} { "api_id": "c85662b6-0f35-4ea9-b8c3-22fa1e35a4c5", "error": "granularity=day supports a max window of 92 days (requested 120 days); use granularity=month for larger windows" } ``` *** ## Notes * `auth_id` is always taken from the URL path. A client cannot read another account's usage by passing a different `auth_id` in the query string. * Upstream 4xx errors propagate their status code and message verbatim. Upstream 5xx or network failures are normalized to `502` with a generic message. # API Access Control (IP Whitelisting) Source: https://plivo.com/docs/account/concepts/ip-whitelisting Restrict Plivo API access to specific IP addresses from your account settings * **What:** Restrict which IP addresses can make API requests to your Plivo account. Requests from non-whitelisted IPs are rejected with HTTP 403 * **Direction:** Inbound (your servers → Plivo API) * **How:** Add CIDR entries in **Account Settings > IP Whitelisting** in the Console. Max 50 entries per account * **Note:** This controls API access only. For firewall rules to allow Plivo traffic to reach your servers, see [Voice Firewall & Network Configuration](/docs/voice/concepts/firewall-network-configuration/) or [Messaging Firewall & Network Configuration](/docs/messaging/concepts/firewall-network-configuration/) IP Whitelisting adds an extra layer of API access control by allowing requests only from specified IP addresses or CIDR ranges. When enabled, any API request from a non-whitelisted IP is rejected with an HTTP 403 Forbidden response. *** ## Key Points * Plivo matches the requesting IP address against your whitelist using CIDR matching. * Requests from non-whitelisted IPs receive an HTTP `403 Forbidden` response. * Only "Allow" rules are supported — there are no "deny" or custom logic rules. * Maximum of 50 CIDR entries per account. * Subaccounts inherit the parent account's whitelist rules. Subaccount CIDRs cannot be independently managed. * Validation checks run when you add new entries and when you edit existing ones to prevent overlaps, supersets, and duplicates. * IP Whitelisting takes effect as soon as you add your first CIDR entry. *** ## Set Up IP Whitelisting ### Step 1: Navigate to IP Whitelisting 1. Log in to the [Plivo console](https://cx.plivo.com/home). 2. Go to **Account Settings > IP Whitelisting** from the left navigation pane. ### Step 2: Add IPs 1. Click **+ Add CIDR Address**. 2. In the modal popup, enter one or more IP addresses in CIDR format (comma-separated). * Example: `192.0.2.0/24, 1.1.1.1/32` 3. Click **Add** to save the entries. ### Step 3: Confirm Entries After adding CIDRs, the system blocks any API request not coming from whitelisted IPs. The list shows all currently active CIDRs with subnet masks. You can edit or delete any entry at any time. Before enabling, make sure you have added the IP addresses of all servers, CI/CD pipelines, and developer machines that make Plivo API calls. Forgetting an IP locks out those systems immediately. *** ## Validation Rules Follow these rules to avoid configuration errors. | Error Case | How to Avoid | | --------------------------------- | --------------------------------------------------------------------------- | | Invalid Format | Enter IPs in proper CIDR format (e.g., `192.168.1.0/24` or `2001:db8::/64`) | | Duplicate Entry | Do not re-enter an IP or CIDR already present in the list | | Subset Already Exists | Avoid adding an IP that is already covered by a broader CIDR | | Superset Conflict | Remove more specific entries before adding a broader range | | Private or Special Ranges Blocked | Avoid using localhost (e.g., `127.0.0.1/32`) or reserved/documentation IPs | | Limit Reached (50 CIDRs) | Remove an existing IP if you have already reached the limit of 50 entries | *** ## FAQ *** ### What happens if my IP is not whitelisted? Your API requests are rejected with an HTTP `403 Forbidden` response: ```json theme={null} { "api_id": "", "error": "Access denied. The request originated from IP , which is not in the IP whitelist for this account. Update your IP whitelist in the console. Refer to https://www.plivo.com/docs/account/concepts/ip-whitelisting for more details." } ``` *** ### How many CIDRs can I add? You can add up to 50 CIDR entries per account. *** ### Can I add a single IP without a CIDR mask? No. You must use CIDR format. For single IPs, use `/32` for IPv4 or `/128` for IPv6 (e.g., `203.0.113.5/32`). *** ### Can I whitelist IP ranges? Yes, use CIDR notation (e.g., `203.0.113.0/24`) to specify a range. *** ### Can subaccounts have different IP rules? No. Subaccounts follow the CIDR rules of their parent account. *** ### How can I troubleshoot blocked access? Check that: * Your current IP matches one of the whitelisted CIDRs. * There are no formatting or range-related issues with your entries. *** ## Related Resources * [Voice: Firewall & Network Configuration](/docs/voice/concepts/firewall-network-configuration/) — Plivo IP ranges and ports to whitelist on your firewall for SIP, RTP, and voice callbacks * [Messaging: Firewall & Network Configuration](/docs/messaging/concepts/firewall-network-configuration/) — Plivo IP ranges to whitelist on your firewall for messaging callbacks * [Account Management FAQ](/docs/faq/account/account-management/) — General account security best practices # Subaccounts Source: https://plivo.com/docs/account/concepts/subaccounts Segment usage, isolate traffic, and manage multi-tenant architectures * **What:** Subaccounts are isolated environments under your main Plivo account — each with its own Auth ID/Auth Token, separate call/message logs, and independent webhooks — for multi-tenant SaaS, resellers, and dev/staging/production separation * **Billing:** All charges deduct from the parent account's balance; subaccounts have no separate payment methods * **Access:** Subaccount credentials (Auth ID prefix `SA`) reach only their own resources; the main account (`MA`) can access all resources and all subaccounts * **Numbers:** Each phone number belongs to one account only; numbers transfer to the main account when a subaccount is deleted (unless `cascade=true`) Subaccounts let you create isolated environments under your main Plivo account. *** ## How Subaccounts Work Each subaccount has: * Unique Auth ID and Auth Token * Separate call/message logs * Independent webhooks All charges deduct from the parent account balance. *** ## Use Cases | Use Case | Description | | -------------------------- | ----------------------------------------------- | | **Multi-tenant SaaS** | Isolate each customer's traffic and logs | | **Reseller/White-label** | Manage client accounts, track usage for billing | | **Environment separation** | Separate dev, staging, production | | **Department tracking** | Track usage by business unit | *** ## Billing Subaccounts share the main account's credit balance: * All charges deduct from main account * No separate payment methods per subaccount * Track usage per subaccount via API for client invoicing *** ## Credentials | Account Type | Auth ID Prefix | Access | | ------------ | -------------- | ------------------------------- | | Main account | `MA` | All resources + all subaccounts | | Subaccount | `SA` | Only its own resources | Subaccounts cannot access main account or other subaccount resources. *** ## Phone Numbers * Assign numbers when renting or transfer later * Each number belongs to one account only * Numbers transfer to main account when subaccount deleted (unless cascade=true) *** ## Related * [Subaccount API Reference](/docs/account/api/subaccount) # Account Management Source: https://plivo.com/docs/faq/account/account-management Common questions about managing your Plivo account, subaccounts, and settings Frequently asked questions about Plivo account setup, credentials, security, team management, and subaccounts. *** ## How do I create a Plivo account? 1. Go to [Plivo signup](https://cx.plivo.com/signup) 2. Enter your name, work email, and set a password 3. Verify your email via activation link 4. Verify your phone number **Requirements:** * Work email address — personal (e.g., @gmail.com, @yahoo.com) and disposable email domains are not accepted * Valid phone number for verification * No VPN during onboarding Plivo validates email domains during signup. If validation fails, signup will not proceed. To send voice or messaging traffic to countries beyond the US and India, a minimum spend agreement is required. See [Plivo Pricing](https://www.plivo.com/pricing/) for details. *** ## What is Data Region? During signup, you select a **Data Region** that determines which phone numbers and services you can access. | Data Region | Can Access | Payment Method | | ----------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **United States** | Phone numbers in [supported countries](https://www.plivo.com/virtual-phone-numbers/coverage/), international calling | International credit/debit cards or USD Bank Transfer — **cards issued in India are not accepted** | | **India** | Indian phone numbers only, calling within India | Indian credit/debit cards only — **cards issued outside India are not accepted** | **Data region cannot be changed after account creation.** Card origin and data region must match: * **Card issued in India →** choose the **India** data region. US data region accounts cannot be charged with India-issued cards. * **Card issued outside India →** choose the **US** data region. India data region accounts cannot be charged with international cards. If you need both Indian numbers and international calling, you'll need separate accounts for each region. ### When to choose India * Your business is registered in India * You only need Indian phone numbers * You're making calls within India ### When to choose United States * You need phone numbers outside India * You need to make international calls * You're operating globally *** ## What happens if my signup is delayed? Plivo verifies all signups to ensure compliance with telecommunications regulations. Accounts may be placed on hold if risk assessment indicates concerns. Contact [Plivo Support](https://support.plivo.com) if delayed. *** ## Why can't I create an account with my email? Plivo requires a **business domain email address** for account registration. | Email Type | Accepted? | Example | | --------------- | --------- | -------------------------------------------------------------------------------- | | Business domain | ✅ Yes | [john@yourcompany.com](mailto:john@yourcompany.com) | | Personal email | ❌ No | [john@gmail.com](mailto:john@gmail.com), [john@yahoo.com](mailto:john@yahoo.com) | | Temporary email | ❌ No | [john@tempmail.com](mailto:john@tempmail.com) | *** ## I can't log in to my account. What should I do? ### Troubleshooting steps | Issue | Solution | | ------------------------------- | ---------------------------------------------------------------------------- | | **Forgot password** | Click "Forgot password" on login page, check email (including spam) | | **Password reset link expired** | Request a new reset link (links expire after 24 hours) | | **2FA code not working** | Ensure device time is synced; try recovery codes | | **Locked out of 2FA** | Contact [Plivo Support](https://support.plivo.com) with account verification | | **Account suspended** | Check email for suspension notice; contact support | | **Browser issues** | Clear cache/cookies, try incognito mode, or different browser | ### If password reset emails aren't arriving 1. Check spam/junk folder 2. Verify you're using the correct email address 3. Add `noreply@plivo.com` to your contacts 4. Wait 5-10 minutes (email delivery can be delayed) 5. Try requesting another reset ### If you've lost access to 2FA 1. Try using **recovery codes** (saved during 2FA setup) 2. If no recovery codes, contact [Plivo Support](https://support.plivo.com) with: * Account email address * Auth ID (if known) * Business verification documents **Security verification required:** For security, Plivo requires identity verification before disabling 2FA on an account. This process may take 1-2 business days. *** ## Why is my account disabled or suspended? Your account may be disabled for several reasons: | Reason | Solution | | ----------------------------- | ------------------------------------------------- | | **Policy violation** | Check email for violation notice, contact support | | **Suspicious activity** | Verify identity with support | | **Fraudulent usage detected** | Contact support with business verification | | **AUP violation** | Review Acceptable Use Policy, contact support | | **Inactivity** | Contact support to reactivate | ### To reactivate a disabled account 1. Check your email for any notices from Plivo 2. Log in to Console (if possible) and review any alerts 3. Contact [Plivo Support](https://support.plivo.com) with: * Your account email * Auth ID (if known) * Business verification documents (if requested) Reactivation may require identity verification and can take 1-3 business days depending on the reason for suspension. *** ## How do I close or delete my account? To close (or delete) your account, go to the [Organization settings](https://cx.plivo.com/profile/organization) page (**Profile > Organization**) and click **Delete Organization**. Closing your account is **irreversible**. Once closed, you will no longer be able to log in, and no request to restore the account or its data will be entertained. **After closure:** * All applications, phone numbers, endpoints, and logs are permanently deleted * Remaining credits are refunded within 20 business days (only recharges from the last 90 days) * Trial credits are not refunded * Team members lose access immediately *** ## What are Auth ID and Auth Token? | Credential | Description | | -------------- | ------------------------------------------------------------- | | **Auth ID** | Your unique account identifier (username) — cannot be changed | | **Auth Token** | Your API password — can be changed | Find them at the top of the [Plivo Console](https://cx.plivo.com/home) home page. *** ## How do I regenerate my Auth Token? 1. Go to [Auth Settings](https://cx.plivo.com/profile/auth) in the Plivo console 2. Click **Generate Auth Token** 3. Select when to expire the old token: * **Delete immediately** — old token stops working right away * **Delete in 48 hours** — gives you time to update your applications 4. Type `delete auth token` to confirm Only one Auth Token can be active at a time. After the old token expires, any application still using it will fail to authenticate. Update all integrations with the new token and test before the old token expires. *** ## Is Two-Factor Authentication mandatory? Yes. 2FA is mandatory for all Plivo accounts. **Available methods:** * Phone OTP (SMS/Voice) * Authenticator apps (Google Authenticator, 1Password, Microsoft Authenticator, Authy) * Recovery codes *** ## How do I set up an authenticator app for 2FA? 1. Go to **Account > Settings > Security > Two-Factor Authentication** 2. Click **Add** next to Authenticator App 3. Verify with OTP sent to your phone 4. Scan the QR code with your authenticator app 5. Enter the generated code to confirm *** ## How do I change my phone number for 2FA? 1. Navigate to **Account > Settings > Security > Two-Factor Authentication** 2. Click the 3-dot menu next to Phone Verification 3. Select **Change Number** 4. Authenticate with your current method 5. Enter and verify the new number *** ## How do I set up Single Sign-On (SSO)? 1. Navigate to **Account > Settings > Security** 2. Click **Configure** in the Configure SSO widget 3. Select your identity provider 4. Follow the configuration guide Contact [Plivo Support](https://support.plivo.com) to access SSO. *** ## What is IP Whitelisting? IP Whitelisting restricts API access to specific IP addresses. **To configure:** 1. Go to **Account > Settings > IP Whitelisting** 2. Click **+ Add CIDR Address** 3. Enter IP addresses in CIDR format (e.g., `192.0.2.0/24`, `1.1.1.1/32`) 4. Toggle the switch to enable *** ## What are the security best practices? * Use a strong password (12+ characters with mixed case, numbers, symbols) * Enable 2FA * Use role-based access for team members * Use individual email addresses * Monitor account alerts * Keep Auth Token private like a password * Regularly rotate Auth Tokens * Set up IP whitelisting *** ## What should I do if my account is compromised? 1. Check login notification emails from Plivo 2. Review payment receipts for unfamiliar charges 3. Check usage logs in the console 4. Immediately regenerate your Auth Token 5. Change your password 6. Review and remove unauthorized team members 7. Contact [Plivo Support](https://support.plivo.com) *** ## What are the team roles? | Role | Access | | ------------------- | ----------------------------------------------------------------- | | **Owner** | Full access (auto-assigned to account creator, cannot be changed) | | **Administrator** | Same as owner — billing, credentials, configuration, logs | | **Developer** | Application configuration, logs, API access (no billing) | | **Support** | View logs and usage (read-only) | | **Finance Analyst** | Billing and payment access only | *** ## How do I transfer account ownership? Account ownership cannot be reassigned to a different team member. However, you can transfer access by updating the owner's email address: 1. Go to [Profile Details](https://cx.plivo.com/profile/details) in the Plivo console 2. Update the email address to the new owner's email 3. Complete the 2FA verification to confirm the change The new email address holder will then have owner access to the account. *** ## How do I invite team members? 1. Go to **Settings > Account > Team** 2. Click **Add New User** 3. Enter the user's email address 4. Select the appropriate role 5. Click **Invite User** *** ## What are the benefits of subaccounts? * Individual phone numbers and applications per subaccount * Unique Auth ID and Auth Token for each * Credits deducted from main account (no separate recharges) * Single consolidated invoice * Ability to whitelist unique sender IDs per subaccount Billing is at the account level — subaccounts provide a usage breakdown split by main account and each subaccount, but there is no separate invoice per subaccount. *** ## How do I create a subaccount? **Via Console:** 1. Navigate to subaccount management 2. Click **Create Subaccount** 3. Configure settings **Via API:** Use the [Subaccount API](/docs/account/api/subaccount). *** ## What balance notifications does Plivo send? Plivo automatically sends email alerts when your balance drops below \$250, \$100, and \$10. **Configure custom alerts:** 1. Go to Payment Settings 2. Set up to 3 custom threshold amounts 3. Add additional notification email addresses **Recommendation:** Set one alert equal to your average daily usage. *** ## Where do I find pricing information? Access pricing by country through: * **Voice:** Console > Voice > Pricing * **SMS:** Console > Messaging > Pricing *** ## What is the inactive account policy? Accounts with stored payment methods are vulnerable to takeover. Inactive accounts may be sold or misused. Accounts are reviewed for activity periodically. To keep your account active, maintain regular usage or contact support. *** ## How do I create a support ticket? 1. Go to [Plivo Support](https://support.plivo.com) 2. Click **Create New Ticket** 3. Enter email, subject, and description 4. Select category and priority 5. Attach files if needed 6. Click **Create New Ticket** Check ticket status anytime at **Check Ticket Status** on the support homepage. *** ## Related Resources * [Payments](/docs/faq/billing-and-invoices/payments) * [Invoices](/docs/faq/billing-and-invoices/invoices) * [Subaccount API](/docs/account/api/subaccount) * [Contact Support](https://support.plivo.com) # Plans and Pricing Source: https://plivo.com/docs/faq/account/plans Pricing plans, limits, and how to choose the right plan for your use case Plivo offers two plans to fit different business needs: * **Professional** (pay-as-you-go) — ideal for startups, developers, and businesses getting started with Plivo Platform. * **Enterprise** — built for high-volume businesses that need custom configurations, compliance certifications, and dedicated support. Available channels, limits, and features vary by data region. Use the tabs below to compare plans for your region. Your data region is shown at the top of the [Plivo console](https://cx.plivo.com/home) header (for example, **Data Region: US**), next to your plan name. *** ## Plan Comparison | Feature | Professional | Enterprise | | ---------------------------------- | --------------------------------------------------------------- | ------------------------------------------------- | | **Pricing** | Pay-as-you-go ([per-use rates](https://www.plivo.com/pricing/)) | Custom, volume-based pricing — from \$1,000/month | | **Usage limit** | \$2,500/month | Unlimited | | **CPS** | 2 (default) | Custom | | **Coverage** | United States | Custom — [global](/docs/numbers#country-availability) | | **Voice & SIP Trunking** | ✓ | ✓ | | **SMS, MMS & RCS** | ✗ | ✓ | | **WhatsApp (Messaging & Call)** | ✗ | ✓ | | **Verify** | ✗ | ✓ | | **AI Agents** | Voice | All channels | | **Shortcodes & Custom Sender IDs** | ✗ | ✓ | | **Compliance** | ✗ | BAA, HIPAA | | **SSO** | ✗ | ✓ | | **Onboarding** | Self-serve | Dedicated Slack channel | | Feature | Professional | Enterprise | | ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- | | **Pricing** | Pay-as-you-go ([per-use rates](https://www.plivo.com/pricing/)) | Custom, volume-based pricing — from ₹1,00,000/month | | **Usage limit** | ₹2,00,000/month | Unlimited | | **CPS** | 2 (default) | Custom | | **Voice & SIP Trunking** | ✓ | ✓ | | **SMS, MMS & RCS** | ✗ | ✗ | | **WhatsApp (Messaging & Call)** | ✗ | ✓ | | **AI Agents** | Voice | All channels | | **Onboarding** | Self-serve | Dedicated Slack channel | In the India data region, calling is restricted to India in line with local compliance requirements. *** ## How to Upgrade **Prerequisite:** An active Plivo account. You can request an upgrade to Enterprise through **Buddy**, Plivo's in-console chat agent. Open Buddy from the [Plivo console](https://cx.plivo.com/home) and ask to upgrade — the team will follow up with a custom quote based on your volume and requirements. *** ## Frequently Asked Questions ### Can I start with Professional and upgrade later? Yes. Most customers start on the Professional plan and upgrade to Enterprise as their usage grows or when they need enterprise features like compliance certifications. Note that the Enterprise plan starts at a minimum of **\$1,000/month** in the US data region and **₹1,00,000/month** in the India data region. ### What happens if I exceed the Professional plan limits? Your account is temporarily limited. To continue, request an upgrade to Enterprise through Buddy, Plivo's in-console chat agent. ### Is there a free trial? Yes. You get free credits for your first 3 weeks. After they expire, add a payment card to continue on the Professional plan. You can later upgrade to Enterprise as your needs grow. ### Can I get volume discounts on the Professional plan? No. Volume discounts are only available on the Enterprise plan. If you have high volume, Enterprise may be more cost-effective. *** ## Related Resources * [Payments](/docs/faq/billing-and-invoices/payments) - Payment methods and recharges * [Voice Pricing](https://www.plivo.com/pricing/voice/) - Per-minute voice rates * [SMS Pricing](https://www.plivo.com/pricing/sms/) - Per-message SMS rates * [Contact Sales](https://www.plivo.com/contact/sales/) - Get an Enterprise quote # Billing Concepts Source: https://plivo.com/docs/faq/billing-and-invoices/billing-concepts How billing works for voice calls, SMS, MMS, and phone numbers on Plivo Frequently asked questions about how Plivo charges for voice calls, messaging, and phone numbers. *** ## How does voice call billing work? Plivo bills voice calls based on per-minute rates with billing increments that depend on the product: | Product | Billing Increment | How It Works | | ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Voice API | 60-second (60/60) | Calls are rounded up to the next full minute. A 10-second call is billed as 1 minute. | | Zentrunk (SIP Trunking) | Varies by country | Per-second (1/1) for US routes, 60-second (60/60) for India routes. Other destinations vary — check your rate sheet for details. | **Key details:** * Billing starts when the call is answered, not when it starts ringing. * Both inbound and outbound call legs are billed separately. * Rates vary by destination country and number type. See [Voice Pricing](https://www.plivo.com/pricing/voice/) for current rates. *** ## How does SMS and MMS billing work? SMS and MMS are billed **per message segment**. **SMS segments:** * A single SMS segment can contain up to **160 characters** using GSM-7 encoding (standard Latin characters). * If your message uses **Unicode** characters (such as non-Latin scripts or special symbols), the segment limit drops to **70 characters**. * Messages longer than one segment are split into multiple segments, each billed separately. For multi-part messages, segment limits are 153 characters (GSM-7) or 67 characters (Unicode) due to concatenation headers. **MMS:** * MMS messages are billed per message, regardless of media size. * MMS is available only for US and Canadian destinations. See [SMS Pricing](https://www.plivo.com/pricing/sms/) for current per-segment rates. *** ## What are phone number charges? Plivo charges a **monthly rental fee** for each phone number on your account. * Rental is charged on a calendar-month basis starting from the date of purchase. * Rates vary by country and number type (local, toll-free, mobile, national). * Some countries may have one-time setup charges in addition to the monthly rental. * Numbers removed mid-month are billed for the full month. See [Phone Number Pricing](https://www.plivo.com/virtual-phone-numbers/pricing/) for rates by country. *** ## What is CPS and how do I increase it? **CPS (Calls Per Second)** is the maximum number of concurrent outbound call requests Plivo processes per second for your account. | Account Type | Default CPS | | ------------ | -------------------------------- | | Standard | 2 CPS | | Enterprise | Custom (higher limits available) | Voice API and Zentrunk (SIP Trunking) each have their own separate CPS limit per account. For example, a standard account can initiate 2 outbound calls per second via Voice API and 2 outbound calls per second via Zentrunk simultaneously. If you need higher CPS for large-scale calling campaigns or high-volume applications, ask **Buddy**, Plivo's in-console chat agent, from the [Plivo console](https://cx.plivo.com/home) to move to an Enterprise plan with increased CPS limits. CPS limits apply to outbound call initiation only. They do not limit the number of concurrent active calls on your account. *** ## What do billing increments like 1/1 and 6/6 mean? These are standard telecom billing increment notations in the format **initial/subsequent**: | Increment | Meaning | | --------- | ------------------------------------------------------------------------------------------------------ | | **1/1** | Per-second billing — both the first and every subsequent second are billed individually | | **6/6** | Billed in 6-second blocks — the first 6 seconds are billed as a block, then every additional 6 seconds | | **60/60** | Per-minute billing — the first 60 seconds are billed as a block, then every additional 60 seconds | | **30/6** | First 30 seconds billed as a block, then every additional 6 seconds | **Example with 60/60 billing:** A call lasting 61 seconds is billed as 120 seconds (2 minutes). Plivo Voice API uses **60/60** (per-minute) billing. Zentrunk billing increments vary by country — for example, **1/1** (per-second) for US routes and **60/60** (per-minute) for India routes. Check your Zentrunk rate sheet for destination-specific increments. *** ## Related Resources * [Payments](/docs/faq/billing-and-invoices/payments) * [Invoices](/docs/faq/billing-and-invoices/invoices) * [Taxes](/docs/faq/billing-and-invoices/taxes) * [Voice Pricing](https://www.plivo.com/pricing/voice/) * [SMS Pricing](https://www.plivo.com/pricing/sms/) * [Phone Number Pricing](https://www.plivo.com/virtual-phone-numbers/pricing/) # Invoices Source: https://plivo.com/docs/faq/billing-and-invoices/invoices Understanding your Plivo invoices, line items, and billing details Frequently asked questions about Plivo invoices, billing cycles, and usage reports. *** ## What is included in an invoice? Invoices contain three main sections: | Section | Contents | | ------------------- | --------------------------------------------------- | | **Invoice Summary** | Usage ID, generation date, Auth ID, billing address | | **Usage Summary** | Breakdown by product (Voice, SMS, Numbers, etc.) | | **Payment Summary** | Credits applied and amounts charged | *** ## When are invoices generated? Invoices are generated on the first business day of each month for the preceding month. **Example:** The January invoice is created on February 1st. *** ## How do I access my invoices? Navigate to **Billing > Invoices** in the [Plivo console](https://cx.plivo.com/billing/payment-methods). *** ## What detailed information is available beyond the main invoice? Plivo provides XLSX format usage supplements containing six sheets: | Sheet | Contents | | -------------- | ------------------------------------- | | Voice Inbound | Calls by destination country and type | | Voice Outbound | Calls by destination | | SMS Inbound | Messages by country and type | | SMS Outbound | Messages by country and type | | Number Rentals | Phone number charges | | Zentrunk | SIP trunking usage | *** ## How do I generate a fair usage report? **For Voice:** 1. Go to Voice Logs 2. Click **Export** 3. Select **Export Fair Usage Report** 4. Click **Export Logs** **For Zentrunk:** 1. Navigate to Zentrunk Logs 2. Follow the same process Reports show total eligible calls, short duration calls, abandoned calls, and corresponding charges. *** ## Related Resources * [Payments](/docs/faq/billing-and-invoices/payments) * [Taxes](/docs/faq/billing-and-invoices/taxes) * [Contact Support](https://support.plivo.com) # Payments Source: https://plivo.com/docs/faq/billing-and-invoices/payments Payment methods, auto-recharge, failed payments, and 3D Secure troubleshooting Frequently asked questions about payment methods, account recharges, and credits on Plivo. *** ## Payment Methods ### Accepted payment methods | Method | Availability | Minimum | Settlement | | ----------------- | ------------- | ------- | -------------------- | | Credit Card | All customers | \$25 | Immediate | | ACH Direct Debit | US only | \$25 | 5 business days | | USD Bank Transfer | All customers | — | Same-day or next-day | Accepted cards: Visa, Mastercard, American Express, and Discover. PayPal is not supported. A 3% payment gateway fee applies on all card transactions. **Cards issued in India are not accepted on US data region accounts.** If your card is issued by a bank in India, sign up for the India data region account or pay via [USD Bank Transfer](#how-do-i-set-up-usd-bank-transfer). Data region cannot be changed after account creation. *** ### My card payment is failing with 3D Secure / OTP. What should I do? Some banks require 3D Secure (3DS) authentication — an additional verification step like an OTP or bank app approval — for online transactions. **Troubleshooting steps:** 1. **Enable pop-ups** — the 3DS verification window opens in a pop-up. Make sure your browser allows pop-ups for the Plivo console. 2. **Try a different browser** — some browser extensions or privacy settings block the 3DS iframe. 3. **Check with your bank** — confirm your card is enrolled for 3DS and that online/international transactions are enabled. 4. **Try a different card** — if the issue persists, use another card from a different issuer. If the charge still fails after these steps, contact [Plivo Support](https://support.plivo.com) with the error message shown. *** ### How do I add a credit card? 1. Navigate to **Billing** in the Plivo console 2. Enter card information in the Payment Details section 3. Click **Add New Card** *** ### How do I set up ACH Direct Debit (US only)? ACH debit requires at least one credit card on file. 1. Navigate to **Billing** and select bank direct debits 2. Enter bank account details 3. Plivo sends a micro-deposit of \$0.01 with a code starting with "SM" 4. Enter the four digits following "SM" in the console to verify Verification typically takes 2-3 days. Maximum 10 verification attempts allowed. *** ### How do I set up USD Bank Transfer? USD Bank Transfer avoids the 3% Payment Gateway Fee charged on credit card payments. **Transfer options:** * Domestic Wire Transfer: Same-day settlement * ACH Transfer: Next-day settlement Contact [Plivo Support](https://support.plivo.com) to set up USD Bank Transfer. *** ### How do I set up wire transfer payments? For wire transfers over \$1,000, contact [Plivo Support](https://support.plivo.com) with: * Your use case * Company details * Estimated monthly volume ### Requirements for India-registered businesses | Requirement | Details | | ----------- | ---------------------------------------------- | | Currency | INR only | | Route Type | Domestic routes | | GST | Required with registration provided in Console | | Card Type | Credit and Debit cards (Indian) | *** ### Accepted payment methods **Indian Credit/Debit Card:** * Minimum: ₹2,000 * Settlement: Immediate * Note: 2% payment gateway fee applies on all card transactions **Only cards issued in India are accepted on India data region accounts.** Cards issued outside India are not supported — if your only payment method is an international card, sign up for the US data region account instead. Data region cannot be changed after account creation. **Netbanking:** * Minimum: ₹10,000 * Settlement: Immediate * No payment gateway fee (0%) To pay using netbanking, open the [Plivo Console](https://cx.plivo.com/home), go to **Billing > Overview**, and click **Add Credits**. Select an amount of ₹10,000 or more, choose **Netbanking**, and click **Recharge**. Netbanking is rolling out and not every bank is supported yet. The banks available to you appear after you click **Add Credits** and choose **Netbanking**. Plivo is working to expand coverage. *** ### GST requirements * GST registration details must be entered in the Console * 18% GST charged on all invoiced amounts * GSTIN must be provided for tax compliance *** ## Recharges and Credits ### How do I manually recharge my account? 1. Navigate to **Billing** 2. Enter the recharge amount (minimum \$25 USD or ₹2,000 INR) 3. Complete payment *** ### What is auto-recharge and how does it work? Auto-recharge automatically adds funds when your balance drops below \$25. **How it works:** 1. When your balance drops below \$25, Plivo charges your card for the configured recharge amount 2. Choose a recharge amount: \$25, \$50, \$100, \$250, \$500, or \$1,000 3. If a recharge fails, Plivo retries when your balance drops below the threshold again **Example:** Starting balance \$100, recharge amount \$100. If a \$90 charge reduces the balance to \$10 (below \$25), auto-recharge triggers and adds \$100, resulting in a final balance of \$110. **Removing your credit card disables auto-recharge.** If you remove the card on file, auto-recharge stops working and your account may run out of funds. Add a new card and re-enable auto-recharge to resume. Auto-recharge is not available for India (INR) accounts. INR accounts must recharge manually. *** ### How do I configure auto-recharge? 1. Navigate to **Billing** 2. Go to the Auto Recharge section 3. Select a recharge amount (\$25, \$50, \$100, \$250, \$500, or \$1,000) 4. Save *** ### What are monthly recharge limits? Monthly limits protect against fraudulent activity like SMS pumping or credential leaks. * The system calculates a recommended limit based on usage * Limits can be adjusted anytime in the Console * Some accounts have upper caps based on account history *** ### What balance notifications does Plivo send? Plivo automatically sends email alerts when your balance drops below \$250, \$100, and \$10. **Custom alerts:** * Configure up to 3 custom threshold amounts * Add additional notification email addresses via Payment Settings *** ## Related Resources * [Invoices](/docs/faq/billing-and-invoices/invoices) * [Taxes](/docs/faq/billing-and-invoices/taxes) * [Voice Pricing](https://www.plivo.com/pricing/voice/) * [SMS Pricing](https://www.plivo.com/pricing/sms/) * [Phone Number Pricing](https://www.plivo.com/virtual-phone-numbers/pricing/) * [Contact Support](https://support.plivo.com) # Taxes Source: https://plivo.com/docs/faq/billing-and-invoices/taxes Tax charges, exemptions, and regulatory fees on your Plivo account Frequently asked questions about taxes, surcharges, and regulatory fees on Plivo invoices. **Regional tax applicability:** * **United States:** The taxes and fees described below (Sales Tax, Telecom Tax, CCRF, Carrier Surcharges) apply to businesses registered in the US, identified by billing address. * **India:** GST of 18% is applicable on all spends. See [India taxes](#what-taxes-apply-for-india-based-accounts) for details. *** ## What additional charges may appear on my invoice? Your invoice may include additional charges based on service type and location: | Charge | Description | | ---------------------- | ------------------------------------------------------------------------------------- | | **Sales Tax** | State and local taxes based on service address | | **Telecom Tax** | Telecommunications-specific taxes | | **CCRF** | Carrier Cost Recovery Fee — fixed percentage on US voice, numbers, and Zentrunk usage | | **Regulatory Fees** | Federal communications program contributions | | **Carrier Surcharges** | Fees imposed by US/Canadian carriers on SMS/MMS traffic | *** ## What is the Carrier Cost Recovery Fee (CCRF)? CCRF is a pass-through mechanism for recovering federal regulatory costs, including: * Universal Service Fund contributions * Other telecommunications fees This charge applies exclusively to US-originating or US-terminating calls. *** ## What are carrier surcharges on messaging? US and Canadian carriers levy surcharges on SMS and MMS communications. These fees vary depending on: * Mobile carrier * Message type (SMS vs MMS) * Number type (long code, toll-free, or short code) *** ## How are taxes calculated? Plivo determines applicable taxes using your billing address, including: * State and local sales taxes * Telecom taxes * Jurisdiction-specific charges Update your billing address in **Account Settings** for accurate assessment. *** ## Why does Plivo charge taxes? Where Plivo has sufficient presence in a state, locality, or jurisdiction, we are required to collect applicable taxes and remit them to appropriate authorities. Sales tax functions as an indirect tax at the point of transaction — although Plivo pays initially, customers ultimately bear the burden per applicable law. *** ## What taxes apply for India-based accounts? | Tax Type | Details | | --------- | ----------------------------------- | | **GST** | 18% charged on all invoiced amounts | | **GSTIN** | Required in account profile | Supply your GST registration details through the Console for proper account configuration. *** ## Related Resources * [Payments](/docs/faq/billing-and-invoices/payments) * [Invoices](/docs/faq/billing-and-invoices/invoices) * [Contact Support](https://support.plivo.com) # AI-Powered Documentation Search Source: https://plivo.com/docs/faq/developer-tools/mcp-server Connect your AI assistant to Plivo documentation using the Model Context Protocol (MCP) Plivo provides an MCP server that allows AI assistants to search our documentation. Use it to get accurate, contextual answers about Plivo APIs, SDKs, and features directly in your development environment. **MCP Server URL:** `https://plivo.com/docs/mcp` *** ## What is MCP? The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that lets AI applications connect to external tools and data sources. By connecting your AI assistant to Plivo's MCP server, it can search our documentation and provide accurate answers with direct links to relevant pages. *** ## Available Tools | Tool | Description | | ------------- | -------------------------------------------------------------------------------------------------------------- | | `SearchPlivo` | Search across the Plivo knowledge base to find relevant information, code examples, API references, and guides | *** ## Setup by Client ### Claude Desktop Add to your Claude Desktop config file: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json theme={null} { "mcpServers": { "plivo": { "command": "npx", "args": ["-y", "mcp-remote", "https://plivo.com/docs/mcp"] } } } ``` Restart Claude Desktop after saving. ### Claude Code (CLI) ```bash theme={null} claude mcp add plivo --transport http https://plivo.com/docs/mcp ``` ### Cursor Go to **Settings → MCP Servers** and add: ```json theme={null} { "mcpServers": { "plivo": { "command": "npx", "args": ["-y", "mcp-remote", "https://plivo.com/docs/mcp"] } } } ``` ### Cline (VS Code) Open Cline settings and add to MCP configuration: ```json theme={null} { "plivo": { "command": "npx", "args": ["-y", "mcp-remote", "https://plivo.com/docs/mcp"] } } ``` ### Windsurf Add to your MCP configuration: ```json theme={null} { "mcpServers": { "plivo": { "command": "npx", "args": ["-y", "mcp-remote", "https://plivo.com/docs/mcp"] } } } ``` *** ## Using with OpenAI or Gemini OpenAI and Google Gemini don't natively support MCP, but you can use MCP-compatible clients that support multiple models: ### Option 1: Use Cursor or Cline Both Cursor and Cline support MCP and allow you to switch between Claude, GPT-4, and Gemini models: 1. Configure the MCP server as shown above 2. Change your model to GPT-4o or Gemini in the client settings 3. The client bridges MCP tools to the model's function calling ### Option 2: Direct API Integration Call the MCP endpoint directly and include the results in your prompt: ```python theme={null} import requests import openai # or google.generativeai # Search Plivo documentation response = requests.post( "https://plivo.com/docs/mcp", json={ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "SearchPlivo", "arguments": {"query": "audio streaming websocket"} }, "id": 1 } ) docs_context = response.json() # Use with OpenAI completion = openai.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": f"Answer using this context:\n{docs_context}"}, {"role": "user", "content": "How do I set up audio streaming with Plivo?"} ] ) print(completion.choices[0].message.content) ``` ### Option 3: LangChain Integration ```python theme={null} from langchain_mcp import MCPToolkit from langchain_openai import ChatOpenAI toolkit = MCPToolkit(server_url="https://plivo.com/docs/mcp") tools = toolkit.get_tools() llm = ChatOpenAI(model="gpt-4o").bind_tools(tools) response = llm.invoke("How do I make an outbound call with Plivo?") ``` *** ## Example Queries Once connected, try asking your AI assistant: * "How do I make an outbound call with Plivo in Python?" * "What are the audio streaming WebSocket message formats?" * "Show me how to set up a Pipecat voice agent" * "What XML elements can I use for IVR?" * "How do I handle incoming SMS messages?" The AI will search Plivo documentation and provide accurate answers with links to the relevant pages. *** ## Troubleshooting | Issue | Solution | | ---------------------- | --------------------------------------------------------------------- | | "MCP server not found" | Ensure you have Node.js installed and `npx` is available in your PATH | | Connection timeout | Check your network connection and firewall settings | | No search results | Try rephrasing your query with different keywords | | Tool not appearing | Restart your AI client after configuration changes | *** ## Related * [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification and documentation * [MCP Remote](https://www.npmjs.com/package/mcp-remote) - NPM package for connecting to remote MCP servers # Postman Collection Source: https://plivo.com/docs/faq/developer-tools/postman Test Plivo APIs using our official Postman collection Plivo provides an official Postman collection with pre-configured endpoints for Voice, SMS, Phone Numbers, Account, Lookup, and PHLO APIs. Add to your Postman workspace *** ## What's Included | Product | APIs | | ----------------- | ----------------------------------------- | | **Voice** | Calls, Conferences, Recordings, Endpoints | | **SMS** | Messages, Media (MMS) | | **Phone Numbers** | Search, Buy, Manage | | **Account** | Details, Subaccounts | | **Lookup** | Number validation | | **PHLO** | Workflow triggers | *** ## Quick Setup 1. **Fork the collection** using the button above 2. **Add credentials** in the collection's Authorization tab: * Username: Your Auth ID * Password: Your Auth Token 3. **Set environment variable** `auth_id` to your Auth ID 4. **Start testing** - all endpoints are pre-configured *** ## Detailed Guide For step-by-step setup instructions with screenshots, see [Postman Collections Guide](/docs/messaging/quickstart/postman). # A2P Guidelines for ISVs Source: https://plivo.com/docs/faq/messaging/isv-guidelines ISV guidelines for building and selling A2P messaging applications on Plivo Frequently asked questions about Plivo's guidelines for Independent Software Vendors (ISVs) providing A2P messaging and voice services. *** ## What is an ISV? Independent Software Vendors (ISVs) provide A2P messaging and voice services to businesses, helping with campaign planning, content creation, deployment, monitoring, and analytics. A2P content includes P2P-like messaging, marketing, notifications, OTP authentication, and more. *** ## What types of brands can ISVs onboard? ISVs should only onboard traffic from **direct brands**—businesses that engage directly with end subscribers and collect opt-ins. ISVs working with other ISVs need prior approval from Plivo. *** ## How should ISVs segregate traffic between brands? ISVs must separate traffic for each end brand using sub-accounts: * Create a sub-account for each end brand * Use that sub-account for all messaging and calling API requests * Maintain clear separation between brands *** ## How does geography access work for ISVs? By default, access to all regions outside the US is disabled at the main account level. ISVs should enable access to relevant geographies only after completing KYC for each end brand. *** ## Can ISVs use short codes in the US and Canada? No. Plivo does not offer short codes for A2P messaging in the US or Canada to ISV/Reseller customers. **Alternatives:** * Use long codes or toll-free numbers for messaging traffic * For OTP delivery, use [Plivo Verify](/docs/programmable-api/verify/overview) for short code-based OTP at no additional cost *** ## Can I use the same sender ID for multiple brands? No. All messaging and calling compliance flows must be completed for each end brand separately. If a sender ID is approved for Brand B1, it cannot be used for Brand B2, even for legitimate use cases like 2FA. *** ## What content is prohibited for ISVs? The following categories are strictly prohibited. No campaign or toll-free verification will be supported: | Category | Examples | | ----------- | --------------------------------------------------- | | Financial | Mortgage, loans, credit repair, debt collection | | Investment | Stock alerts, cryptocurrency, high-risk investments | | Marketing | Lead generation, affiliate marketing, MLM | | Employment | Deceptive work-from-home, job postings | | Real Estate | Sales, servicing | | Gambling | Gambling, sweepstakes | | Regulated | Tobacco/vape, illegal drugs, SHAFT content | **SHAFT:** Sex, Hate, Alcohol, Firearms, and Tobacco *** ## Can I use URL shorteners? | Type | Allowed | | --------------------------------------- | ------- | | Public shorteners (bit.ly, tinyurl.com) | No | | ISV-owned shorteners | No | | Brand-owned shorteners | Yes | *** ## What are the opt-out requirements for ISVs? * If an end subscriber opts out, do not contact them again regardless of sender ID used * Monitor incoming messages and remove opted-out customers from contact lists * Subscribers on national do-not-call lists must be excluded * Subscribe to available DNC lists *** ## How does keyword monitoring work? Plivo blocks outbound messages containing specific keywords that may violate the AUP. * ISVs can request to whitelist specific keywords on a case-by-case basis * Decisions are at Plivo's compliance team discretion * Two weeks notice given before enforcement of changes *** ## Can ISVs redact message content or phone numbers? No. ISVs cannot redact message content or destination phone numbers. This allows Plivo's compliance team to effectively monitor for non-compliance. *** ## What happens if an ISV violates compliance rules? | Violation Type | Action | | ------------------- | ------------------------------------------------------------- | | Single violation | SID or campaign suspension | | Serious violation | All SIDs/campaigns under sub-account suspended without notice | | Multiple violations | Account suspension | *** ## How should ISVs report security compromises? If an ISV detects a compromise affecting message or call traffic: 1. Report immediately via email to [security-report@plivo.com](mailto:security-report@plivo.com) 2. Include relevant supporting details *** ## Related Resources * [Messaging Compliance](/docs/faq/messaging/messaging-compliance) * [Acceptable Use Policy](https://www.plivo.com/aup/) * [Plivo Verify](/docs/programmable-api/verify/overview) * [Sub-account API](https://www.plivo.com/docs/account/api/subaccount/) # Messaging API Source: https://plivo.com/docs/faq/messaging/messaging-api Common questions about sending and receiving SMS and MMS via Plivo API Frequently asked questions about Plivo's Messaging API, throughput limits, message expiry, and data logging. *** ## What does Plivo's Messaging API offer? Plivo's Messaging API enables SMS and MMS messaging to 200+ countries with: * Programmable SMS/MMS via REST API * High throughput delivery * Delivery receipts and callbacks * Message logging and analytics *** ## What is Messages Per Second (MPS)? MPS limits control how fast your account can send messages. ### Default Limits | Type | Default MPS | | ---- | ----------- | | SMS | 5 MPS | | MMS | 0.25 MPS | View your allocated MPS at **SMS > Overview** in the console. *** ## What is the throughput for US numbers? | Number Type | SMS Throughput | MMS Throughput | Daily Limit | | -------------------------- | ---------------- | -------------- | ----------- | | Long Code (Unregistered) | 1 msg/sec | 1 msg/sec | 2,000/day | | Long Code (10DLC Low) | 0.2-0.75 msg/sec | Varies | Varies | | Long Code (10DLC Standard) | 3.75-15 msg/sec | Varies | Varies | | Toll-Free (Verified) | 25 msg/sec | 2 msg/sec | No limit | | Short Code | 100+ msg/sec | Not supported | No limit | *** ## What is the throughput for Canada numbers? | Number Type | SMS | MMS | | ----------- | --------- | ------------- | | Long Code | 15/minute | 15/minute | | Toll-Free | 25/second | 2/second | | Short Code | 10/second | Not supported | **Note:** Verify toll-free numbers to avoid sending limits. *** ## What happens when a message expires? Messages remaining in queue after **3 hours** expire automatically. * Message marked as "failed" * Error code: 420 * No charge applied Messages may expire due to carrier delays, invalid destination numbers, or network issues. *** ## How can I control my data logging preferences? Control how Plivo stores your message data: | Setting | Destination Number | Message Content | | ------------------------ | ------------------ | --------------- | | **Store Both** (Default) | Stored | Stored | | **Store Number Only** | Stored | Not stored | | **Store Content Only** | Not stored | Stored | | **Store Neither** | Not stored | Not stored | Set the `log` parameter in the [Send Message API](https://www.plivo.com/docs/messaging/api/message/#send-a-message). *** ## What's the difference between promotional and transactional SMS? | Type | Purpose | Examples | | ----------------- | --------------------- | --------------------------------- | | **Promotional** | Marketing, sales | Offers, discounts, advertisements | | **Transactional** | Essential information | OTPs, order confirmations, alerts | Different countries have varying regulations for each type. *** ## How does Plivo protect against fraud? ### Geo Permissions Restrict messaging to specific countries: 1. Navigate to **SMS > Settings > [Geo Permissions](https://cx.plivo.com/messaging-settings)** 2. Enable only required destination countries 3. Set messaging thresholds per country ### Unusual Traffic Alerts Plivo monitors for suspicious patterns: * Sudden traffic spikes * Unusual destinations * Potential account takeover You'll receive alerts via email when anomalies are detected. ### Monthly Limits Set spending caps to prevent runaway costs from fraud. *** ## How do I export Message Detail Records (MDR)? ### Via Console 1. Navigate to **SMS > Logs** 2. Click **Filter Logs** to refine 3. Select records to export 4. Click **Export** Small exports download directly; large exports are emailed. ### Via API Use the [Message API](https://www.plivo.com/docs/messaging/api/message/#list-all-messages) to retrieve records programmatically. *** ## How can I add a line break in my SMS or MMS message? Use `\n` for line breaks: ```bash theme={null} curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Message/" \ -u "{auth_id}:{auth_token}" \ -H "Content-Type: application/json" \ -d '{ "src": "14151234567", "dst": "14157654321", "text": "Line 1\nLine 2\nLine 3" }' ``` *** ## What countries do you support for SMS? | Direction | Coverage | | ------------ | --------------------------------------------------------------------------------- | | Outbound SMS | 200+ countries | | Inbound SMS | US, Canada, UK, Australia, France, Germany, Netherlands, Sweden, Austria, Belgium | See [Plivo Coverage](https://www.plivo.com/sms/coverage/) for details. *** ## What are the compliance standards for messaging? All messaging must follow: * Regional laws and regulations * Carrier policies * [Plivo Acceptable Use Policy](https://www.plivo.com/aup/) ### Prohibited Content * Unsolicited spam * Fraudulent or deceptive content * Violence, hate speech, obscenity * Illegal substances promotion See [Messaging Compliance](/docs/faq/messaging/messaging-compliance) for details. *** ## How do I integrate with Bitrix24? 1. Install Plivo from Bitrix24 Marketplace 2. Enter Auth ID, Auth Token, and sender ID 3. Click **Test SMS** to validate *** ## Related Resources * [SMS](/docs/faq/messaging/sms) * [MMS](/docs/faq/messaging/mms) * [US Messaging (10DLC, Toll-Free)](/docs/faq/messaging/us-messaging) * [Short Codes](/docs/faq/messaging/short-codes) * [PHLO for Messaging](/docs/faq/messaging/phlo) * [ISV Guidelines](/docs/faq/messaging/isv-guidelines) * [Messaging API Reference](https://www.plivo.com/docs/messaging/api/) # Messaging Compliance Source: https://plivo.com/docs/faq/messaging/messaging-compliance 10DLC registration, A2P compliance, campaign approval, and rejection reasons Frequently asked questions about sender IDs, country-specific regulations, DND/opt-out management, and delivery alerts. *** ## What is a Sender ID? Sender ID is the name or number that appears as the message sender on the recipient's device. ### Sender ID Types | Type | Example | Support | | ---------------- | -------------- | ----------------- | | **Alphanumeric** | "MyBrand" | Country-dependent | | **Numeric** | "+14151234567" | Most countries | | **Short Code** | "12345" | US, Canada, UK | *** ## What are the Sender ID country categories? | Category | Description | | -------------------- | ------------------------------------ | | **Dynamic** | Instant sender ID support | | **Pre-registration** | Requires carrier approval before use | | **Not Supported** | Must use numeric sender ID | *** ## Which countries require Sender ID pre-registration? | Country | Registration Fee | Recurring Fee | ETA | | --------- | ---------------- | ------------- | --------- | | Singapore | Yes | Monthly | Varies | | UK | Yes | — | 1-2 weeks | Plivo does not support domestic India SMS (DLT). Messages to India are delivered over international (ILDO) routes, which don't require Sender ID pre-registration. See [SMS availability](/docs/messaging/sms-availability). Check [Plivo coverage](https://www.plivo.com/sms/coverage/) for country-specific requirements. *** ## How do I register a Sender ID? 1. Navigate to **Messaging > Settings > Sender ID** 2. Select country 3. Submit registration with required documents 4. Wait for carrier approval *** ## What are the requirements for sending SMS to India? Plivo does not support domestic India SMS, which requires DLT (distributed ledger technology) registration under TRAI regulations. SMS to India is delivered exclusively over international (ILDO) routes, which don't require DLT registration, templates, or PE-TM binding. See [SMS availability](/docs/messaging/sms-availability) for current coverage and requirements. *** ## What are the Singapore Sender ID requirements? **Full SMS Sender ID Registry (SSIR):** * All sender IDs must be registered with SGNIC * Unregistered sender IDs are blocked * Registration required for all organizations *** ## What are the UK SMS regulations? **A2P SMS Filtering:** * Carriers actively filter unregistered traffic * Register sender IDs to avoid filtering * Follow UK carrier guidelines *** ## Can I send messages from Canadian long codes to US? **Cross-Border Restrictions:** * Canadian long codes cannot send to US * Use US numbers for US destinations * Toll-free and short codes work cross-border *** ## What keywords trigger the "Do Not Disturb" (DND) feature? Plivo automatically recognizes these opt-out keywords (case-insensitive): | Keyword | Action | | ----------- | ------- | | STOP | Opt out | | END | Opt out | | QUIT | Opt out | | CANCEL | Opt out | | UNSUBSCRIBE | Opt out | | UNSUB | Opt out | | STOP ALL | Opt out | *** ## What happens when someone opts out? 1. Recipient sends STOP keyword 2. Plivo adds number to suppression list 3. Future messages to that number are blocked 4. Messages fail with DND error code *** ## Can my customers opt back in after opting out? Yes. Opt-in keywords: | Keyword | Action | | ------- | ----------- | | UNSTOP | Opt back in | | START | Opt back in | *** ## Can I reply to customers who have opted out? No. Messages to opted-out users: * Are blocked by Plivo * Fail with appropriate error code * Are not charged *** ## How can I ensure my messages adhere to DND regulations? * Include opt-out instructions in every message * Example: "Reply STOP to opt out" * Monitor inbound messages for complaints * Only message explicit opt-ins *** ## Can I receive email alerts for message delivery issues? Yes. Plivo monitors delivery rates and alerts you to issues. ### Alert Types | Alert | Trigger | | ------------ | ---------------------------------- | | **Outbound** | Significant drop in delivery rate | | **Inbound** | Issues delivering to your endpoint | *** ## I've received an outbound delivery email alert from Plivo. What should I do? 1. Review message content for spam triggers 2. Check number registration status 3. Verify destination numbers are valid **Email includes:** * Total messages sent in past hour * Phone numbers with low delivery * Suggested actions **Frequency:** Maximum once per day per destination country *** ## I've received an inbound delivery email alert from Plivo. What should I do? 1. Check endpoint availability 2. Verify URL configuration 3. Review server logs for errors **Evaluation:** * Checks delivery rate every 15 minutes * Looks at messages from past hour * Alerts if delivery issues detected **Frequency:** Maximum once per day *** ## Why did my outbound SMS delivery fail? **Common causes:** * Carrier filtering * Invalid numbers * Content violations **Inbound issues:** * Endpoint timeout * Server errors (5xx) * Invalid URL configuration *** ## What content is prohibited in messaging? * Unsolicited messages (spam) * Fraudulent or deceptive content * Violence, hate speech, obscenity * Illegal drugs or substances * Marketing to children under 13 (requires extra carrier review) *** ## What is age gating and when is it required? Messages with age-restricted content (SHAFT: Sex, Hate, Alcohol, Firearms, Tobacco) must include age verification before opt-in. *** ## What are the best practices for messaging compliance? ### Consent * Obtain explicit opt-in before messaging * Document consent method and timestamp * Honor opt-outs immediately ### Content * Avoid spam triggers * Include sender identification * Provide opt-out instructions ### Record Keeping * Maintain opt-in records * Log opt-out requests * Document consent methods *** ## What are the penalties for messaging compliance violations? Violations of messaging standards or [Acceptable Use Policy](https://www.plivo.com/aup/) result in penalties. ### Penalty Tiers | Tier | Violation Type | Fine | | ------ | ------------------------------------------ | ----------- | | Tier 1 | Phishing, smishing, social engineering | \$2,000 USD | | Tier 2 | Illegal content | \$1,000 USD | | Tier 3 | Other violations (including SHAFT content) | \$500 USD | Fines apply regardless of country. If a carrier imposes a fine, the amount is deducted from your account. ### Consequences * Single violation: SID or campaign suspension * Serious violation: All SIDs/campaigns suspended without notice * Repeated violations: Account suspension *** ## Related Resources * [Messaging API Overview](/docs/faq/messaging/messaging-api) * [US Messaging](/docs/faq/messaging/us-messaging) * [ISV Guidelines](/docs/faq/messaging/isv-guidelines) * [Acceptable Use Policy](https://www.plivo.com/aup/) # MMS Source: https://plivo.com/docs/faq/messaging/mms MMS support, media types, file size limits, and delivery troubleshooting Frequently asked questions about MMS messaging, supported media types, size limits, and delivery. *** ## What is MMS? MMS (Multimedia Messaging Service) allows sending images, videos, and audio in addition to text. **Availability:** US and Canada only *** ## Is MMS supported by all carriers in the US and Canada? ### Major Carriers * AT\&T, Verizon, T-Mobile (US) * Rogers, Bell, Fido, Telus, Wind Canada ### Minor Carriers 365 Wireless, Alaska Communication System (ACS), Alltel Wireless, Bluegrass Cellular, Boost Mobile, and others. *** ## How much does it cost to send and receive MMS messages? | Direction | Cost per Message | | --------- | ---------------- | | Outbound | \$0.0160 | | Inbound | \$0.0080 | Volume discounts available—contact [Plivo Sales](https://www.plivo.com/contact/sales/). *** ## What types of multimedia content does Plivo accept? | Category | Formats | | --------- | -------------- | | **Image** | JPEG, PNG, GIF | | **Video** | MP4, 3GP, MOV | | **Audio** | MP3, WAV, AMR | See [full list](/docs/faq/messaging/mms) of accepted content types. *** ## What are the size limitations for sending messages with text and images? | Limit | Value | | ---------------------- | --------------------------- | | Total message size | 5 MB | | Maximum attachments | 10 files | | Text content | 1,600 characters (\~4.8 KB) | | Recommended image size | \< 600 KB | **Note:** Plivo does not resize images. Messages exceeding 5 MB fail with error code 120. *** ## Will Plivo automatically resize my images for MMS messaging? No. Plivo does not resize images. You must ensure total message size is under 5 MB before sending. *** ## What MMS content types does Plivo support? Media URLs must return valid `Content-Type` and `Content-Length` headers. URLs without these headers are rejected. *** ## How do I send MMS via API? ```bash theme={null} curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Message/" \ -u "{auth_id}:{auth_token}" \ -H "Content-Type: application/json" \ -d '{ "src": "14151234567", "dst": "14157654321", "type": "mms", "text": "Check out this image!", "media_urls": ["https://example.com/image.jpg"] }' ``` *** ## How do I send MMS via Powerpack? Replace `src` with `powerpack_uuid`: ```json theme={null} { "powerpack_uuid": "your-powerpack-uuid", "dst": "14157654321", "type": "mms", "media_urls": ["https://example.com/image.jpg"] } ``` *** ## How does Plivo manage delivery order of multiple media files via one MMS message? Send up to 10 files in one message: ```json theme={null} { "media_urls": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg", "https://example.com/image3.jpg" ] } ``` **Note:** Media file order is not guaranteed at delivery. *** ## How can I upload media to an MMS message? ### Via Console 1. Navigate to **Messaging > MMS Media Upload** 2. Upload files 3. Use returned `media_id` in API requests ### Via API Use the [Media API](https://www.plivo.com/docs/messaging/api/media/) to upload and manage files. ### Hosted Media Host media on any cloud storage (S3, GCS, etc.) and provide the URL in `media_urls`. *** ## How long does Plivo store MMS media files? | Feature | Details | | ---------------- | ------------------- | | Storage duration | Up to 1 year | | URL type | Publicly accessible | | Extension | Case-by-case basis | Media files sent or received are stored in your account with unique URLs. *** ## How can I retrieve Plivo MMS media files? **Via SDK:** Use the list media method **Via API:** Use the [Media API](https://www.plivo.com/docs/messaging/api/media/) *** ## How do I receive MMS messages? 1. Set `message_url` on your Plivo application 2. Assign MMS-enabled number to application 3. Plivo POSTs inbound MMS to your URL ### Inbound Parameters In addition to standard SMS parameters: | Parameter | Description | | ----------------------- | ----------------------------- | | `Type` | "mms" for multimedia messages | | `Media0`, `Media1`, ... | URLs of attached media files | *** ## What do the different MMS delivery statuses mean? | Status | Meaning | | --------------- | --------------------------------- | | **queued** | Message accepted, waiting to send | | **sent** | Sent to carrier | | **delivered** | Confirmed delivery to recipient | | **undelivered** | Failed to deliver | | **failed** | Error occurred | View status in Message Detail Records or via delivery callbacks. *** ## Can I send and receive MMS on my toll-free phone number? Yes. Toll-free numbers support MMS in the US and Canada. **Features:** * Videos up to 40 seconds * Audio files * Animated GIFs * Images and slideshows * Automatic message queuing *** ## What are the MMS rate limits? ### Account Level | Limit | Value | | --------------- | ------------------------- | | Default MMS MPS | 0.25 | | API concurrency | 100 simultaneous requests | ### Per Number Long code numbers have individual throughput limits. *** ## What happens to MMS messages sent to unsupported destinations? MMS to countries or devices without MMS support returns HTTP 400 error. *** ## What happens to MMS messages sent from unsupported phone numbers? HTTP 400 error is returned. Use an MMS-enabled number. *** ## Does Plivo do anything with the metadata associated with digital pictures? * Metadata (date, time, location) is usually stripped by sending carrier * If carrier preserves metadata, Plivo passes it through * No modification of received metadata *** ## Related Resources * [Messaging API Overview](/docs/faq/messaging/messaging-api) * [SMS](/docs/faq/messaging/sms) * [MMS API Reference](https://www.plivo.com/docs/messaging/api/message/) * [Media API Reference](https://www.plivo.com/docs/messaging/api/media/) # Powerpack Source: https://plivo.com/docs/faq/messaging/powerpack Powerpack number pools, sticky sender, and intelligent number selection for SMS Frequently asked questions about Powerpack, Plivo's intelligent number pool for optimized message delivery. *** ## What is Powerpack? Powerpack is a collection of phone numbers that work together to: * Maximize message deliverability * Manage opt-outs automatically * Load balance across numbers * Support multiple number types (long codes, toll-free, short codes) *** ## What are the benefits of Powerpack? | Feature | Description | | ----------------------- | ------------------------------------------------------ | | **Intelligent routing** | Automatically selects best number for delivery | | **Sticky sender** | Same number used for conversations with each recipient | | **Opt-out management** | Automatic STOP keyword handling | | **Number pool** | Combine long codes, toll-free, and short codes | | **Compliance** | Respects carrier throughput limits | *** ## How do I create a Powerpack? 1. Navigate to **Messaging > Powerpack** 2. Click **Add New Powerpack** 3. Enter Powerpack name 4. Add phone numbers to the pool 5. Configure application settings 6. Save *** ## What types of numbers can I add to Powerpack? ### Long Codes Add US/Canada long codes for A2P messaging: * Requires 10DLC registration for optimal throughput * Recommended: \< 200 messages/day per number ### Toll-Free Numbers Add verified toll-free numbers: * Higher throughput (25 MPS) * Best for 2FA, notifications ### Short Codes Add short codes for maximum throughput: * One US short code per Powerpack * One Canada short code per Powerpack * Same short code cannot be in multiple Powerpacks *** ## Can I add a short code number to my Powerpack? Yes. You can add one US short code and one Canada short code per Powerpack. *** ## Can I add multiple short code numbers to my Powerpack? No. Only one US short code and one Canada short code per Powerpack. *** ## Can I add the same short code number to multiple Powerpacks? No. A short code can only belong to one Powerpack. *** ## What are the benefits of adding a short code to my Powerpack? * Maximum throughput (100+ MPS) * Carrier-approved for A2P messaging * Falls back to long codes if short code is unavailable *** ## Why are long code numbers being used for outbound messages when I have a short code in my Powerpack? Even with short code priority enabled, long codes may be used when: * Short code throughput exceeded * Network compatibility issues * Carrier-specific routing *** ## How do I remove a short code from my Powerpack? To disable short code: 1. Disable "prioritize short code" feature 2. Messages will use other numbers To permanently remove: 1. Open support ticket 2. Request short code removal *** ## How can I send SMS and MMS messages using Powerpack? ### SMS via API ```bash theme={null} curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Message/" \ -u "{auth_id}:{auth_token}" \ -H "Content-Type: application/json" \ -d '{ "powerpack_uuid": "your-powerpack-uuid", "dst": "14157654321", "text": "Hello from Powerpack!" }' ``` ### MMS via Powerpack ```json theme={null} { "powerpack_uuid": "your-powerpack-uuid", "dst": "14157654321", "type": "mms", "media_urls": ["https://example.com/image.jpg"] } ``` *** ## What is Smart Sender? Smart Sender ensures that a destination number always receives texts from the same source number. This stickiness enables two-way conversations by keeping the conversation thread intact. Once a Powerpack number is assigned to a destination, all subsequent texts to that destination are sent from the assigned source number. Turn on Smart Sender from the Plivo console's Powerpack dashboard. *** ## What is Local Connect? Local Connect is a Powerpack feature that personalizes conversations by using the same area codes and local numbers as your users. It uses area code matching and prioritizes local numbers over other numbers in the Powerpack pool. Manage Local Connect preferences from the Powerpack management console. *** ## What happens when a Powerpack SMS or MMS recipient replies with an opt-out keyword? When recipient texts STOP: 1. Subscriber added to suppression list for that source number 2. Future messages to that recipient are blocked 3. Message marked "failed" with appropriate error code ### Suppression List * Per-number suppression tracking * Automatic compliance with opt-out requests * View suppression list in console *** ## How are incoming messages to numbers in my Powerpack handled? Assign an application to your Powerpack to handle incoming messages. *** ## How can I modify an application associated with a Powerpack? 1. Navigate to your Powerpack 2. In Application Configuration, select type: * **XML Application** * **PHLO** 3. Select the application name 4. Update *** ## How can I remove an application from Powerpack? 1. Open Powerpack settings 2. In application type, select any option 3. In application name dropdown, select "-------" 4. Update *** ## Can I use PHLOs to handle incoming messages in my Powerpack? Yes. Use PHLO for visual message handling: 1. Create a PHLO for incoming messages 2. Add PHLO to Powerpack's application configuration 3. Incoming messages trigger PHLO workflow *** ## How can I send 6,000 or more SMS messages per day using a long code in the US? For US long codes without 10DLC, the limit is \< 200 messages/day per number. **Options:** * Register for 10DLC to increase limits * Add multiple numbers to your Powerpack * Use toll-free or short codes | Volume | Recommended | | ---------------- | --------------------- | | \< 2,000/day | Registered long codes | | 2,000-50,000/day | Toll-free | | 50,000+/day | Short code | *** ## How can I configure my Powerpack source number pool? ### Add Numbers 1. Navigate to Powerpack 2. Click **Add Numbers** 3. Select from available numbers 4. Add to pool ### Remove Numbers 1. Navigate to Powerpack 2. Select numbers to remove 3. Click **Remove** *** ## What happens if I unrent a Powerpack phone number? The number is removed from the Powerpack. Messages will be sent from remaining numbers in the pool. *** ## Related Resources * [Messaging API Overview](/docs/faq/messaging/messaging-api) * [US Messaging](/docs/faq/messaging/us-messaging) * [Powerpack API Reference](https://www.plivo.com/docs/messaging/api/powerpack/) # Short Codes Source: https://plivo.com/docs/faq/messaging/short-codes Short code provisioning, approval process, and messaging limits Frequently asked questions about short code messaging, application process, and country-specific requirements. *** ## What is a short code? A short code is a 4-6 digit number designed for high-volume messaging. Short codes offer: * Highest throughput (up to 100 MPS in US) * Carrier-approved for A2P and promotional messaging * Bypass carrier content filtering * Easy to remember for customers *** ## Which countries support short codes? | Country | Digits | Types | SMS | MMS | | ------------- | ------ | -------------- | --- | --- | | United States | 5-6 | Random, Vanity | Yes | Yes | | Canada | 5-6 | Random | Yes | No | | Brazil | 5 | Random | Yes | No | | New Zealand | 4 | FTEU, Standard | Yes | No | *** ## What is the throughput for short codes? | Country | SMS Throughput | | ------------- | -------------- | | United States | 100 MPS | | Canada | 10 MPS | | Brazil | Varies | | New Zealand | Varies | *** ## How much do short codes cost? | Country | Setup Fee | Monthly Rental | Procurement Time | | ---------------------- | --------- | -------------- | ---------------- | | United States (Random) | \$1,500 | \$500 | 6-8 weeks | | United States (Vanity) | \$1,500 | \$1,000 | 6-8 weeks | | Canada | \$4,000 | \$700 | 6-8 weeks | | Brazil | \$0 | \$500 | 4 weeks | | New Zealand | \$156 | \$156 | 3-4 weeks | Rental charges are deducted in advance on a quarterly basis. *** ## What is the difference between random and vanity short codes? | Type | Description | Cost | | ------ | ----------------------------------- | --------------------- | | Random | Assigned by CSCA | Lower monthly rental | | Vanity | Custom number (e.g., 75486 = PLIVO) | Higher monthly rental | Vanity short codes are subject to availability and only available in the US. *** ## What are the requirements for US short codes? 1. Update Terms and Conditions page with carrier-required language 2. Ensure web opt-in forms contain mandated verbiage 3. Configure keyword responses (opt-in, opt-out, HELP) 4. Submit application with usage details ### Required Keywords | Keyword | Purpose | Required Response | | -------- | ------- | ------------------------------------ | | STOP | Opt-out | Confirmation of opt-out | | HELP | Help | Program description and contact info | | YES/JOIN | Opt-in | Confirmation of subscription | *** ## What are the requirements for Canada short codes? * Carriers must review use case and campaign details * Shared short codes not supported * Specific language requirements for Terms and Conditions * Same application steps as US *** ## What are the requirements for Brazil short codes? * 5 digits, random only * Messages are Free To End User (FTEU) * Express consent required before sending * 35 days notice required to give up a short code * Unused short codes may be disconnected by regulators ### Content Restrictions (Brazil) | Allowed | Prohibited | | -------------------------------- | ------------------------------- | | Alerts, Marketing, Notifications | Adult content | | OTP, Promotions, Special offers | Gambling/casinos | | Political, Religious | Illegal products, Malware, Spam | *** ## What are the requirements for New Zealand short codes? ### Types | Type | Description | | ----------------------- | ------------------------------- | | Free To End User (FTEU) | All charges to short code owner | | Standard | Recipient may be charged | ### Messaging Requirements For **Standard** short codes: * If expecting a reply: include "standard charges apply" * If message contains URL: include "data charges apply" * If no response needed: add "No Text Reply" *** ## What triggers a short code audit? Carriers in US and Canada conduct audits for: * Deviation from registered use cases * Non-compliant traffic (prohibited content, missing opt-in) * Using same short code for multiple brands (shared short code) Potential outcomes include short code suspension, use case disallowed, or fines. *** ## What qualifies as a shared short code? When a short code registered for one purpose (e.g., account notifications) is used to send messages for another brand. This is prohibited by carriers. *** ## What are the US Short Code Registry updates? Effective October 2024, the registry requires: | Entity | Required Information | | ----------------- | ---------------------------------------------------- | | CSC Registrants | Legal name, entity type, physical address, URL, FEIN | | Content Providers | Point of contact (name, email, phone) | | Brand Clients | Organization details and verification | Brand clients receive a verification email from Aegis Mobile with a link and PIN for completion. *** ## How do short codes renew? * Short codes auto-renew by default * To discontinue: contact Plivo support * Decommissioned short codes cannot be reactivated * Failure to notify results in continued rental charges *** ## Can ISVs use short codes? No. Plivo does not offer short codes for A2P messaging in US or Canada to ISV/Reseller customers. **Alternatives:** * Long codes or toll-free numbers for messaging * [Plivo Verify](/docs/programmable-api/verify/overview) for short code-based OTP delivery *** ## Related Resources * [US Messaging (10DLC, Toll-Free)](/docs/faq/messaging/us-messaging) * [Powerpack](/docs/messaging/concepts/powerpack) * [Short Code API](https://www.plivo.com/docs/messaging/api/) * [Acceptable Use Policy](https://www.plivo.com/aup/) # SMS Source: https://plivo.com/docs/faq/messaging/sms SMS delivery, encoding, concatenation, sender ID, and country-specific rules Frequently asked questions about SMS messaging, character limits, concatenation, and delivery. *** ## What is the character limit for SMS text messages? ### GSM-7 Encoding (Standard Characters) | Message Length | Segments | Characters per Segment | | ------------------- | -------- | ------------------------ | | 1-160 characters | 1 | 160 | | 161-1600 characters | Multiple | 153 (7 chars for header) | **Maximum:** 1,600 characters (splits into \~11 segments) ### Unicode Encoding (Special Characters) | Message Length | Segments | Characters per Segment | | --------------- | -------- | ----------------------- | | 1-70 characters | 1 | 70 | | 71+ characters | Multiple | 67 (3 chars for header) | When any Unicode character appears in your message, the entire message uses UCS-2 encoding. *** ## What is automatic encoding? Automatic encoding replaces Unicode characters with GSM-7 equivalents to prevent accidental segmentation from smart quotes, em dashes, etc. ### Enable Auto-Replace 1. Navigate to **Messaging > Settings > Other Settings** 2. Enable **Auto-replace** *** ## How does SMS concatenation work? Long messages are automatically split and reassembled: 1. Plivo splits message into segments 2. Concatenation header added to each segment 3. Carrier reassembles at delivery 4. Recipient sees single message ### Billing Each segment is billed separately. A 200-character message = 2 segments = 2x SMS cost. *** ## How do I send SMS via API? ### Single Message ```bash theme={null} curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Message/" \ -u "{auth_id}:{auth_token}" \ -H "Content-Type: application/json" \ -d '{ "src": "14151234567", "dst": "14157654321", "text": "Hello from Plivo!" }' ``` ### Can I send bulk SMS? Yes. Send to multiple recipients in one request: ```bash theme={null} curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Message/" \ -u "{auth_id}:{auth_token}" \ -H "Content-Type: application/json" \ -d '{ "src": "14151234567", "dst": "14157654321<14158765432<14159876543", "text": "Bulk message to multiple recipients" }' ``` Separate destinations with `<` character. *** ## How can I receive SMS messages on my Plivo numbers? 1. Create an application with a `message_url` 2. Assign a Plivo number to the application 3. Plivo POSTs inbound messages to your URL *** ## How is an incoming message delivered to my application? | Stage | Description | | --------------- | ----------------------------------------- | | **Received** | Plivo receives from carrier (charged) | | **Delivered** | Successfully posted to your `message_url` | | **Undelivered** | Failed to deliver to your URL | If `message_url` is not configured, messages remain in "received" status. *** ## Can the source number for an outbound text message be a non-Plivo number? ### US and Canada * **Must use Plivo number** as source * Non-Plivo numbers not permitted (telecom regulations) ### International * Dynamic sender IDs may be used * Delivery not guaranteed for non-Plivo numbers * Check [country coverage](https://www.plivo.com/sms/coverage/) for sender ID support *** ## What are Geo-Permissions and why should I use them? Geo-Permissions control which countries can receive your SMS, protecting against fraud. ### Default Enabled Countries * United States * United Kingdom * India ### How Can I Manage Geo-Permissions? 1. Navigate to **Messaging > Settings > [Geo Permissions](https://cx.plivo.com/messaging-settings)** 2. Enable/disable countries as needed 3. Set messages-per-hour fraud thresholds *** ## Can I configure SMS Geo Permissions for each subaccount separately? Yes. By default, subaccounts inherit main account settings. **Override for subaccount:** 1. Go to Geo Permissions 2. Select subaccount from dropdown 3. Customize settings 4. Subaccount shows "Overridden" tag **Remove override:** 1. Select overridden subaccount 2. Click **Remove Override** *** ## Why are my outbound messages failing with error code 450? Error 450 means "destination country barred." The destination country is not enabled in your Geo Permissions. Enable the country in **Messaging > Settings > Geo Permissions**. *** ## What is SMS Pumping and how does Plivo protect against it? SMS pumping is fraud where attackers flood OTP fields with fake requests to premium numbers. ### Protection Features Enabled by default for all accounts: * Automated traffic analysis * Suspicious pattern detection * Alerts for unusual activity ### How to Prevent SMS Pumping Attacks? * Enable [Geo Permissions](#what-are-geo-permissions-and-why-should-i-use-them) * Set rate limits on OTP endpoints * Implement CAPTCHA on forms * Monitor traffic patterns * Use Plivo's fraud detection tools *** ## How to access the message content? Message content is stored for **7 days**. ### View in Console 1. Navigate to **Messaging > Logs** 2. Search by timeframe or UUID 3. View message details **Note:** Only available if data logging is enabled. *** ## Why should I authorize Plivo to view my SMS content? Allow Plivo support to view content for debugging: * Helps identify spam filter triggers * Assists with delivery issues * Enables content policy review *** ## What happens to my outbound messages if I don't have sufficient balance? When balance is insufficient: 1. Messages fail with error code 900 2. API requests fail for 2 minutes with "Insufficient Credit" 3. Queued messages continue to fail until recharged Set up [auto-recharge](/docs/faq/billing-and-invoices/payments) to prevent interruptions. *** ## Why were we charged for an undelivered SMS message? Plivo charges when a message is successfully handed off to downstream carriers. Once accepted by the carrier, Plivo has no control over final delivery. Reasons for undelivered status: * Invalid or unreachable destination number * Carrier filtering * Device issues (phone off, full inbox) *** ## What are the different SMS statuses in Plivo? | Status | Description | | --------------- | ---------------------------------------------------- | | **queued** | Message accepted, waiting to send | | **sent** | Successfully passed to downstream carrier (charged) | | **delivered** | Confirmed delivery to recipient device | | **undelivered** | Carrier could not deliver to recipient | | **failed** | Internal error before reaching carrier (not charged) | *** ## What are the Toll-Free Surcharges? US carriers impose surcharges on toll-free messaging: | Carrier | Surcharge per Segment | | -------- | --------------------- | | Verizon | \$0.0025 | | T-Mobile | Varies | | AT\&T | Varies | Surcharges appear as separate invoice line items. *** ## What is the Number Lookup API? Get information about phone numbers: * Local and E.164 formatting * Carrier information * Caller ID name (CNAM) See [Lookup API documentation](https://www.plivo.com/docs/lookup/). *** ## Related Resources * [Messaging API Overview](/docs/faq/messaging/messaging-api) * [MMS](/docs/faq/messaging/mms) * [US Messaging](/docs/faq/messaging/us-messaging) * [SMS API Reference](https://www.plivo.com/docs/messaging/api/message/) # US Messaging (10DLC, Toll-Free, Short Codes) Source: https://plivo.com/docs/faq/messaging/us-messaging FAQs about US A2P messaging compliance, 10DLC registration, and toll-free verification Frequently asked questions about A2P messaging compliance in the US, including 10DLC registration and toll-free verification. *** ## What is required for A2P messaging in the US? US carriers require registration or verification for A2P (Application-to-Person) messaging: | Number Type | Registration | Throughput | Best For | | -------------- | ---------------- | ------------ | ----------------- | | **10DLC** | Brand + Campaign | 3.75-15+ MPS | General A2P | | **Toll-Free** | Verification | 25 MPS | High volume, 2FA | | **Short Code** | Application | 100+ MPS | Marketing, alerts | *** ## What is 10DLC? 10DLC (10-Digit Long Code) is the standard for A2P messaging on local US numbers. *** ## What is the 10DLC registration process? 1. **Register Brand** - Company information with TCR (The Campaign Registry) 2. **Register Campaign** - Use case and sample messages 3. **Link Numbers** - Associate phone numbers with campaign *** ## How to register a 10DLC brand on the Plivo console? ### Required Information | Field | Description | | ------------------- | ------------------------------ | | Legal business name | Official registered name | | EIN | Employer Identification Number | | Business address | Physical address | | Website | Business website URL | | Vertical | Industry category | *** ## What is Authentication+ for 10DLC Public Brands? Effective October 2024, public for-profit brands must complete Authentication+ verification through TCR. *** ## Why did my brand registration fail, and how can I fix it? | Status | Meaning | Action | | -------- | ------------------------------- | ------------------------- | | Approved | Ready for campaign registration | Proceed | | Failed | Issues with submitted info | Review feedback, resubmit | Review the feedback from TCR and correct the identified issues before resubmitting. *** ## How to register a 10DLC campaign on the Plivo console? ### Campaign Types | Type | Use Cases | | -------------- | --------------------------------- | | **Standard** | Marketing, notifications, alerts | | **Special** | Political, charity, emergency | | **Low Volume** | Mixed use, under 6,000 msgs/month | ### Required Information * Use case description * Sample messages * Opt-in method * Opt-out handling *** ## What is the 10DLC campaign vetting process? Campaigns undergo third-party vetting. Declined campaigns receive feedback for resubmission. *** ## Why was my campaign registration declined, and how can I fix it? Review the feedback from TCR/carrier, correct the identified issues, and resubmit with updated information. *** ## How do I set up 10DLC for multi-brand companies? For companies with multiple brands (e.g., parent company with subsidiaries): * Register each brand separately * Link campaigns to appropriate brand * Maintain consistent legal entity information *** ## How to set up email alerts for your 10DLC submissions? 1. Navigate to **Messaging > 10DLC** 2. Configure notification preferences 3. Receive updates on approvals/rejections *** ## How to link phone numbers with 10DLC campaigns? Associate your phone numbers with registered campaigns through the Plivo console after campaign approval. *** ## How can users opt in to receive messages in the US? ### Supported Opt-In Methods | Method | Description | | ----------------- | ----------------------------------- | | **Web form** | User enters phone number on website | | **Keyword** | User texts keyword to your number | | **Paper form** | Physical sign-up sheet | | **Verbal** | Phone call consent (recorded) | | **Point of sale** | In-person consent at checkout | *** ## What is the Toll-Free Verification Process? 1. Purchase toll-free number 2. Submit verification request 3. Carrier reviews submission 4. Receive approval or rejection feedback *** ## How to submit Toll-free verification on the Plivo console? 1. Navigate to **Messaging > Toll-free Verification** 2. Click **Submit Toll-free Verification** 3. Select profile 4. Complete required fields 5. Submit ### Required Information | Field | Description | | --------------- | ---------------------------- | | Business name | Legal business name | | Business type | Direct brand or ISV/Reseller | | Use case | How you'll use messaging | | Sample messages | Example message content | | Opt-in method | How users consent | | Website | Business website | *** ## Why was my Toll-free verification request rejected, and how can I fix it? | Status | Meaning | Action | | -------- | ----------------- | ------------------------- | | Approved | Ready to send | Begin messaging | | Rejected | Issues identified | Review feedback, resubmit | Review the feedback, provide clear and accurate business information, and resubmit. *** ## What are the best practices for Toll-free verification? * Provide clear, accurate business information * Include realistic sample messages * Document opt-in methods clearly * Respond promptly to carrier inquiries *** ## What about Short Codes? For high-volume messaging, see [Short Codes](/docs/faq/messaging/short-codes) for complete details on: * US, Canada, Brazil, and New Zealand short codes * Application process and requirements * Pricing and throughput * Compliance and audits *** ## What is the throughput comparison for US numbers? | Number Type | Registration Status | SMS Throughput | | ----------- | ------------------- | ---------------------- | | Long Code | Unregistered | 1 MPS, 2,000/day limit | | Long Code | 10DLC Low Volume | 0.2-0.75 MPS | | Long Code | 10DLC Standard | 3.75-15+ MPS | | Toll-Free | Verified | 25 MPS | | Short Code | Approved | 100+ MPS | *** ## What is the throughput for Canada numbers? | Number Type | SMS Throughput | | ----------- | -------------- | | Long Code | 15/minute | | Toll-Free | 25/second | | Short Code | 10/second | *** ## Why are my messages being filtered? * Verify registration is complete * Check message content for spam triggers * Ensure proper opt-in documentation *** ## Why is my throughput low? * Complete 10DLC registration for higher limits * Consider toll-free or short code for high volume *** ## Related Resources * [Messaging API Overview](/docs/faq/messaging/messaging-api) * [SMS](/docs/faq/messaging/sms) * [Short Codes](/docs/faq/messaging/short-codes) * [10DLC Documentation](/docs/messaging/a2p-10dlc/quickstart) * [Toll-Free Verification](/docs/messaging/api/toll-free-verification) # WhatsApp Business API Source: https://plivo.com/docs/faq/messaging/whatsapp WhatsApp Business API setup, templates, pricing, and message types Frequently asked questions about WhatsApp Business messaging, account setup, message types, and integration with Plivo. *** ## What does WhatsApp Business API offer? WhatsApp Business API enables direct customer communication on WhatsApp with: * Real-time messaging * Global reach (2+ billion users) * Rich media support * Message templates * Delivery receipts *** ## What are the key features of WhatsApp Business? | Feature | Description | | ------------------------ | -------------------------------------------------- | | **Business Profile** | Display business info (address, website, email) | | **Message Templates** | Pre-approved messages for initiating conversations | | **Rich Media** | Images, documents, videos, audio | | **Interactive Messages** | Buttons, lists, quick replies | | **Delivery Status** | Real-time delivery and read receipts | *** ## What are the prerequisites for WhatsApp Business API? 1. Meta Business Account 2. Business verification with Meta 3. WhatsApp Business Account (WABA) 4. Phone number for WhatsApp *** ## How do I set up WhatsApp Business with Plivo? 1. **Create WABA**: Through Plivo's embedded signup flow 2. **Verify Business**: Complete Meta business verification 3. **Register Phone Number**: Use existing or rent from Plivo 4. **Configure Display Name**: Set business name for WhatsApp 5. **Create Templates**: Submit templates for approval 6. **Integrate API**: Connect your systems See [WhatsApp concepts](/docs/messaging/concepts/whatsapp/prerequisites) for detailed setup. *** ## What is a WhatsApp Business Account (WABA)? A WhatsApp Business Account contains: * Your phone numbers * Message templates * Business profile * Messaging configuration When onboarding with Plivo, a WABA is created with Plivo as the partner. *** ## Why should I complete Meta business verification? Complete Meta business verification to: * Improve WABA approval chances * Get higher messaging limits * Get higher phone number limits * Display verified business name See [Meta's business verification guide](https://www.facebook.com/business/help/2058515294227817). *** ## What are the phone number requirements for WhatsApp? * Must receive OTP via SMS or voice call * Will be visible to customers on WhatsApp * One number per WhatsApp registration ### Options | Option | Description | | ------------------- | ---------------------------------------- | | **Rent from Plivo** | Use Plivo phone number (where available) | | **Bring your own** | Use existing number | | **Migrate** | Transfer from another provider | *** ## How do I migrate a number from another WhatsApp provider? 1. Request migration through Plivo 2. Follow Meta's migration requirements 3. Number transfers to your new WABA *** ## What is the WhatsApp display name? The business display name appears in: * Chat thread headers * Chat lists * Business profile ### Requirements * Business must complete Meta verification * Display name approved by Meta * Set during embedded signup flow *** ## How do I change my WhatsApp display name? Contact Plivo support to update your display name after initial setup. *** ## What are the WhatsApp message types? ### Template Messages **Required to initiate conversations.** | Template Type | Use Case | | ------------------ | ------------------------------------- | | **Authentication** | OTPs, verification codes | | **Utility** | Order updates, shipping notifications | | **Marketing** | Promotions, offers, announcements | ### Session Messages After customer responds, you have a **24-hour window** to send free-form messages without templates. *** ## What content types are supported in WhatsApp messages? * Text messages * Images * Documents * Videos * Audio * Interactive buttons * List messages *** ## How do message templates work? Templates must be approved by Meta before use. **Status flow:** 1. Submitted → Pending review 2. Approved → Active (Quality pending) 3. Rejected → Edit and resubmit or appeal *** ## How do I create message templates? Templates are created through Meta's WhatsApp Manager: 1. Access [WhatsApp Manager](https://business.facebook.com/wa/manage/) 2. Navigate to Message Templates 3. Create template with required components 4. Submit for approval *** ## What are the template guidelines? * Follow Meta's content policies * Use correct categorization * Include required variables * Avoid prohibited content See [Meta's template guidelines](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/). *** ## How do I view my templates in Plivo? View your templates in the Plivo console: **Messaging > WhatsApp > Templates** *** ## How do I send WhatsApp messages via API? Use Plivo's existing Messaging endpoint: ```bash theme={null} curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Message/" \ -u "{auth_id}:{auth_token}" \ -H "Content-Type: application/json" \ -d '{ "src": "whatsapp:+14151234567", "dst": "whatsapp:+14157654321", "type": "whatsapp", "template": { "name": "your_template_name", "language": "en" } }' ``` *** ## How do I configure webhooks for WhatsApp? Configure webhooks at WABA level: 1. Navigate to WhatsApp settings 2. Set webhook URL 3. Select events to receive 4. Save configuration Webhooks apply to all numbers and templates under the WABA. *** ## What SDKs support WhatsApp integration? Use Plivo's Server SDKs for WhatsApp integration: * Node.js * Python * Ruby * PHP * Java * .NET * Go *** ## How do I view WhatsApp message logs? 1. Navigate to **Messaging > Logs** 2. Filter by WhatsApp messages 3. View delivery status, pricing, destination ### Log Details | Field | Description | | ------------ | ----------------------- | | Message UUID | Unique identifier | | Status | Delivery status | | Destination | Recipient number | | Price | Message cost | | Callbacks | Status updates received | *** ## How do I export WhatsApp logs? Download logs at: * Individual message level * Aggregate by time duration *** ## What if my template is rejected? Review guidelines, edit and resubmit the template. *** ## What if my message is not delivered? Check error code and verify the recipient number. *** ## What if my WABA is not approved? Complete business verification with Meta. *** ## What if number migration fails? Verify all Meta migration requirements are met. *** ## Where can I find error code descriptions? Review [Plivo error codes](https://www.plivo.com/docs/messaging/troubleshooting/) for detailed descriptions and next steps. *** ## How do I get support for WhatsApp issues? 1. Note the message UUID 2. Gather relevant details 3. Contact [Plivo Support](https://support.plivo.com) *** ## Related Resources * [WhatsApp Documentation](https://www.plivo.com/docs/whatsapp/) * [WhatsApp API Reference](/docs/messaging/api/whatsapp-templates) * [Meta Business Help](https://www.facebook.com/business/help/) * [Messaging API Overview](/docs/faq/messaging/messaging-api) # Home Source: https://plivo.com/docs/home Explore Plivo docs for voice, SMS, and SIP trunking API integration.
Plivo Docs

Guides, API references, and quickstarts to integrate, manage, and optimize your Plivo Voice, Messaging, SIP Trunking, and Voice AI.

plivo/docs.console
api.plivo.comv2 · stable
Connect voice AI agents built on platforms like LiveKit, ElevenLabs, and Vapi to the phone network using Plivo SIP trunking Build voice AI agents with frameworks like Pipecat by streaming live call audio over WebSockets Frequently asked questions about Messaging, Account Management, and Billing
# Agno Source: https://plivo.com/docs/integrations/agno Give an Agno AI agent the ability to send SMS, place voice calls, and look up numbers using Plivo tools. [Agno](https://github.com/agno-agi/agno) is an open-source framework for building AI agents. Plivo ships as a built-in toolkit in Agno, so an agent can send SMS, place voice calls, and look up phone numbers by calling Plivo APIs as tools. The agent's model decides when to use each tool, so you add the capability once and let the agent choose when to reach a person. This is a tool-use integration over Plivo REST APIs. ## Prerequisites | Requirement | Description | | -------------- | -------------------------------------------------------------------------- | | Plivo account | Your Auth ID and Auth Token from the [Plivo console](https://cx.plivo.com) | | Plivo number | An SMS-enabled number on your account to send from and call from | | Python | 3.11 or newer | | Model provider | An OpenAI API key | | Answer URL | A hosted answer URL that returns Plivo XML for outbound calls | ## Quick start Start with the runnable examples repository, then adapt the pattern to your own agent. ```bash theme={null} git clone https://github.com/plivo-dev/agno-plivo-examples.git cd agno-plivo-examples uv sync cp .env.example .env ``` Set your credentials in `.env`: ```bash theme={null} OPENAI_API_KEY=your-openai-key PLIVO_AUTH_ID=your-auth-id PLIVO_AUTH_TOKEN=your-auth-token PLIVO_FROM_NUMBER=your-plivo-number PLIVO_TO_NUMBER=destination-number PLIVO_ANSWER_URL=https://your-app.example.com/answer.xml ``` Run the featured example: ```bash theme={null} uv run python examples/on_call_alerting.py ``` For call-capable examples, `PLIVO_ANSWER_URL` should point to an endpoint that returns valid Plivo XML. If you want the smallest possible inline example, create an agent and give it the Plivo tools: ```python theme={null} import os from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.tools.plivo import PlivoTools agent = Agent( model=OpenAIChat(id="gpt-4o"), tools=[PlivoTools()], instructions=[ "Use Plivo to send SMS, place calls, and look up phone numbers.", f"When placing a call, use caller ID {os.environ['PLIVO_FROM_NUMBER']} ", f"and answer URL {os.environ['PLIVO_ANSWER_URL']} served over GET.", ], markdown=True, ) agent.print_response( "Send an SMS from +14150000001 to +14150000002 saying the deploy is done." ) ``` The agent calls `send_sms` and returns the Plivo message ID. For outbound calls, keep the caller ID and answer URL in config and let the per-call prompt express only intent: ```python theme={null} agent.print_response("Call +14150000002 and remind them about the 3pm meeting.") ``` This works with the toolkit as it exists today. The model fills `make_call` from the configured instructions, while `PLIVO_ANSWER_URL` stays in env instead of being pasted into every call prompt. The sender must be an SMS-enabled Plivo number on your account. For calls, the caller ID must be a voice-enabled Plivo number in E.164. ## Available tools `PlivoTools` registers these tools. The agent picks the right one from your instruction. | Tool | What it does | | ------------------ | ------------------------------------------------------------------ | | `send_sms` | Send an SMS from a Plivo number to a recipient | | `make_call` | Place an outbound call that runs answer XML from a URL you provide | | `lookup_number` | Look up the country, carrier, and line type of a number | | `list_messages` | List recent messages on the account | | `list_calls` | List recent calls on the account | | `get_call_details` | Fetch the details of a single call | For `make_call`, pass an `answer_url` that returns Plivo XML, and set `answer_method` to match how that URL is served. ## Register a subset of tools Turn individual tools on or off with the `enable_*` flags. ```python theme={null} PlivoTools(enable_send_sms=True, enable_make_call=True, enable_lookup_number=False) ``` ## Troubleshooting | Issue | Solution | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `authentication failed` | Confirm `PLIVO_AUTH_ID` and `PLIVO_AUTH_TOKEN` are set to the values from the [Plivo console](https://cx.plivo.com). | | SMS not delivered | Confirm the sender is an SMS-enabled Plivo number and that the destination country is supported for that number. | | Agent does not call a tool | Make the instruction explicit and confirm the tool is enabled. | | `make_call` connects but plays nothing | The `answer_url` must return valid Plivo XML, and `answer_method` must match how the URL is served. | ## Related Clone-and-run Agno agents built on the Plivo tools. The Plivo tools example in the Agno cookbook. Agno's reference for the Plivo toolkit. Send an SMS with the Plivo API. Make a call with the Plivo API. Look up carrier and line-type details for a number. # Acitvatec custom SMS factor Source: https://plivo.com/docs/integrations/auth0/activate-custom-sms-factor Activate custom SMS as an MFA factor in Auth0 using Plivo Before you can use SMS as an authentication factor, your Auth0 tenant needs to have [MFA enabled globally](https://auth0.com/docs/login/mfa/enable-mfa) or [for specific contexts](https://auth0.com/docs/login/mfa/customize-mfa-user-pages). You can then configure the SMS factor to use your custom code. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/select-tenant?path=/mfa) and click the Phone Message factor box. In the modal that appears, select Custom for the delivery provider, make any adjustments you’d like to the templates, then click Save and close the modal. Finally, enable the SMS factor using the toggle switch. Auth0 will immediately begin using this factor for MFA during login. Before you activate your integration in production, make sure you’ve configured all of the components correctly and verified everything on a [test tenant](https://auth0.com/docs/dev-lifecycle/set-up-multiple-environments). # Add the Action Source: https://plivo.com/docs/integrations/auth0/add-the-action Add a Plivo SMS Action to your Auth0 authentication flow To integrate Auth0, first [sign up](https://auth0.com/signup) for an account. Add an [Action](https://auth0.com/docs/actions) (a triggerable function), then integrate it with your authentication flow. * Go to Actions > Library and select Add Integration. * Read the necessary access requirements and click **Continue**. * Configure the integration by filling in the fields on the next screen with your Plivo Auth ID and Auth Token and your Plivo phone number. * Click **Create** to add the integration to your library. * Click the **Add to flow** link on the pop-up that appears. * Drag the Action into the flow. * Click Apply Changes. Now this flow will use the Plivo integration to send an SMS message whenever it’s called. # Auth0 Source: https://plivo.com/docs/integrations/auth0/overview Integrate Plivo SMS with Auth0 for multi-factor authentication [Auth0](https://auth0.com/) solves the most complex and large-scale identity use cases for global enterprises with their extensible and easy-to-integrate platform, securing billions of logins every year. Using Plivo’s Messaging platform and Auth0 you can send SMS messages to send multi-factor verification codes via text messages. This integration will add SMS-based MFA to the login flow for the tenant in which you’re working. # Prerequisites Source: https://plivo.com/docs/integrations/auth0/prerequisites Requirements for setting up Plivo SMS with Auth0 MFA To start using Plivo with Auth0, you’ll need 1. Make sure you have an [Auth0 account](https://auth0.com/signup) and **tenant**. 2. Your **Plivo Auth ID and Auth Token**: You can find your Plivo Auth ID and Auth Token on the overview page of the [Plivo console](https://cx.plivo.com/home). 3. **A Plivo number** *(optional)*: You must have an SMS-enabled Plivo phone number to send SMS messages to numbers in the US and Canada. Purchase numbers from the [Phone Numbers](https://cx.plivo.com/phone-numbers) page of the Plivo console, or by using the [PhoneNumber API](/docs/numbers). Plivo provides an SMS messaging service that Auth0 can use to deliver multi-factor verification via SMS messages. The following steps will enable you to add SMS-based MFA via the Plivo SMS API to the login flow for the tenant in which you’re working. The following steps will add text-message-based MFA to the login flow for the tenant in which you're working. We highly recommend testing this setup on a [staging or development server](https://auth0.com/docs/dev-lifecycle/set-up-multiple-environments) before making the changes to your production login flow. # Set up plivo Source: https://plivo.com/docs/integrations/auth0/set-up-plivo Configure Plivo credentials for the Auth0 SMS integration Capture the authorization ID and authorization token from the Account and Payments section in the [Plivo console](https://cx.plivo.com/home). # Test MFA flow Source: https://plivo.com/docs/integrations/auth0/test-mfa-flow Verify your Plivo SMS MFA integration works in Auth0 Navigate to the Authentication section in the Auth0 Manage Dashboard, choose your Connection, then select **Try** from the connection’s dropdown menu to verify that everything works as intended. You can then log into your Plivo account to verify that SMS messages are indeed being sent. If you don’t receive an SMS message as expected, look in your [tenant logs](https://auth0.com/docs/logs) for a failed Phone Message log entry. To learn which event types to search, see the [Log Event Type Code list](https://auth0.com/docs/logs/log-event-type-codes). You can use the Filter control to find MFA errors. Make sure that: * The Action is in the Send Phone Message flow. * The secrets are the same Plivo Auth ID and Auth Token you created when you added the Action. * Your Plivo account is active (not suspended). * Your phone number is formatted in [E.164 format](https://en.wikipedia.org/wiki/E.164). # Make calls using Plivo Source: https://plivo.com/docs/integrations/engagebay/make-calls-using-plivo Place voice calls to EngageBay contacts using Plivo To make a call, navigate to the contact you want to call to. Under the phone number in the left pane click **Call**, then select Plivo from the drop-down menu. You’ll be asked to choose one of the Plivo numbers as the caller ID for the call. Once you select the phone number, EngageBay will call the contact’s phone number using Plivo as the voice provider in the background. # Overview Source: https://plivo.com/docs/integrations/engagebay/overview Connect Plivo with EngageBay for SMS and voice in your CRM [EngageBay](https://www.engagebay.com/) is an affordable all-in-one marketing, sales, and support CRM platform for small businesses. By integrating Plivo with EngageBay you can send SMS messages and make calls to your EngageBay contacts. To use Plivo with EngageBay, you’ll need an [EngageBay account](https://app.engagebay.com/signup) and a voice- and SMS-enabled Plivo phone number. You can purchase numbers from the [Phone Numbers](https://cx.plivo.com/phone-numbers) page of the Plivo console, or by using the [PhoneNumber API](/docs/numbers). # Send SMS messages using Plivo Source: https://plivo.com/docs/integrations/engagebay/send-sms-messages-using-plivo Send text messages to EngageBay contacts using Plivo SMS To send a text message, navigate to the contact you want to send a message to. Under the phone number in the left pane click **SMS**, then select Plivo from the drop-down menu. A pop-up appears that prompts for the From number and message text you want to use. Fill in the details, then click **Send**. EngageBay will send the message to the contact’s phone number using Plivo as the SMS provider in the background. # Set up Plivo in EngageBay Source: https://plivo.com/docs/integrations/engagebay/set-up-plivo-in-engagebay Configure your Plivo credentials in the EngageBay dashboard To get started, log in to the EngageBay dashboard, click on the Profile drop-down at the top right, then Preferences > Gadgets > Plivo (click **Enable**). Enter your Plivo Auth ID and Auth Token, which you can find on the overview page of the [Plivo console](https://cx.plivo.com/home), and click **Validate**. Once you validate your credentials, the next screen will prompt you to choose the Plivo phone numbers you want to enable on EngageBay. Choose the options you want and click **Save**. Now you can use your Plivo number within EngageBay to send SMS messages and make voice calls. # Configuring credentials Source: https://plivo.com/docs/integrations/github-actions/configuring-credentials Store Plivo auth credentials securely in GitHub Secrets You also need to know your Plivo Auth ID and Auth Token, which you can find on the overview screen of the [Plivo console](https://cx.plivo.com/home). But you don’t want to put your authentication credentials or other private information into your YAML file. If you’re working in a public repository, the YAML file is exposed to everyone, so your secrets would be exposed too. Fortunately, [GitHub](https://docs.github.com/en/actions/reference/encrypted-secrets) has a way to keep this information secret. Go to your repository’s settings and select Secrets from the left menu bar.