Required dependencies

npm install axios base-64 build-url form-data https-proxy-agent joi jsonwebtoken lodash querystring request uri-parser utf8 xml2js xmlbuilder @types/node

No native modules, no pod install, no Android linking required. The source is pure JavaScript (ES modules).

Project setup

1. Copy the source/ directory into your project, e.g. src/plivo/.
2. Ensure your project supports ES modules. In package.json:

   { "type": "module" }
   

   Or, if using TypeScript with CommonJS, configure Babel with @babel/plugin-transform-modules-commonjs and set "allowSyntheticDefaultImports": true in tsconfig.json.
3. If using TypeScript, add a path alias in tsconfig.json:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": { "plivo-src/*": ["src/plivo/*"] }
     }
   }
   

4. Set environment variables (never hard-code credentials):

   export PLIVO_AUTH_ID=your_auth_id
   export PLIVO_AUTH_TOKEN=your_auth_token
   

5. The Client constructor reads PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN automatically when called with no arguments.

Public API

PlivoGenericResponse

class PlivoGenericResponse {
  id: string;
  [key: string]: any;
  constructor(params: Record<string, any>, idString?: string): PlivoGenericResponse;
}

Base response wrapper returned by most resource operations. If idString is provided and exists in params, it is exposed as .id; otherwise falls back to request_uuid. Use this when inspecting raw API responses or building custom resource classes.

PlivoResource

class PlivoResource {
  constructor(action: string, klass: any, idField: string, request: Function): void;
  update(params: Record<string, any>, id?: string): Promise<this>;
  delete(params?: Record<string, any>): Promise<void>;
}

Abstract base for all Plivo resource objects. Provides update() and delete() as promise-returning methods that POST or DELETE to the REST API. Extend this when adding a custom resource module on top of the SDK source.

Client (from rest/client.js)

class Client {
  constructor(authId?: string, authToken?: string, options?: Record<string, any>): void;
  calls: CallInterface;
  messages: MessagesInterface;
  numbers: NumbersInterface;
  lookup: LookupInterface;
  conferences: ConferencesInterface;
  recordings: RecordingsInterface;
  accounts: AccountsInterface;
  // ... all other resource namespaces
}

The main entry point. Instantiate once and use its resource properties to interact with every Plivo API surface. Reads credentials from environment variables when called with no arguments.

Working examples

Scenario - Send an SMS message

Import the client from the local source copy and send a text message. The messages.create() method returns a promise resolving to a PlivoGenericResponse-compatible object with the message_uuid exposed as .id.

import { Client } from './src/plivo/rest/client.js';

const client = new Client(); // reads PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN

client.messages.create({
  src: '+14156667778',
  dst: '+14156667777',
  text: 'Hello from the embedded Plivo SDK source.',
}).then((response) => {
  console.log('Message UUID:', response.id);
}).catch((err) => {
  console.error('Send failed:', err.message);
});

Scenario - Make an outbound voice call

Use calls.create() to initiate a call. The third argument is the answer URL, which Plivo fetches to retrieve a Plivo XML response controlling the call.

import { Client } from './src/plivo/rest/client.js';

const client = new Client(
  process.env.PLIVO_AUTH_ID,
  process.env.PLIVO_AUTH_TOKEN
);

client.calls.create(
  '+14156667778',   // from
  '+14156667777',   // to
  'https://example.com/answer.xml'
).then((response) => {
  console.log('Call request UUID:', response.requestUuid);
}).catch(console.error);

Scenario - Generate Plivo XML for an answer webhook

Use the plivoxml utilities to build a Response document returned from your Express route. This avoids an external dependency on the npm package.

import { Response } from './src/plivo/utils/plivoxml.js';
import express from 'express';

const app = express();

app.post('/answer.xml', (_req, res) => {
  const plivoResponse = new Response();
  plivoResponse.addSpeak('Welcome to the Plivo demo. Goodbye.');
  res.set('Content-Type', 'text/xml');
  res.send(plivoResponse.toXML());
});

app.listen(3000, () => console.log('Webhook server on port 3000'));

Scenario - Look up a phone number

import { Client } from './src/plivo/rest/client.js';

const client = new Client();

client.lookup.get('+14156667778').then((info) => {
  console.log('Carrier:', info.carrier);
  console.log('Number type:', info.number_type);
}).catch(console.error);

File walkthrough

• base.js - Defines PlivoResource (CRUD scaffolding) and PlivoGenericResponse (response normalization); every resource module extends these.
• version.js - Exports the SDK version string used in User-Agent headers.
• resources/ - One file per Plivo API resource group; each exports a resource class and an interface class wired into Client.
• rest/client.js - Instantiates all resource interfaces, configures the HTTP transport, and exposes them as named properties on Client.
• rest/axios.js - Axios adapter that handles authentication headers, proxy support, and response/error normalization.
• rest/request.js - Constructs signed HTTP requests; used internally by the axios adapter.
• rest/utils.js - URL and parameter encoding helpers shared across the transport layer.
• utils/common.js - Generic extend and other object utilities used throughout the SDK.
• utils/exceptions.js - SDK-level exception classes for input validation errors.
• utils/jwt.js - Generates Plivo access tokens (for WebRTC clients) using jsonwebtoken.
• utils/plivoxml.js - Full TwiML-style XML builder: Response, Speak, Play, Dial, Record, etc.
• utils/security.js - v2 webhook signature validation helpers.
• utils/v3Security.js - v3 webhook signature validation (for voice v3 events).
• utils/template.js - WhatsApp template message payload builder.
• utils/restException.js - Wraps HTTP error responses into a typed exception.
• utils/interactive.js - Helpers for PHLO interactive node payloads.
• utils/location.js - Encodes geographic data for number search requests.
• utils/jsonStrinfigier.js - JSON serializer that handles BigInt and circular refs.

Common pitfalls and fixes

• ES module / CommonJS mismatch: The source uses import/export; if your project is CJS, either set "type":"module" or transpile with Babel (@babel/plugin-transform-modules-commonjs).
• Missing PLIVO_AUTH_ID / PLIVO_AUTH_TOKEN: Client() with no args will silently use undefined credentials and every request will return 401 - always verify env vars are exported before the process starts.
• request package deprecation warnings: The source depends on the legacy request package; pin it to ^2.88.2 and suppress deprecation warnings with NODE_NO_WARNINGS=1 if needed.
• Axios version conflict: The source targets Axios v0.x/v1.x; if your project already uses a conflicting major, install explicitly: npm install axios@1.
• Webhook signature validation: Always validate X-Plivo-Signature on incoming webhooks using utils/security.js or utils/v3Security.js; skipping this exposes your endpoint to spoofed requests.
• XML response content-type: Plivo fetches answer URLs and expects Content-Type: text/xml; forgetting to set the header causes call failures even when the XML body is correct.

Vibe-coding prompt template

I have embedded the Plivo Node.js SDK source (plivo@4.77.0) at `src/plivo/`
in my project. The USAGE.md at the project root documents all exports,
file responsibilities, and working examples.

Please help me integrate Plivo into my project step by step:

1. Read USAGE.md and `src/plivo/rest/client.js` to understand the Client API.
2. Read `src/plivo/utils/plivoxml.js` to understand the XML builder.
3. Add the required npm dependencies listed in USAGE.md ## Required dependencies.
4. Create a `src/plivoService.ts` that:
   - Instantiates Client using PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN env vars.
   - Exports a `sendSms(from, to, text)` function.
   - Exports a `makeCall(from, to, answerUrl)` function.
   - Exports an Express middleware `answerWebhook` that returns Plivo XML
     saying "Hello from my app." using the Response builder.
5. Wire `answerWebhook` into my Express app at POST /plivo/answer.
6. Do not install the `plivo` npm package; import only from `src/plivo/`.

License and credit

The Plivo Node.js SDK is released under the MIT License. See source/LICENSE if present in this block, or refer to the upstream repository. Upstream package: plivo on npm - source repository at github.com/plivo/plivo-node.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free