# 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 REST API requests to your Plivo account. * **When:** Use it to limit API access to your known server IPs — inbound traffic (your servers → Plivo API). 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:** Isolated environments under your main Plivo account, each with its own Auth ID/Token, logs, and webhooks. * **When:** Use for multi-tenant SaaS, resellers, or dev/staging/production separation. All billing rolls up to the parent account. 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) # Using the CLI from an AI coding agent Source: https://plivo.com/docs/cli/agents Give Claude Code, Cursor, Codex, or any agent a reliable way to drive Plivo. The CLI is designed to be operated by AI coding agents: stable JSON in and out, one error shape, exit codes to branch on, `--dry-run` to preview, and a hard `--yes` gate on anything that spends money. The local tools are covered too: `streams test`, `streams forward` and `upgrade` honour `-o json` and send their progress output to stderr, so stdout stays parseable. ## Install the skill `plivo skill install` writes a single reference file (`SKILL.md`) that agents load automatically. It documents every command, the JSON and error envelopes, the exit codes, headless auth, and the safety rules: without a network call, from the copy embedded in the binary. ```bash theme={null} plivo skill install # → ~/.claude/skills/plivo-cli/SKILL.md (Claude Code) plivo skill install --dir ./.cursor/skills/plivo-cli plivo skill install --print # write to stdout for any other tool ``` ## Headless authentication Agents can't complete a browser login. Set `PLIVO_AUTH_ID` and `PLIVO_AUTH_TOKEN` in the environment instead, see [Using API credentials](/docs/cli/authenticate#use-api-credentials-ci-and-agents), plus `PLIVO_FEEDBACK_PROMPT=0` and `CI=1` to suppress interactive prompts. ## Rules of the road for agents * Always pass `-o json`; parse `data` on success and `error.code` on failure. * Never pass `--yes` unless the human asked for the spend or deletion. Use `--dry-run` to show what would happen. * `plivo --help` is the source of truth for flags. Do not invent flag names. * Use [`plivo ask`](/docs/cli/apis/diagnose-ask#ask-a-question) for how-to questions and [`plivo diagnose`](/docs/cli/apis/diagnose-ask#diagnose-a-call-or-message) for a failed call or message; both are rate-limited per account. * `plivo docs search `, `plivo docs list` and `plivo docs show ` read the documentation with no credentials, so an agent can look something up before it has any. See [Read the docs from your terminal](/docs/cli/docs). # Account, Verify and Lookup Source: https://plivo.com/docs/cli/apis/account Account details and balance, subaccounts, OTP verification sessions, and carrier lookup. Applications (the webhook URLs a number points at) are documented under [Connect a number](/docs/cli/voice-agent/connect-number). ## Account Inspect the active account, its balance, and settings. Inspect and update the active Plivo account | Command | What it does | | ---------------------- | ---------------------------------------------------------- | | `plivo account get` | Get account details (name, billing mode, credits, address) | | `plivo account update` | Update account profile fields | **Command:** ```bash theme={null} plivo account get ``` **Command:** ```bash theme={null} plivo account update [flags] ``` **Flags** * `--address `: billing address * `--city `: city * `--name `: account name * `--timezone `: IANA timezone (e.g. Asia/Kolkata) ## Subaccounts Create, list, update, and delete subaccounts. Manage subaccounts under the master account | Command | What it does | | ---------------------------------- | ------------------------------------ | | `plivo account subaccounts create` | Create a subaccount | | `plivo account subaccounts delete` | Delete a subaccount (requires --yes) | | `plivo account subaccounts get` | Get a subaccount by auth\_id | | `plivo account subaccounts list` | List subaccounts | | `plivo account subaccounts update` | Update a subaccount | **Command:** ```bash theme={null} plivo account subaccounts create [flags] ``` **Flags** * `--enabled`: enable on creation (default true) * `--name `: subaccount name (required) **Command:** ```bash theme={null} plivo account subaccounts delete ``` **Command:** ```bash theme={null} plivo account subaccounts get ``` **Command:** ```bash theme={null} plivo account subaccounts list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo account subaccounts update [flags] ``` **Flags** * `--enabled `: true|false * `--name `: new name ## Verify Create OTP sessions and check their status. Requires the Verify service to be enabled on the account. Plivo Verify: OTP / phone-number verification sessions Manage Verify sessions | Command | What it does | | -------------------------------- | ------------------------------------------------------ | | `plivo verify sessions create` | Create a Verify session (spends money: requires --yes) | | `plivo verify sessions get` | Get a Verify session by uuid | | `plivo verify sessions list` | List Verify sessions | | `plivo verify sessions validate` | Submit the OTP to validate a session | **Command:** ```bash theme={null} plivo verify sessions create [flags] ``` **Flags** * `--alpha-sender `: alphanumeric sender id * `--app-uuid `: Verify application uuid (required) * `--channel `: delivery channel: sms|voice|whatsapp (default "sms") * `--locale `: BCP-47 locale, e.g. en-US * `--method `: HTTP method for callback URL * `--recipient `: E.164 destination number (required) * `--url `: callback URL for session status events **Command:** ```bash theme={null} plivo verify sessions get ``` **Command:** ```bash theme={null} plivo verify sessions list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--status `: filter by status: pending|verified|expired **Command:** ```bash theme={null} plivo verify sessions validate [flags] ``` **Flags** * `--otp `: OTP code received by the recipient (required) ## Lookup Look up the carrier, number type, and formatting for an E.164 number. | Command | What it does | | -------------- | -------------------------------------------------------------- | | `plivo lookup` | Carrier + format lookup for an E.164 number (lookup.plivo.com) | **Command:** ```bash theme={null} plivo lookup [flags] ``` **Flags** * `--type `: lookup type (currently only 'carrier' is supported by Plivo) (default "carrier") # Any REST endpoint Source: https://plivo.com/docs/cli/apis/api Call any Plivo REST endpoint the CLI does not wrap yet. ## plivo api For any endpoint the CLI doesn't yet have a command for. Uses your profile or environment credentials, supports `--dry-run`, returns the same JSON and error envelopes, and requires `--yes` for `POST`, `PUT`, `PATCH`, and `DELETE`. Account-scoped paths can be given relative to `/v1/Account//`. ```bash theme={null} plivo api GET /Number/ --query limit=5 plivo api GET /v1/Account//Zentrunk/Trunk/ plivo api POST /Message/ --body @msg.json --yes ``` | Command | What it does | | ----------- | ------------------------------------------------------------------------ | | `plivo api` | Generic REST escape hatch: hit any Plivo API path that isn't yet wrapped | **Command:** ```bash theme={null} plivo api [flags] ``` **Flags** * `--body `: request body: literal JSON, @path/to/file, or @- for stdin * `--header `: extra header as 'Key: Value' (repeatable; overrides defaults) * `--method `: HTTP method (alternative to the positional arg; useful when piping) * `--query `: query param as key=value (repeatable) # Diagnose and ask Source: https://plivo.com/docs/cli/apis/diagnose-ask Explain why any call or message failed, or ask Plivo's assistant a question, from the terminal. These work for every product, not just voice agents. `diagnose` reads the records of a call or message on your account and explains what happened; `ask` answers questions about Plivo in plain English. To read the documentation itself from the terminal, see [Read the docs from your terminal](/docs/cli/docs). ## Diagnose a call or message Give the CLI a call or message UUID and it explains what happened: whose side failed (your server, Plivo, the carrier), the timeline, and what to do next. It reads Plivo's call and message records and carrier reports for you. **Commands** ```bash theme={null} plivo voice calls diagnose plivo messaging sms diagnose plivo messaging mms diagnose plivo messaging whatsapp diagnose ``` **Examples** ```bash theme={null} plivo voice calls list --limit 5 plivo voice calls diagnose 58dcee4c-969d-4a5d-a732-cf50573e8d8c ``` A typical answer for a failed inbound call: ```text theme={null} What happened: This inbound call was terminated because Plivo could not fetch call instructions from your answer URL. Likely cause: The answer URL https://api.example.com/plivo/answer returned 404. The call was hung up with cause 7011 (Error Reaching Answer URL). Timeline: 07:48:40.600 call received · 07:48:40.630 answer URL responded 404 · 07:48:41.016 call hung up Suggested next step: Make sure the answer URL is deployed and returns Plivo XML with HTTP 200; every inbound call will fail until it does. ``` Use `-o json` to receive the analysis as a stream of events. Answers usually take about a minute (allow 30 to 120 seconds) and are written by the AI assistant, so read them as an explanation rather than parsing them as a fixed schema; only calls and messages on your own account can be diagnosed. ## Ask a question Ask Plivo's AI assistant a question without leaving the terminal. The assistant searches the Plivo documentation, reads the relevant pages, and streams an answer with source links. **Command:** `plivo ask ""` **Flags** * `-i, --interactive`: start a chat session that keeps context between turns (`/reset`, `/help`, `/exit`). Use `-o table` when input is piped. * `-o json`: emit the answer as one JSON event per line (start, tool\_call, tool\_output, token, final), for scripts and agents. **Examples** ```bash theme={null} plivo ask "What hangup cause does Plivo return when the callee is busy?" plivo ask "Do I need 10DLC registration to send SMS to US numbers?" -o json plivo ask -i ``` `ask` and `diagnose` share a rate limit per account. If you see `RATE_LIMITED`, wait for the retry interval shown in the error. #### `plivo support` List the support escalations raised from your account through the assistant. Requires a browser login (`plivo login`), because escalations are scoped to the person who raised them. # Messaging Source: https://plivo.com/docs/cli/apis/messaging Send and list SMS, MMS and WhatsApp messages; manage 10DLC and Powerpacks. Sending spends money, so `send` commands need `--yes`; `--dry-run` shows the request without sending. ## SMS Send SMS (requires `--yes`; `--dry-run` previews), list and fetch messages, and manage US 10DLC brands, campaigns, and number links, and Powerpacks. SMS: A2P / P2P short-message-service (incl. 10DLC, powerpacks, toll-free) | Command | What it does | | ----------------------------------------------- | ------------------------------------------------------------------------- | | `plivo messaging sms 10dlc` | US A2P 10DLC registration: brands, campaigns, links | | `plivo messaging sms list` | List SMS messages | | `plivo messaging sms powerpacks` | Powerpacks: number pools for high-volume SMS | | `plivo messaging sms send` | Send an SMS (requires --yes; spends money: use --dry-run to preview) | | `plivo messaging sms tollfree` | Toll-free verification (US TFN messaging compliance) | | `plivo messaging sms 10dlc brands` | 10DLC brand registration (US A2P 10-digit-long-code messaging) | | `plivo messaging sms 10dlc campaigns` | 10DLC campaign registration (use cases for a brand) | | `plivo messaging sms 10dlc links` | 10DLC number-to-campaign linking | | `plivo messaging sms powerpacks create` | Create a powerpack | | `plivo messaging sms powerpacks delete` | Delete a powerpack (requires --yes) | | `plivo messaging sms powerpacks get` | Get a powerpack by uuid | | `plivo messaging sms powerpacks list` | List powerpacks | | `plivo messaging sms powerpacks numbers` | Manage numbers inside a powerpack | | `plivo messaging sms powerpacks update` | Update a powerpack | | `plivo messaging sms tollfree get` | Get a toll-free verification profile by uuid | | `plivo messaging sms tollfree list` | List toll-free verification profiles | | `plivo messaging sms tollfree submit` | Submit a new toll-free verification profile | | `plivo messaging sms 10dlc brands create` | Register a new brand (spends money. TCR registration fee, requires --yes) | | `plivo messaging sms 10dlc brands get` | Get a brand by ID | | `plivo messaging sms 10dlc brands list` | List registered brands | | `plivo messaging sms 10dlc brands update` | Update mutable brand fields | | `plivo messaging sms 10dlc campaigns create` | Register a new campaign (spends money. TCR fee, requires --yes) | | `plivo messaging sms 10dlc campaigns get` | Get a campaign by ID | | `plivo messaging sms 10dlc campaigns list` | List campaigns | | `plivo messaging sms 10dlc campaigns update` | Update mutable campaign fields | | `plivo messaging sms 10dlc links create` | Link a number to a campaign | | `plivo messaging sms 10dlc links delete` | Unlink a number (requires --yes) | | `plivo messaging sms 10dlc links list` | List number→campaign links | | `plivo messaging sms powerpacks numbers add` | Add a number to a powerpack | | `plivo messaging sms powerpacks numbers list` | List numbers attached to a powerpack | | `plivo messaging sms powerpacks numbers remove` | Remove a number from a powerpack (requires --yes) | **Command:** ```bash theme={null} plivo messaging sms 10dlc ``` **Command:** ```bash theme={null} plivo messaging sms list [flags] ``` **Flags** * `--direction `: inbound|outbound * `--from `: filter by from\_number * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--state `: queued|sent|delivered|undelivered|failed|received * `--to `: filter by to\_number **Command:** ```bash theme={null} plivo messaging sms powerpacks ``` **Command:** ```bash theme={null} plivo messaging sms send [flags] ``` **Flags** * `--dst `: destination, separate multiple with \< (required) * `--method `: callback method GET|POST (default "POST") * `--src `: sender (E.164, shortcode, or sender ID) (required) * `--text `: message body (required) * `--url `: callback URL for delivery status **Command:** ```bash theme={null} plivo messaging sms tollfree ``` **Command:** ```bash theme={null} plivo messaging sms 10dlc brands ``` **Command:** ```bash theme={null} plivo messaging sms 10dlc campaigns ``` **Command:** ```bash theme={null} plivo messaging sms 10dlc links ``` **Command:** ```bash theme={null} plivo messaging sms powerpacks create [flags] ``` **Flags** * `--application-id `: application uuid (when application-type=xml\_application) * `--application-type `: default\_message|xml\_application * `--local-connect`: use a local-prefix-matching number * `--name `: powerpack name (required) * `--number-priority `: ordered priority list (e.g. "local,tollfree") * `--sticky-sender`: send from same number to same recipient **Command:** ```bash theme={null} plivo messaging sms powerpacks delete ``` **Command:** ```bash theme={null} plivo messaging sms powerpacks get ``` **Command:** ```bash theme={null} plivo messaging sms powerpacks list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo messaging sms powerpacks numbers ``` **Command:** ```bash theme={null} plivo messaging sms powerpacks update [flags] ``` **Flags** * `--local-connect `: true|false * `--name `: new name * `--sticky-sender `: true|false **Command:** ```bash theme={null} plivo messaging sms tollfree get ``` **Command:** ```bash theme={null} plivo messaging sms tollfree list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--status `: filter by status: SUBMITTED|IN\_REVIEW|APPROVED|REJECTED **Command:** ```bash theme={null} plivo messaging sms tollfree submit [flags] ``` **Flags** * `--business-name `: business name (required) * `--business-website `: business website URL * `--message-volume `: expected volume: LOW|MEDIUM|HIGH * `--numbers `: comma-separated toll-free numbers to verify * `--opt-in-workflow `: describe how recipients opt in * `--production-message-content `: sample message content * `--use-case `: use case category (required) * `--use-case-summary `: free-text use case summary **Command:** ```bash theme={null} plivo messaging sms 10dlc brands create [flags] ``` **Flags** * `--alias `: human-friendly alias (required) * `--brand-type `: STANDARD|LOW\_VOLUME\_STANDARD|SOLE\_PROPRIETOR (default "STANDARD") * `--ein `: tax ID / EIN * `--ein-issuing-country `: ISO-2 country issuing the EIN (default "US") * `--email `: support email * `--entity-type `: PRIVATE\_PROFIT|PUBLIC\_PROFIT|NON\_PROFIT|GOVERNMENT|SOLE\_PROPRIETOR (default "PRIVATE\_PROFIT") * `--legal-name `: legal entity name (required) * `--phone `: support phone E.164 * `--stock-exchange `: exchange code (PUBLIC\_PROFIT only) * `--stock-symbol `: ticker (PUBLIC\_PROFIT only) * `--vertical `: industry vertical (e.g. TECHNOLOGY, RETAIL) * `--website `: primary website URL **Command:** ```bash theme={null} plivo messaging sms 10dlc brands get ``` **Command:** ```bash theme={null} plivo messaging sms 10dlc brands list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo messaging sms 10dlc brands update [flags] ``` **Flags** * `--email `: support email * `--phone `: support phone * `--website `: website URL **Command:** ```bash theme={null} plivo messaging sms 10dlc campaigns create [flags] ``` **Flags** * `--affiliate-marketing`: affiliate marketing campaign * `--age-gated`: campaign targets adult content * `--alias `: human-friendly alias (required) * `--brand-id `: brand to register under (required) * `--description `: what this campaign does (required) * `--direct-lending`: direct-lending arrangements * `--embedded-link`: messages contain links * `--embedded-phone`: messages contain phone numbers * `--help-keywords `: comma-separated help keywords (default "HELP") * `--help-message `: auto-reply to HELP * `--message-flow `: describe how recipients opt in (required) * `--number-pool`: campaign uses a number pool * `--opt-in-keywords `: opt-in keywords (default "START") * `--opt-in-message `: opt-in confirmation message * `--opt-out-keywords `: opt-out keywords (default "STOP") * `--opt-out-message `: opt-out confirmation message * `--sample-message-1 `: sample message (required) * `--sample-message-2 `: second sample message * `--sub-usecases `: comma-separated sub use cases * `--usecase `: primary use case, e.g. MARKETING, MIXED (required) **Command:** ```bash theme={null} plivo messaging sms 10dlc campaigns get ``` **Command:** ```bash theme={null} plivo messaging sms 10dlc campaigns list [flags] ``` **Flags** * `--brand-id `: filter by brand\_id * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo messaging sms 10dlc campaigns update [flags] ``` **Flags** * `--description `: new description * `--message-flow `: new message flow * `--sample-message-1 `: new sample 1 * `--sample-message-2 `: new sample 2 **Command:** ```bash theme={null} plivo messaging sms 10dlc links create [flags] ``` **Flags** * `--campaign-id `: 10DLC campaign id (required) * `--number `: E.164 number (required) **Command:** ```bash theme={null} plivo messaging sms 10dlc links delete ``` **Command:** ```bash theme={null} plivo messaging sms 10dlc links list [flags] ``` **Flags** * `--campaign-id `: filter by campaign\_id * `--limit `: results per page (default 20) * `--number `: filter by number * `--offset `: pagination offset **Command:** ```bash theme={null} plivo messaging sms powerpacks numbers add ``` **Command:** ```bash theme={null} plivo messaging sms powerpacks numbers list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo messaging sms powerpacks numbers remove ``` ## MMS Send MMS with one or more `--media-url` attachments (requires `--yes`), and list or fetch messages. MMS: multimedia messages (US/Canada) | Command | What it does | | -------------------------- | -------------------------------------------------------------------- | | `plivo messaging mms list` | List MMS messages | | `plivo messaging mms send` | Send an MMS (requires --yes; spends money: use --dry-run to preview) | **Command:** ```bash theme={null} plivo messaging mms list [flags] ``` **Flags** * `--direction `: inbound|outbound * `--from `: filter by from\_number * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--state `: queued|sent|delivered|undelivered|failed|received * `--to `: filter by to\_number **Command:** ```bash theme={null} plivo messaging mms send [flags] ``` **Flags** * `--dst `: destination, separate multiple with \< (required) * `--media-url `: URL of a hosted image/media file to attach (repeatable, up to 10) * `--method `: callback method GET|POST (default "POST") * `--src `: sender (E.164, shortcode, or sender ID) (required) * `--text `: message body (required) * `--url `: callback URL for delivery status ## WhatsApp Send WhatsApp messages (requires `--yes`) and list or fetch them. WhatsApp: Plivo's WhatsApp Business API surface | Command | What it does | | ------------------------------- | -------------------------------------------------------------------------------- | | `plivo messaging whatsapp list` | List WhatsApp messages | | `plivo messaging whatsapp send` | Send a WhatsApp message (requires --yes; spends money: use --dry-run to preview) | **Command:** ```bash theme={null} plivo messaging whatsapp list [flags] ``` **Flags** * `--direction `: inbound|outbound * `--from `: filter by from\_number * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--state `: queued|sent|delivered|undelivered|failed|received * `--to `: filter by to\_number **Command:** ```bash theme={null} plivo messaging whatsapp send [flags] ``` **Flags** * `--dst `: destination, separate multiple with \< (required) * `--method `: callback method GET|POST (default "POST") * `--src `: sender (E.164, shortcode, or sender ID) (required) * `--text `: message body (required) * `--url `: callback URL for delivery status ## Get any message Fetch a single message regardless of channel. | Command | What it does | | --------------------- | -------------------------------------------------------- | | `plivo messaging get` | Get a message by UUID (works for SMS, MMS, and WhatsApp) | **Command:** ```bash theme={null} plivo messaging get ``` # Numbers Source: https://plivo.com/docs/cli/apis/numbers Search, buy, attach and release phone numbers; compliance applications (including India KYC); number masking. Buying a number spends money and needs `--yes`. In India a number can only be rented (and used for calls) once a compliance application is `accepted`; see the compliance commands below. ## Phone numbers Search available numbers, buy one (requires `--yes`), attach it to an application, set CNAM, or release it. Manage account phone numbers | Command | What it does | | ----------------------- | ------------------------------------------------------------------------------ | | `plivo numbers buy` | Rent a phone number (requires --yes; spends money) | | `plivo numbers cnam` | Caller-ID Name (CNAM) lookup for a US/CA number (spends money: requires --yes) | | `plivo numbers get` | Get details of a rented number | | `plivo numbers list` | List numbers rented to your account | | `plivo numbers release` | Release a rented number (requires --yes; stops monthly billing) | | `plivo numbers search` | Search available numbers to rent | | `plivo numbers update` | Update settings on a rented number | **Command:** ```bash theme={null} plivo numbers buy [flags] ``` **Flags** * `--app-id `: auto-attach to this application after purchase **Command:** ```bash theme={null} plivo numbers cnam ``` **Command:** ```bash theme={null} plivo numbers get ``` **Command:** ```bash theme={null} plivo numbers list [flags] ``` **Flags** * `--alias `: filter by alias * `--limit `: results per page (max 20) (default 20) * `--offset `: pagination offset * `--services `: filter by services: voice|sms|mms|voice,sms ... * `--starts-with `: prefix filter on E.164 * `--subaccount `: filter by subaccount auth\_id * `--type `: filter by type: local|tollfree|mobile|fixed **Command:** ```bash theme={null} plivo numbers release ``` **Command:** ```bash theme={null} plivo numbers search [flags] ``` **Flags** * `--country `: ISO country code, e.g. US (required) * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--pattern `: digit pattern * `--region `: region filter * `--type `: local|tollfree|mobile|fixed **Command:** ```bash theme={null} plivo numbers update [flags] ``` **Flags** * `--alias `: set alias * `--app-id `: associate an application * `--subaccount `: move under subaccount ## Number compliance Look up what documents a country and number type require, create and manage compliance applications (with document upload), and link numbers to them. Regulatory compliance for phone numbers (requirements, applications, linking) | Command | What it does | | --------------------------------------- | -------------------------------------------------------------------- | | `plivo numbers compliance create` | Create + submit a compliance application (multipart; auto-submits) | | `plivo numbers compliance delete` | Delete a compliance application (requires --yes) | | `plivo numbers compliance get` | Get a compliance application by ID | | `plivo numbers compliance link` | Bulk-link numbers to accepted compliance applications | | `plivo numbers compliance list` | List compliance applications | | `plivo numbers compliance requirements` | List documents/fields required to activate a regulated number | | `plivo numbers compliance update` | Update a rejected compliance application (multipart; auto-resubmits) | **Command:** ```bash theme={null} plivo numbers compliance create [flags] ``` **Flags** * `--data `: application JSON; inline or @file.json (required) * `--file `: document upload as field=path, e.g. documents\[0].file=@id.pdf (repeatable) **Examples** ```bash theme={null} plivo numbers compliance create \ --data @app.json \ --file documents[0].file=@passport.pdf \ --file documents[1].file=@address-proof.pdf ``` **Command:** ```bash theme={null} plivo numbers compliance delete ``` **Command:** ```bash theme={null} plivo numbers compliance get [flags] ``` **Flags** * `--expand `: comma-separated: end\_user,documents,linked\_numbers **Examples** ```bash theme={null} plivo numbers compliance get --expand end_user,documents,linked_numbers ``` **Command:** ```bash theme={null} plivo numbers compliance link [flags] ``` **Flags** * `--data `: full link JSON body; inline or @file.json (alternative to --link) * `--link `: number=compliance\_application\_id (repeatable) **Examples** ```bash theme={null} plivo numbers compliance link --link +14155551234= --link +14155556789= ``` **Command:** ```bash theme={null} plivo numbers compliance list [flags] ``` **Flags** * `--alias `: filter by alias * `--country `: filter by ISO country code * `--limit `: results per page (default 20) * `--number-type `: filter by number type * `--offset `: pagination offset * `--status `: filter by status * `--user-type `: filter by user type **Command:** ```bash theme={null} plivo numbers compliance requirements [flags] ``` **Flags** * `--country `: ISO country code, e.g. US (required) * `--number-type `: local|mobile|tollfree (required) * `--user-type `: individual|business (required) **Examples** ```bash theme={null} plivo numbers compliance requirements --country US --number-type local --user-type business ``` **Command:** ```bash theme={null} plivo numbers compliance update [flags] ``` **Flags** * `--data `: updated application JSON; inline or @file.json (required) * `--file `: document upload as field=path (repeatable; replaces all documents) **Examples** ```bash theme={null} plivo numbers compliance update --data @fixed.json --file documents[0].file=@passport.pdf ``` ## Number masking Create, list, fetch, and delete number-masking sessions. Number-Masking sessions (privacy-preserving call/SMS bridge) | Command | What it does | | --------------------------------------- | ------------------------------------------------------- | | `plivo numbers masking sessions` | Manage number-masking sessions | | `plivo numbers masking sessions create` | Create a masking session (spends money: requires --yes) | | `plivo numbers masking sessions delete` | End a masking session (requires --yes) | | `plivo numbers masking sessions get` | Get a masking session by uuid | | `plivo numbers masking sessions list` | List masking sessions | **Command:** ```bash theme={null} plivo numbers masking sessions ``` **Command:** ```bash theme={null} plivo numbers masking sessions create [flags] ``` **Flags** * `--call-time-limit `: max per-call duration in seconds * `--first-party `: first party E.164 (required) * `--mode `: voice|sms|both (default "both") * `--record`: record calls in this session * `--second-party `: second party E.164 (required) * `--session-expiry `: session lifetime in seconds * `--virtual-number `: virtual number to use (else allocates from pool) **Command:** ```bash theme={null} plivo numbers masking sessions delete ``` **Command:** ```bash theme={null} plivo numbers masking sessions get ``` **Command:** ```bash theme={null} plivo numbers masking sessions list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset # Voice Source: https://plivo.com/docs/cli/apis/voice Conferences, multiparty calls, recordings and SIP endpoints from the terminal. Calls and live-call streams are documented under [Make and control calls](/docs/cli/voice-agent/calls); this page covers the rest of the Voice API. ## Conferences List active conferences, inspect them, hang them up, and manage members. Inspect and control live audio conferences | Command | What it does | | ------------------------------------------- | -------------------------------------------------- | | `plivo voice conferences get` | Get conference details (members, run time) | | `plivo voice conferences hangup` | End the entire conference (requires --yes) | | `plivo voice conferences list` | List active conference names | | `plivo voice conferences member` | Per-member actions inside a conference | | `plivo voice conferences record` | Start recording a conference | | `plivo voice conferences stop-record` | Stop the active recording on a conference | | `plivo voice conferences member deaf` | Deafen a member (they can't hear) | | `plivo voice conferences member kick` | Kick a member from the conference (requires --yes) | | `plivo voice conferences member mute` | Mute a member | | `plivo voice conferences member play` | Play audio file(s) into a member's channel | | `plivo voice conferences member speak` | Speak TTS text to a member | | `plivo voice conferences member stop-play` | Stop audio playback to a member | | `plivo voice conferences member stop-speak` | Stop TTS playback to a member | | `plivo voice conferences member undeaf` | Undeafen a member | | `plivo voice conferences member unmute` | Unmute a member | **Command:** ```bash theme={null} plivo voice conferences get ``` **Command:** ```bash theme={null} plivo voice conferences hangup ``` **Command:** ```bash theme={null} plivo voice conferences list ``` **Command:** ```bash theme={null} plivo voice conferences member ``` **Command:** ```bash theme={null} plivo voice conferences record [flags] ``` **Flags** * `--callback-url `: URL hit when recording finishes * `--file-format `: mp3|wav (default "mp3") * `--time-limit `: max recording length in seconds (default 60) * `--transcribe`: request transcription **Command:** ```bash theme={null} plivo voice conferences stop-record ``` **Command:** ```bash theme={null} plivo voice conferences member deaf ``` **Command:** ```bash theme={null} plivo voice conferences member kick ``` **Command:** ```bash theme={null} plivo voice conferences member mute ``` **Command:** ```bash theme={null} plivo voice conferences member play [flags] ``` **Flags** * `--length `: stop after N seconds * `--loop`: loop playback * `--mix`: mix with conference audio (default true) * `--urls `: comma-separated audio file URLs (required) **Command:** ```bash theme={null} plivo voice conferences member speak [flags] ``` **Flags** * `--language `: BCP-47 language code (default "en-US") * `--text `: TTS text (required) * `--voice `: MAN|WOMAN (default "WOMAN") **Command:** ```bash theme={null} plivo voice conferences member stop-play ``` **Command:** ```bash theme={null} plivo voice conferences member stop-speak ``` **Command:** ```bash theme={null} plivo voice conferences member undeaf ``` **Command:** ```bash theme={null} plivo voice conferences member unmute ``` ## Multiparty calls Create MultiPartyCall rooms, add or remove participants, and end rooms. Creating a room and dialling a participant spend money and require `--yes`. Multi-Party Calls (MPC): group voice rooms with dynamic participants | Command | What it does | | ------------------------------------------- | --------------------------------------------------------------- | | `plivo voice multiparty create` | Create a multi-party call (spends money: requires --yes) | | `plivo voice multiparty end` | End the MPC and hang up all participants (requires --yes) | | `plivo voice multiparty get` | Get an MPC by uuid or friendly\_name | | `plivo voice multiparty list` | List multi-party calls | | `plivo voice multiparty participant` | Per-participant actions inside an MPC | | `plivo voice multiparty participant add` | Add a participant by dialing out (spends money: requires --yes) | | `plivo voice multiparty participant hold` | Put a participant on hold | | `plivo voice multiparty participant kick` | Remove a participant (requires --yes) | | `plivo voice multiparty participant list` | List participants in an MPC | | `plivo voice multiparty participant mute` | Mute a participant | | `plivo voice multiparty participant unhold` | Take a participant off hold | | `plivo voice multiparty participant unmute` | Unmute a participant | **Command:** ```bash theme={null} plivo voice multiparty create [flags] ``` **Flags** * `--max-participants `: cap on simultaneous participants * `--name `: friendly\_name for the MPC (required) * `--record`: auto-record the MPC **Command:** ```bash theme={null} plivo voice multiparty end ``` **Command:** ```bash theme={null} plivo voice multiparty get ``` **Command:** ```bash theme={null} plivo voice multiparty list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--status `: filter by status: active|initialized|ended **Command:** ```bash theme={null} plivo voice multiparty participant ``` **Command:** ```bash theme={null} plivo voice multiparty participant add [flags] ``` **Flags** * `--from `: source number for the dial-out (required) * `--role `: participant role: agent|supervisor|customer (default "agent") * `--to `: destination number to add (required) **Command:** ```bash theme={null} plivo voice multiparty participant hold ``` **Command:** ```bash theme={null} plivo voice multiparty participant kick ``` **Command:** ```bash theme={null} plivo voice multiparty participant list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo voice multiparty participant mute ``` **Command:** ```bash theme={null} plivo voice multiparty participant unhold ``` **Command:** ```bash theme={null} plivo voice multiparty participant unmute ``` ## Recordings List recordings (filter by call UUID, conference, or time range), fetch one, or delete one. List, fetch, and delete call/conference recordings | Command | What it does | | ------------------------------- | ----------------------------------- | | `plivo voice recordings delete` | Delete a recording (requires --yes) | | `plivo voice recordings get` | Get a recording by ID | | `plivo voice recordings list` | List recordings | **Command:** ```bash theme={null} plivo voice recordings delete ``` **Command:** ```bash theme={null} plivo voice recordings get ``` **Command:** ```bash theme={null} plivo voice recordings list [flags] ``` **Flags** * `--call-uuid `: filter by call uuid * `--conference-name `: filter by conference name * `--from-time `: filter recordings after this ISO time * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--to-time `: filter recordings before this ISO time ## SIP endpoints Create, list, update, and delete SIP endpoints (credentials a softphone or PBX registers with). Manage SIP endpoints (registered SIP devices/usernames) | Command | What it does | | ------------------------------ | -------------------------------------- | | `plivo voice endpoints create` | Create a SIP endpoint | | `plivo voice endpoints delete` | Delete a SIP endpoint (requires --yes) | | `plivo voice endpoints get` | Get an endpoint by ID | | `plivo voice endpoints list` | List SIP endpoints | | `plivo voice endpoints update` | Update a SIP endpoint | **Command:** ```bash theme={null} plivo voice endpoints create [flags] ``` **Flags** * `--alias `: human-friendly label * `--app-id `: application to attach * `--password `: SIP password (required) * `--username `: SIP username (required) **Command:** ```bash theme={null} plivo voice endpoints delete ``` **Command:** ```bash theme={null} plivo voice endpoints get ``` **Command:** ```bash theme={null} plivo voice endpoints list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo voice endpoints update [flags] ``` **Flags** * `--alias `: new alias * `--app-id `: new application id * `--password `: new password # Authenticate Source: https://plivo.com/docs/cli/authenticate Log in with a browser, use API credentials in CI or from an agent, switch between accounts, and log out. Pick one: a browser login for your laptop, or API credentials in environment variables for CI and coding agents. Both end up as a named **profile** you can switch between. ## Log in with a browser Connect the CLI to your Plivo account with a browser-based login flow. The CLI opens the Plivo Console in your default browser; you sign in there and approve access. Your password never touches the CLI. After approval, the CLI stores a profile in `~/.plivo/config.toml` and keeps the auth token in your operating system's secure credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). Use [`plivo auth list`](/docs/cli/authenticate#switch-between-accounts) to see saved profiles and `plivo auth use` to switch between them. To remove a profile and its stored token, use [`plivo logout`](/docs/cli/authenticate#log-out). Running in CI, a container, or an AI coding agent where a browser can't open? Skip `plivo login` entirely and [set credentials as environment variables](/docs/cli/authenticate#use-api-credentials-ci-and-agents). **Command:** `plivo login` **Flags** * `-n, --name `: name to save the profile under (default `default`). * `--no-verify`: skip the validation request to `GET /Account/` after login (offline or mock use only). **Examples** ```bash theme={null} plivo login plivo login --name staging ``` ## Use API credentials (CI and agents) For CI pipelines, containers, and AI coding agents, skip the browser login and pass your Auth ID and Auth Token as environment variables. Every command reads them automatically; they are used only when no `--profile` flag and no active profile are set (both take precedence over environment variables). ```bash theme={null} export PLIVO_AUTH_ID= export PLIVO_AUTH_TOKEN= plivo auth whoami ``` Find your Auth ID and Auth Token on the [Console overview](https://cx.plivo.com/home). Never commit them; load them from a secrets manager or a local `.env` file that is not checked in. Anyone with these two values can act as your account. Prefer a [subaccount](/docs/cli/apis/account#subaccounts) with the minimum products enabled for automated use. Useful companions in scripts: ```bash theme={null} export PLIVO_FEEDBACK_PROMPT=0 # never show the "rate the CLI?" prompt export CI=1 # disables all TTY-only interactions export PLIVO_CLI_TELEMETRY=0 # see Telemetry ``` ## Switch between accounts A profile is a saved set of credentials. Most people have one; if you work across several Plivo accounts or subaccounts, save one profile per account and switch between them. **Command:** `plivo auth ` #### `plivo auth list` List saved profiles and show which one is active. #### `plivo auth use ` Make a saved profile the active one for subsequent commands. #### `plivo auth whoami` Show the account behind the credentials the CLI would use right now: including whether they came from a profile or from environment variables (`"meta": {"source": "env"}`). ```bash theme={null} plivo auth whoami -o json ``` #### `plivo auth remove ` Delete a profile and its stored token. **Per-command override** Any command accepts `--profile ` to run once under a different profile without switching: ```bash theme={null} plivo --profile staging numbers list ``` Credential precedence is: `--profile` flag → the active profile → `PLIVO_AUTH_ID` / `PLIVO_AUTH_TOKEN` environment variables. ## Log out Remove a saved profile and delete its auth token from the operating system's credential store. **Command:** `plivo logout [profile]` **Flags** * `[profile]`: the profile to log out (default: the active profile). **Examples** ```bash theme={null} plivo logout plivo logout staging ``` # Configuration, flags and output Source: https://plivo.com/docs/cli/configure Global flags, JSON output and exit codes, config keys, and how to turn telemetry off. ## Global flags The Plivo CLI supports these flags on every command. **Command:** `plivo [flags]` **Flags** * `-o, --output `: output format: `table` or `json`. Defaults to `table` when attached to a terminal and `json` when piped. See [Output and exit codes](/docs/cli/configure#output-and-exit-codes). * `-y, --yes`: confirm a command that spends money or deletes data. Without it, such commands are refused with exit code 5. * `--dry-run`: print the HTTP request the command would make (method, URL, body) and exit without sending it. * `--profile `: run under a named profile from `~/.plivo/config.toml` instead of the active one. * `--timeout `: request timeout (default 30). * `--log-level `: `debug`, `info`, `warn`, `error`, or `none` (default `warn`). `debug` prints every HTTP request and response to stderr. * `-q, --quiet`: suppress non-data output. * `--no-color`: disable colored output. * `-h, --help`: help for any command. `--explain` is not a global flag. It narrates what a command will do in plain English before running it, and it exists only on the commands that implement it: `api`, `account applications create`, `auth whoami`, `voice calls make`, `messaging sms send`, `messaging whatsapp send`, `messaging mms send`, `numbers buy`, `numbers release` and `verify sessions create`. Every other command rejects it rather than accepting it and doing nothing. * `plivo --version` (or `plivo -v`) prints the CLI version; this works on the root command only, not after a subcommand. ## Output and exit codes The CLI is built to be parsed. Every command has one success shape, one error shape, and a small set of exit codes. ### Success envelope With `-o json`, an API-backed command prints the upstream API response verbatim under `data`. Nothing is dropped or renamed: ```json theme={null} { "data": { "api_id": "…", "meta": { "limit": 20, "offset": 0, "total_count": 6 }, "objects": [ … ] } } ``` Single resources have the resource under `data`; list commands have the API's `meta` and `objects` under `data`, so objects live at `data.objects[...]`. Commands that resolve credentials add `"meta": {"source": "env" | "profile"}`. The local tools that do not call the API (`streams test`, `streams forward`, `upgrade`, `config telemetry`) honour `-o json` too: each emits one machine-readable summary on stdout and sends its progress output to stderr, so stdout stays parseable. ### Error envelope Errors go to stderr as JSON and the process exits non-zero: ```json theme={null} { "error": { "code": "RESOURCE_NOT_FOUND", "message": "CDR for call uuid … not found", "hint": "List available resources with the matching `... list` command.", "status_code": 404, "request_id": "…", "retryable": false } } ``` Switch on `code`, never on message text. ### Exit codes | Exit | Meaning | Typical `code` values | | ----- | ------------------------------------------ | ------------------------------------------------------------------------------------- | | `0` | success | — | | `1` | bad input, or the API rejected the request | `USER_ERROR`, `BAD_INPUT`, `VALIDATION_ERROR`, `RESOURCE_NOT_FOUND`, `UPSTREAM_ERROR` | | `2` | authentication | `AUTH_MISSING`, `AUTH_INVALID`, `AUTH_FORBIDDEN`, `AUTH_EXPIRED` | | `3` | network | `NETWORK_ERROR` | | `5` | refused for safety | `DESTRUCTIVE_REFUSED`; a spend or delete command without `--yes` | | `130` | interrupted (Ctrl-C) | — | ### Safety Any command that spends money or deletes data, `voice calls make`, `messaging * send`, `numbers buy`, `numbers release`, `* delete`, and mutating `plivo api` calls, is refused unless `--yes` is present. The refusal happens locally, before any request is sent. Use `--dry-run` to see the exact request first. ## Configuration keys Use the `config` command to view and change CLI settings stored in `~/.plivo/config.toml`. **Command:** `plivo config ` #### `plivo config telemetry on|off|status` Turn identity telemetry on or off, or show its current state. See [Telemetry](/docs/cli/configure#telemetry) for exactly what is and isn't sent. ```bash theme={null} plivo config telemetry status plivo config telemetry off ``` The environment variable `PLIVO_CLI_TELEMETRY=0` does the same for a single shell session or CI job and wins over the config file. #### `plivo config get ` / `plivo config set ` Read or write an individual setting. Currently supported key: `telemetry`. **Environment variables** * `PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN`: [headless credentials](/docs/cli/authenticate#use-api-credentials-ci-and-agents). * `PLIVO_CLI_TELEMETRY=0`: disable identity telemetry. * `PLIVO_FEEDBACK_PROMPT=0`: silence the post-command feedback prompt. * `PLIVO_FEEDBACK_TELEMETRY=0`: disable `plivo feedback` submission entirely. * `PLIVO_NO_UPDATE_CHECK=1`: silence the "newer version available" hint. ## Telemetry The Plivo CLI sends a small amount of usage data with each request so we can see which commands are used, what fails, and which versions are in the field. It is **enabled by default**, and you can turn the identity part off at any time. ### What is collected On every request to Plivo: * CLI version, operating system, and architecture (used for the upgrade hint and compatibility). * The command name (for example `voice calls list`): never its arguments or flag values. * When identity telemetry is on: the account's Auth ID, the email of the logged-in user, the account region, and an internal user identifier. This lets us see usage per person within an organisation. `plivo feedback` additionally sends the rating and comment you type. ### What is never collected * Your auth token, API keys, or passwords. * Phone numbers, call or message UUIDs, message bodies, audio, or recordings. * URLs you pass to commands (answer URLs, WebSocket URLs, callback URLs). * Flag values, file contents, or anything from your Plivo account data. ### How to turn it off Identity telemetry is an account-level setting you control: ```bash theme={null} plivo config telemetry off # persistent, stored in ~/.plivo/config.toml plivo config telemetry status ``` or, for a single shell session or CI job (takes precedence over the config file): ```bash theme={null} PLIVO_CLI_TELEMETRY=0 plivo voice calls list ``` With telemetry off, requests still carry the CLI version, OS, and architecture (the server needs them to tell you when an upgrade is available) but no identity fields. Set `PLIVO_FEEDBACK_TELEMETRY=0` to disable `plivo feedback` submission as well. # Read the docs from your terminal Source: https://plivo.com/docs/cli/docs Search, list and print any Plivo documentation page from the shell. No credentials, no browser. `plivo docs` reads the Plivo documentation without leaving the shell. It needs no credentials, so it works before you have authenticated, and inside CI containers and coding agents where nobody can open a browser. **Command:** `plivo docs ` ## `plivo docs search ` Search the full text of every page. A page matches only if it contains **all** the keywords, and results are ranked by how often those keywords appear. Matching is case-insensitive and substring based, so partial words and API field names both work. * `--limit `: maximum results (default 10). ```bash theme={null} plivo docs search audio streaming plivo docs search bidirectional plivo docs search 10dlc brand registration -o json ``` ## `plivo docs list` List every documentation page. ## `plivo docs show ` Print one page in full. The reference can be a URL, a path fragment such as `voice/api/call`, or a page title, and the most specific match wins. ```bash theme={null} plivo docs show voice/api/call plivo docs show "Account API" ``` ## Cache, refresh and offline use The full text is cached under `~/.plivo/cache` for a day, so repeat searches are instant. If the network is unreachable the CLI serves the stale cache rather than failing, which keeps the docs readable on a bad connection. `--refresh` bypasses the cache and re-fetches; it is a group flag, so it works on `plivo docs` itself and on all three subcommands. ## The same content without the CLI Every page on the documentation site is also available as plain Markdown: append `.md` to any URL. Two index files summarise the whole site for LLMs and agents, and they are what `plivo docs` reads. ```bash theme={null} curl -s https://www.plivo.com/docs/llms.txt # index of every page, with one-line summaries curl -s https://www.plivo.com/docs/llms-full.txt # every page, in one file curl -s https://www.plivo.com/docs/voice/quickstart/quickstart.md ``` For a synthesised, cited answer instead of raw pages, use [`plivo ask`](/docs/cli/apis/diagnose-ask#ask-a-question). # Install and upgrade the Plivo CLI Source: https://plivo.com/docs/cli/install Install the Plivo CLI on macOS, Linux, Windows or CI, keep it current, and turn on shell completion. ## Install Install with a package manager, or with the one-line installer. The installer detects your OS and architecture, downloads the matching release binary, verifies its SHA-256 checksum, and places it in a user-owned directory on your `PATH`: no `sudo`. ```bash theme={null} brew install plivo/tap/plivo ``` ```powershell theme={null} scoop bucket add plivo https://github.com/plivo/homebrew-tap scoop install plivo ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/plivo/plivo-cli/main/install.sh | bash ``` ```powershell theme={null} irm https://raw.githubusercontent.com/plivo/plivo-cli/main/install.ps1 | iex ``` ```bash theme={null} git clone https://github.com/plivo/plivo-cli && cd plivo-cli && go build -o plivo . ``` Requires Go 1.26 or later. Once the CLI is installed, [log in to Plivo](/docs/cli/authenticate#log-in-with-a-browser), set up [autocompletion](/docs/cli/install#shell-autocompletion), or install the [agent skill](/docs/cli/agents) if an AI coding agent will be driving the CLI. **Installer options** * `PLIVO_CLI_VERSION`: install a specific release tag instead of the latest (for example `v0.2.0`). * `PLIVO_INSTALL_DIR`: install into a specific directory instead of the first user-owned directory on `PATH`. **Verifying a release** Release binaries for macOS, Linux and Windows (amd64 and arm64), the `SHA256SUMS` file and its signature are published on the [GitHub releases page](https://github.com/plivo/plivo-cli/releases). The checksums are signed with [cosign](https://docs.sigstore.dev/cosign/installation/) in keyless mode, and `install.sh`, `install.ps1` and `plivo upgrade` all verify that signature when cosign is present on the machine. To check by hand: ```bash theme={null} V=v1.0.0 for f in SHA256SUMS SHA256SUMS.sig SHA256SUMS.pem; do curl -fsSLO "https://github.com/plivo/plivo-cli/releases/download/$V/$f" done cosign verify-blob SHA256SUMS \ --signature SHA256SUMS.sig --certificate SHA256SUMS.pem \ --certificate-identity cx-tech@plivo.com \ --certificate-oidc-issuer https://accounts.google.com ``` `Verified OK` means the checksums genuinely came from Plivo. Pin both the identity and the issuer: without them any valid Sigstore signature would pass. ## Upgrade Keep your Plivo CLI up to date to get new commands, fixes, and security updates. **Command:** `plivo upgrade` `plivo upgrade` fetches the latest release, verifies the downloaded binary against the release's `SHA256SUMS` (and, when cosign is installed, the signature on those checksums), then atomically replaces the running executable. It honours `-o json`, printing a single summary on stdout with progress on stderr. If the running binary lives inside a Homebrew prefix, `upgrade` refuses and points you at `brew upgrade plivo` so the two do not fight over the same file. **Flags** * `--check`: report whether a newer release exists without installing it. * `--version `: install a specific release tag instead of the latest. * `--force`: reinstall even if you are already on the target release. **Examples** ```bash theme={null} plivo upgrade # install the latest release plivo upgrade --check # check only plivo upgrade --version v0.4.1 ``` The CLI also prints a one-line hint on stderr when a newer version is available (at most once every 24 hours, only when attached to a terminal). Set `PLIVO_NO_UPDATE_CHECK=1` to silence it. ## Shell autocompletion Generate a completion script for your shell so that commands, subcommands, and flags tab-complete. **Command:** `plivo completion ` **Examples** ```bash theme={null} # zsh plivo completion zsh > "${fpath[1]}/_plivo" # bash plivo completion bash > /usr/local/etc/bash_completion.d/plivo # fish plivo completion fish > ~/.config/fish/completions/plivo.fish # PowerShell plivo completion powershell | Out-String | Invoke-Expression ``` Run `plivo completion --help` for shell-specific installation notes. # Plivo CLI Source: https://plivo.com/docs/cli/overview Work with every Plivo API from the terminal (calls, messages, numbers, applications and more) by hand or from an AI coding agent. The Plivo CLI is a command-line interface to the Plivo APIs. Anything you can do with the REST API (make calls, send messages, search and buy numbers, create applications, manage subaccounts, pull recordings) you can do from the terminal, and anything the CLI doesn't wrap yet is one `plivo api` call away. It is built for people **and** for AI coding agents (Claude Code, Cursor, Codex): every command returns machine-readable output with `-o json` (API-backed commands hand back the raw API response; local tools such as `streams test`, `streams forward` and `upgrade` print a single summary and move progress to stderr), previews changes with `--dry-run`, and refuses to spend money or delete anything unless you pass `--yes`. It also ships Plivo's AI assistant: `plivo ask` answers questions in plain English and `plivo … diagnose` explains why a call or message failed. ## What you can do | Area | Examples | Where | | ------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Voice | make and control calls, transfer, record, conferences, multiparty calls, SIP endpoints | [Make and control calls](/docs/cli/voice-agent/calls), [Voice](/docs/cli/apis/voice) | | Voice agents on Audio Streaming | test a WebSocket bot, forward live calls to it, connect a number | [Voice agents with Audio Streaming](/docs/cli/voice-agent/test-websocket) | | Messaging | send and list SMS, MMS and WhatsApp; 10DLC and Powerpacks | [Messaging](/docs/cli/apis/messaging) | | Numbers | search, buy, attach to an application, compliance applications (India KYC), masking | [Connect a number](/docs/cli/voice-agent/connect-number), [Numbers](/docs/cli/apis/numbers) | | Account | applications, subaccounts, balance, Verify, Lookup | [Account, Verify and Lookup](/docs/cli/apis/account) | | Debugging (any product) | `plivo voice calls diagnose`, `plivo messaging sms diagnose`, `plivo ask` | [Diagnose and ask](/docs/cli/apis/diagnose-ask) | | Documentation | search, list and print any docs page from the shell, no credentials needed | [Read the docs](/docs/cli/docs) | | Anything else | `plivo api GET /Account/{auth_id}/…` | [Any REST endpoint](/docs/cli/apis/api) | ## Example: a voice agent on Audio Streaming The most common thing people build with the CLI today is a WebSocket voice agent on [Audio Streaming](/docs/voice-agents/audio-streaming/overview), so the docs walk through that path in its own section. Voice agents built on SIP platforms (LiveKit, Vapi, Retell, ElevenLabs) do not use the stream commands; their trunks are set up through the [SIP trunking API](/docs/voice-agents/sip-trunking/api/sip-trunking), reachable with `plivo api`. | Step | What you do | Command | | ---- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Install and log in | `brew install plivo/tap/plivo` · `plivo login`, see [Install](/docs/cli/install#install), [Authenticate](/docs/cli/authenticate) | | 2 | Teach your coding agent the CLI | `plivo skill install`, see [Agent setup](/docs/cli/agents) | | 3 | Prove your WebSocket bot works before any phone is involved | `plivo voice streams test --to wss://… --bidirectional`, see [Test your WebSocket endpoint](/docs/cli/voice-agent/test-websocket) | | 4 | Point a Plivo number at your agent | `plivo account applications create` · `plivo numbers update --app-id`, see [Connect a number](/docs/cli/voice-agent/connect-number) | | 5 | Take a real call on a bot that has no public answer URL yet | `plivo voice streams forward --number +14151234567 --app --to ws://…`, see [Forward calls to your bot](/docs/cli/voice-agent/forward-calls) | | 6 | Make outbound calls, transfer, record | `plivo voice calls make …`, see [Make and control calls](/docs/cli/voice-agent/calls) | | 7 | Ask what happened on a call, failed or not | `plivo voice calls diagnose `, see [Diagnose a call](/docs/cli/voice-agent/diagnose-call) | Not building a voice agent? Start with [Install](/docs/cli/install#install) and [Authenticate](/docs/cli/authenticate), then pick your API under **Plivo APIs**: [Voice](/docs/cli/apis/voice), [Messaging](/docs/cli/apis/messaging), [Numbers](/docs/cli/apis/numbers), [Account](/docs/cli/apis/account). The CLI is open source under the Apache-2.0 license: [github.com/plivo/plivo-cli](https://github.com/plivo/plivo-cli). Run `plivo feedback` from the terminal, or open an issue on the [issue tracker](https://github.com/plivo/plivo-cli/issues). # Troubleshooting Source: https://plivo.com/docs/cli/troubleshooting Common Plivo CLI errors and what to do about them. | You see | It means | Do this | | ------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------- | | `AUTH_MISSING` (exit 2) | No credentials found | `plivo login`, or export `PLIVO_AUTH_ID` and `PLIVO_AUTH_TOKEN` | | `AUTH_INVALID` / `AUTH_EXPIRED` (exit 2) | Wrong or expired credentials | Re-run `plivo login`; check the environment variables aren't stale | | `AUTH_FORBIDDEN` on `plivo support` | Env-var credentials have no per-user identity | Use `plivo login` for this command | | `DESTRUCTIVE_REFUSED` (exit 5) | A spend or delete command ran without `--yes` | Add `--yes`, or `--dry-run` to preview | | `RATE_LIMITED` on `ask` / `diagnose` | Per-account limit on assistant requests | Wait for the interval in the message | | `NETWORK_ERROR` (exit 3) | Could not reach Plivo | Check connectivity or VPN; `--log-level debug` shows the request | | `ssh not found, needed for the localhost.run tunnel` on `streams forward` | The default tunnel shells out to `ssh`, which is missing | Install an ssh client, or use ngrok instead with `--tunnel ngrok` | | The tunnel never comes up on `streams forward` | localhost.run was unreachable or refused the connection | Retry, or switch provider with `--tunnel ngrok` (needs ngrok on `PATH`) | | `interactive mode (-i) can't be combined with -o json` | Input is piped, so JSON output was selected | Add `-o table` | | Table output looks truncated | Tables show a curated subset of fields | Use `-o json` for the full API response | Still stuck? `plivo ask ""` usually knows, or open an issue on the [Plivo CLI issue tracker](https://github.com/plivo/plivo-cli/issues). # Make and control calls Source: https://plivo.com/docs/cli/voice-agent/calls Place outbound calls to your agent, transfer a live call to a human, play or record, and start or stop a stream on a live call. Outbound voice agents start with `plivo voice calls make --from --to --answer-url …`; the answer URL returns the same `` XML as an inbound call. Human handoff is `plivo voice calls transfer --legs aleg --aleg-url …` where the new URL returns a ``. Calls cost money, so `make` needs `--yes` (use `--dry-run` to preview). ## Calls Make outbound calls, list and inspect call records, and control live calls. `voice calls make` spends money and requires `--yes`; live-call controls (`play`, `speak`, `record`, `dtmf`, `transfer`, `stop-*`) act on an established call and do not. Make and inspect voice calls | Command | What it does | | ------------------------------- | ------------------------------------------------------------------------------ | | `plivo voice calls dtmf` | Send DTMF tones into a live call | | `plivo voice calls get` | Get a call by UUID | | `plivo voice calls hangup` | Hang up a live call (requires --yes) | | `plivo voice calls list` | List calls | | `plivo voice calls make` | Make an outbound call (requires --yes; spends money: use --dry-run to preview) | | `plivo voice calls play` | Play audio file(s) into a live call | | `plivo voice calls record` | Start recording a live call | | `plivo voice calls speak` | Speak text into a live call via TTS | | `plivo voice calls stop-play` | Stop any audio currently playing in a live call | | `plivo voice calls stop-record` | Stop the active recording on a live call | | `plivo voice calls stop-speak` | Stop any TTS currently playing in a live call | | `plivo voice calls transfer` | Transfer one or both legs of a live call to new PlivoXML URLs | **Command:** ```bash theme={null} plivo voice calls dtmf [flags] ``` **Flags** * `--digits `: DTMF digits to send, e.g. 1234# (required) * `--leg `: aleg|bleg (default "aleg") **Command:** ```bash theme={null} plivo voice calls get ``` **Command:** ```bash theme={null} plivo voice calls hangup ``` **Command:** ```bash theme={null} plivo voice calls list [flags] ``` **Flags** * `--direction `: inbound|outbound * `--from `: filter by from\_number * `--limit `: results per page (default 20) * `--offset `: pagination offset * `--to `: filter by to\_number **Command:** ```bash theme={null} plivo voice calls make [flags] ``` **Flags** * `--answer-method `: GET|POST (default "GET") * `--answer-url `: URL returning PlivoXML to play on answer (default: Plivo's hello demo) (default "[https://s3.amazonaws.com/static.plivo.com/answer.xml](https://s3.amazonaws.com/static.plivo.com/answer.xml)") * `--from `: source number (E.164); must be on your account (required) * `--hangup-url `: URL hit when call ends * `--machine-detection `: none|true|hangup * `--ring-url `: URL hit when call starts ringing * `--to `: destination number (E.164) (required) **Command:** ```bash theme={null} plivo voice calls play [flags] ``` **Flags** * `--legs `: aleg|bleg|both (default "aleg") * `--length `: stop after N seconds (0 = full file) * `--loop`: loop the playback * `--mix`: mix with the call audio (else replace) (default true) * `--urls `: comma-separated list of audio file URLs to play (required) **Command:** ```bash theme={null} plivo voice calls record [flags] ``` **Flags** * `--both-legs`: record both legs (default: just A-leg) * `--callback-method `: GET|POST (default "POST") * `--callback-url `: URL hit when recording finishes * `--file-format `: mp3|wav (default "mp3") * `--time-limit `: max recording length in seconds (default 60) * `--transcribe`: request transcription **Command:** ```bash theme={null} plivo voice calls speak [flags] ``` **Flags** * `--language `: language code, e.g. en-US, en-GB, hi-IN (default "en-US") * `--legs `: aleg|bleg|both (default "aleg") * `--mix`: mix with the call audio (else replace) (default true) * `--text `: text to speak via TTS (required) * `--voice `: voice: MAN|WOMAN (default "WOMAN") **Command:** ```bash theme={null} plivo voice calls stop-play ``` **Command:** ```bash theme={null} plivo voice calls stop-record ``` **Command:** ```bash theme={null} plivo voice calls stop-speak ``` **Command:** ```bash theme={null} plivo voice calls transfer [flags] ``` **Flags** * `--aleg-method `: GET|POST (default "POST") * `--aleg-url `: new URL for A-leg (caller side) * `--bleg-method `: GET|POST (default "POST") * `--bleg-url `: new URL for B-leg (callee side) * `--legs `: which leg(s) to act on: aleg|bleg|both (default "aleg") ## Streams on a live call (REST) Start an audio stream on an already-answered call (instead of via `` XML), list the streams on a call, or stop them. | Command | What it does | | --------------------------------- | -------------------------------------------------------------------------- | | `plivo voice calls streams` | Live audio streams on a call (WebSocket bridge for transcription / agents) | | `plivo voice calls streams get` | Get details for one stream on a call | | `plivo voice calls streams list` | List active streams on a call | | `plivo voice calls streams start` | Start a new audio stream on a call | | `plivo voice calls streams stop` | Stop one stream (with id) or all streams (without id) on a call | **Command:** ```bash theme={null} plivo voice calls streams ``` **Command:** ```bash theme={null} plivo voice calls streams get ``` **Command:** ```bash theme={null} plivo voice calls streams list ``` **Command:** ```bash theme={null} plivo voice calls streams start [flags] ``` **Flags** * `--audio-track `: inbound|outbound|both (default "inbound") * `--bidirectional`: let the WebSocket send audio back into the call * `--callback-url `: alias for --stream-status-callback * `--content-type `: audio codec content-type (default "audio/x-l16;rate=16000") * `--extra-headers `: comma-separated extra WebSocket headers (k1=v1,k2=v2) * `--service-type `: Plivo service type override * `--stream-status-callback `: URL hit when stream starts/ends * `--url `: WebSocket URL to receive audio (wss\://...) (required) **Command:** ```bash theme={null} plivo voice calls streams stop [stream_id] ``` # Connect a number to your agent Source: https://plivo.com/docs/cli/voice-agent/connect-number Create an application that points at your answer URL and attach a Plivo number to it. A Plivo number does not hold URLs itself. It is attached to an **application**, and the application holds the answer URL (which returns your `` XML), the fallback URL and the hangup URL. So going live is two commands: ```sh theme={null} plivo account applications create --app-name my-agent \ --answer-url https://YOUR-HOST/plivo/answer --answer-method POST -o json plivo numbers update 14155551234 --app-id --dry-run # preview: shows the current binding plivo numbers update 14155551234 --app-id --yes ``` To move to a new server later, update the application's URLs. The number does not change. `plivo numbers update` re-attaches a number; preview it with `--dry-run` and note the previous `app_id` so you can roll back. Searching, buying and compliance for numbers are on the [Numbers](/docs/cli/apis/numbers) page. ## Applications An application holds the webhook URLs Plivo calls for a number. Create one, attach numbers to it with `plivo numbers update --app-id`, and update its URLs without touching the number. Manage Plivo applications (voice/messaging webhooks) | Command | What it does | | ----------------------------------- | -------------------------------------- | | `plivo account applications create` | Create a new application | | `plivo account applications delete` | Delete an application (requires --yes) | | `plivo account applications get` | Get application details | | `plivo account applications list` | List applications | | `plivo account applications update` | Update an application | **Command:** ```bash theme={null} plivo account applications create [flags] ``` **Flags** * `--answer-method `: GET|POST (default "POST") * `--answer-url `: webhook for incoming calls (required) * `--app-name `: application name (required) * `--default-number-app`: set as default for new numbers * `--fallback-answer-url `: backup webhook if answer-url fails * `--hangup-url `: webhook for call hangup * `--log-incoming-messages`: log inbound SMS content (default true) * `--message-url `: webhook for inbound SMS **Command:** ```bash theme={null} plivo account applications delete [flags] ``` **Flags** * `--cascade`: also detach numbers/endpoints **Command:** ```bash theme={null} plivo account applications get ``` **Command:** ```bash theme={null} plivo account applications list [flags] ``` **Flags** * `--limit `: results per page (default 20) * `--offset `: pagination offset **Command:** ```bash theme={null} plivo account applications update [flags] ``` **Flags** * `--answer-method `: GET|POST * `--answer-url `: new answer URL * `--app-name `: new application name * `--hangup-url `: new hangup URL * `--message-url `: new message URL # Diagnose a call Source: https://plivo.com/docs/cli/voice-agent/diagnose-call Get a plain-English explanation of what happened on any call to your voice agent (failed, cut short, or completed) and what to fix. Give `diagnose` any call UUID and it explains what happened: whose side each step was on (your server, Plivo, the carrier), the timeline, and anything unusual. Use it on a failed call to find out why, and on a completed call that ended sooner than expected, had one-way audio, or dropped its stream. For a voice agent the usual culprits are three: Plivo could not reach your answer URL, the XML it returned was not valid, or the WebSocket bot did not answer: `diagnose` tells you which. ```bash theme={null} plivo voice calls list --limit 5 # find the UUID plivo voice calls diagnose # usually about a minute; allow 30 to 120 s ``` A typical answer: ```text theme={null} What happened: This inbound call was terminated because Plivo could not fetch call instructions from your answer URL. Likely cause: The answer URL https://api.example.com/plivo/answer returned 404. The call was hung up with cause 7011 (Error Reaching Answer URL). Timeline: 07:48:40.600 call received · 07:48:40.630 answer URL responded 404 · 07:48:41.016 call hung up Suggested next step: Make sure the answer URL is deployed and returns Plivo XML with HTTP 200; every inbound call will fail until it does. ``` The hangup causes you will see most often while building a voice agent: | Hangup cause | Meaning | Fix | | -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `7011` Error reaching answer URL | Plivo could not fetch your answer URL (down, not public, tunnel closed, 4xx/5xx) | Check the URL is reachable from the internet; while developing, use [Forward calls to your bot](/docs/cli/voice-agent/forward-calls) | | `8011` Invalid answer XML | The answer URL returned something that is not Plivo XML (often JSON, or an HTML error page) | Return `` with `Content-Type: application/xml`; check with `curl -X POST ` | | `4010` End of XML instructions | Normal end; the bot closed the WebSocket, or the XML finished | Only a problem if the call ended earlier than you expected: check your bot's logs for why it closed | | `USER_BUSY` (from your XML) | Your answer URL returned `` or an empty response | Fix the branch of your code that returned it | If the answer URL and XML are fine but the caller hears silence, the bot is the problem: reproduce without a phone with [Test your WebSocket endpoint](/docs/cli/voice-agent/test-websocket). For the raw record (hangup cause, source, duration) run `plivo voice calls get -o json`. The answer is written by Plivo's AI assistant, so treat it as an explanation to read, not a stable schema to parse. `diagnose` and `plivo ask` share a limit of 5 requests per 10 minutes per account. Only calls on your own account can be diagnosed. For messages and general questions see [Diagnose and ask](/docs/cli/apis/diagnose-ask). # Forward live calls to any WebSocket Source: https://plivo.com/docs/cli/voice-agent/forward-calls Take a real inbound call on a bot that has no public answer URL yet (on your laptop, a staging box or a teammate's tunnel) with one command. ## How it works One command replaces the usual "deploy an answer URL, write XML, point a number at it" loop while you are still developing. `--to` takes any `ws://` or `wss://` URL: a bot on `localhost`, one on a staging server, or a colleague's tunnel. The tunnel is started on the machine running the CLI, not on the machine where the bot runs. `forward` saves the application's current `answer_url`, starts a tunnel and a local HTTP/WebSocket server, points the application at the tunnel, and bridges the audio of incoming calls to your local WebSocket handler. On Ctrl-C it restores the original `answer_url`. Every phone number attached to the application is redirected for as long as `forward` runs: the confirmation step tells you how many. Use a dedicated test application. ## The tunnel There is nothing to install and no account to create. `forward` defaults to localhost.run over ssh, and ssh already ships on macOS and Linux. If `ngrok` is already on your `PATH` (or at `~/.plivo/bin/ngrok`) the CLI uses that instead, since a warmed-up ngrok is usually faster. `--tunnel` forces the choice: `auto` (the default) prefers ngrok when it is present and falls back to localhost.run, `ngrok` and `localhost.run` pin one provider. The confirmation prompt and the `--dry-run` preview print a placeholder answer URL of the form `https:///answer` whichever provider is chosen. The real tunnel URL is printed once the tunnel is up. ## Command and flags Redirect an app's answer\_url to a local tunnel so calls stream into your local handler **Command:** ```bash theme={null} plivo voice streams forward [flags] ``` **Flags** * `--app `: Plivo Application UUID whose answer\_url will be temporarily redirected (required) * `--bidirectional`: allow bot to send audio back to the caller (default true) * `--codec `: audio codec advertised to Plivo: mulaw | l16 (default "mulaw") * `--keep`: do NOT restore the original answer\_url on exit (advanced) * `--number `: E.164 number attached to --app (required) * `--print-payload`: dump full webhook bodies to terminal (verbose) * `--rate `: sample rate in Hz (mulaw: 8000; l16: 8000 or 16000) (default 8000) * `--to `: local WebSocket URL to forward call audio to, e.g. ws\://localhost:7860/ws (required) * `--tunnel `: tunnel provider: auto | ngrok | localhost.run (default "auto") * `-y, --yes`: skip the confirmation prompt **Examples** ```bash theme={null} plivo voice streams forward \ --number +14155550142 \ --app abc-uuid-def-456 \ --to ws://localhost:7860/ws # Don't restore answer_url on exit (advanced): plivo voice streams forward --number +14155550142 --app abc --to ws://localhost:7860/ws --keep ``` `--codec` and `--rate` follow the same rules here as they do for `streams test`, and an unsupported pair is rejected before anything is redirected: see [The audio contract](/docs/cli/voice-agent/test-websocket#the-audio-contract). Nothing is purchased, created, or deleted: the only change is one field on one application, restored on exit unless you pass `--keep`. # Test your WebSocket endpoint Source: https://plivo.com/docs/cli/voice-agent/test-websocket Send real Plivo-shaped audio frames to your bot and check it answers: before any phone number is involved. ## Test a WebSocket endpoint Open a WebSocket to your server and send exactly what a real call sends: one `start` frame, then a `media` frame every 20 ms for `--duration` seconds, then one `stop` frame. Reports connection latency, frames sent, and (with `--bidirectional`) whether your server sent audio back. No call is placed and Plivo's backend is not involved; this is a pure client-side check you can run in CI. #### `plivo voice streams test` Pre-flight a WebSocket endpoint with synthetic Plivo audio frames **Command:** ```bash theme={null} plivo voice streams test [flags] ``` **Flags** * `--bidirectional`: also read frames back from the endpoint (test bot→caller path) * `--codec `: audio codec: mulaw | l16 (default "mulaw") * `--duration `: seconds of synthetic audio to stream (max 30) (default 3) * `--insecure`: skip TLS verification (self-signed dev certs only) * `--rate `: sample rate in Hz (mulaw: 8000; l16: 8000 or 16000) (default 8000) * `--to `: WebSocket URL of the endpoint to test (ws\:// or wss\://, required) **Examples** ```bash theme={null} plivo voice streams test --to wss://my-bot.example.com/ws plivo voice streams test --to ws://localhost:7860/ws --duration 5 plivo voice streams test --to wss://localhost:7860/ws --insecure # self-signed dev cert plivo voice streams test --to wss://my-bot.example.com/ws --bidirectional ``` If `Received N frames back from endpoint` is missing with `--bidirectional`, your server never sent a `playAudio` message: callers would hear silence. ### The audio contract The XML attribute and the WebSocket frame spell the audio format differently, which is the part that is easiest to get wrong. `` carries a single combined `contentType` attribute holding the codec and the sample rate together. There is no `sampleRate` attribute on ``. ```xml theme={null} wss://your-bot.example.com/ws ``` The WebSocket `start` frame spells the same two things out separately, under `mediaFormat`: ```json theme={null} {"event":"start","start":{"streamId":"...","callId":"...","accountId":"...", "mediaFormat":{"encoding":"audio/x-mulaw","sampleRate":8000,"channels":1}}} ``` The l16 MIME type is `audio/x-l16`, not `audio/l16`. Exactly three combinations are supported: | `contentType` | `--codec` | `--rate` | Bytes per 20 ms frame | | ------------------------- | --------- | -------- | --------------------- | | `audio/x-mulaw;rate=8000` | `mulaw` | `8000` | 160 | | `audio/x-l16;rate=8000` | `l16` | `8000` | 320 | | `audio/x-l16;rate=16000` | `l16` | `16000` | 640 | There is no mu-law 16 kHz stream. Any other codec and rate pair is rejected before the connection is opened, with `BAD_FLAG` and exit code 1, so a bad combination fails on your laptop instead of as a dropped stream mid-call. `--codec l16` generates real little-endian 16-bit PCM, so a bot that decodes the payload sees a genuine waveform rather than mu-law bytes under an l16 header. # 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. *** ## What is an account usage limit? Your usage limit is a cap on how much your account can spend in a calendar month. It covers your total spend on Plivo, across every product on the account. Once your spend reaches the limit, Plivo stops accepting API requests until you raise it or the month resets. You set the limit yourself and can change it at any time. *** ## What is my usage limit set to by default? New accounts start with a usage limit of \$1,000 per month. You can raise it yourself in the console up to the Professional plan maximum of \$2,500 per month in the US data region, or ₹2,50,000 per month in the India data region. You can also lower it if you want a tighter cap. If you have never configured a limit, your account is enforced against the \$1,000 default. *** ## How do I change my usage limit? Open **Organization settings > Account limits** and, under **Monthly Account Usage**, click **Edit spend limit**. You can also reach the same page from **Monthly Usage** on the Home page by clicking **Manage limit**. Enter your new monthly limit and save. Changes take effect immediately. The dialog also shows the highest limit you can set. *** ## Will Plivo notify me before I reach my usage limit? Yes. Plivo emails you at 50%, 80%, and 100% of your usage limit, so you always know how much you have used and can decide whether to raise it, request a higher one, or leave it as it is. These are separate from balance notifications, which track the funds in your account rather than your monthly spend against the limit. *** ## What happens when my account reaches its usage limit? Requests on the account start failing with an HTTP 403, and Plivo does not charge you for them. This applies across every product on the account. To start sending again, raise your limit from **Organization settings > Account limits**, or wait for the reset at the start of the next calendar month. *** ## Why are my API requests failing with a 403 error? If you have reached your monthly usage limit, Plivo returns a 403 with a message saying so: "Your account has reached its configured monthly usage limit." Check **Organization settings > Account limits**. If your month-to-date spend has reached the limit shown there, that is the cause. Raise the limit and requests go through again immediately. A 403 without that message means something else, so check the message in the API response before assuming it is your limit. *** ## Can I set a usage limit higher than the maximum shown in the console? Not from the console. It will not let you set a limit above the maximum shown for your account. If your spend needs to go beyond it, click **Request Enterprise** on **Organization settings > Account limits**, contact your account manager, or contact [Plivo Support](https://support.plivo.com). *** ## When does my usage limit reset? At the start of each calendar month, when the counter returns to zero. Month boundaries are evaluated in UTC. If you raise your limit mid-month, the change applies immediately. *** ## 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 * [Plans and Pricing](/docs/faq/account/plans) * [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 | As required | | **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,50,000/month | As required | | **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, and requests fail until you raise your monthly usage limit or it resets at the start of the next calendar month. You can raise the limit yourself in the console up to the Professional plan maximum of \$2,500 per month in the US data region, or ₹2,50,000 per month in the India data region. To go beyond that maximum, 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/voice/pricing/) - Per-minute voice rates * [SMS Pricing](https://www.plivo.com/sms/pricing/) - 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/voice/pricing/) 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/sms/pricing/) 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/voice/pricing/) * [SMS Pricing](https://www.plivo.com/sms/pricing/) * [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/voice/pricing/) * [SMS Pricing](https://www.plivo.com/sms/pricing/) * [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.