Skip to main content

Class: PlivoVoiceProvider

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:737

Plivo voice call provider.

Uses the Plivo REST API v1 for outbound call control and HMAC-SHA256 for inbound webhook signature verification (v3 signature scheme).

Example​

const provider = new PlivoVoiceProvider({
  authId:    process.env.PLIVO_AUTH_ID!,
  authToken: process.env.PLIVO_AUTH_TOKEN!,
});

Implements​

Constructors​

Constructor​

new PlivoVoiceProvider(config): PlivoVoiceProvider

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:756

Parameters​

config​

PlivoVoiceProviderConfig

Plivo credentials and optional overrides.

Returns​

PlivoVoiceProvider

Properties​

name​

readonly name: "plivo"

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:739

Provider identifier, always 'plivo'.

Implementation of​

IVoiceCallProvider.name

Methods​

hangupCall()​

hangupCall(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:943

Hang up an active call using the Plivo Call DELETE endpoint.

Plivo uses HTTP DELETE to terminate a call (unlike Twilio's POST with Status=completed or Telnyx's POST to /actions/hangup). This is a RESTful convention where deleting the call resource ends the call.

Parameters​

input​

HangupCallInput

Contains the Plivo call_uuid to hang up.

Returns​

Promise<void>

Implementation of​

IVoiceCallProvider.hangupCall

initiateCall()​

initiateCall(input): Promise<InitiateCallResult>

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:908

Initiate an outbound call via the Plivo Call API.

POSTs a JSON body to /v1/Account/{authId}/Call/ with the caller, callee, and answer URL. Returns the request_uuid as the provider call ID.

Parameters​

input​

InitiateCallInput

Call initiation parameters (from/to numbers, webhook URL).

Returns​

Promise<InitiateCallResult>

Result containing the Plivo request_uuid on success.

Throws​

Never throws; returns { success: false, error: '...' } on failure.

Implementation of​

IVoiceCallProvider.initiateCall

parseWebhookEvent()​

parseWebhookEvent(ctx): WebhookParseResult

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:838

Parse a Plivo webhook into normalized NormalizedCallEvents.

Fields come from readPlivoRequest and plivoEventFields, as the signature check reads them: a GET callback's query, otherwise the URL-encoded or JSON body.

Plivo uses two naming conventions for the same fields:

  • PascalCase (CallUUID, CallStatus, Digits) in URL callbacks.
  • snake_case (call_uuid, call_status) in some API responses. Both are checked for maximum compatibility.

Parameters​

ctx​

WebhookContext

Raw webhook request context.

Returns​

WebhookParseResult

Parsed result containing zero or more normalized events.

Implementation of​

IVoiceCallProvider.parseWebhookEvent

playTts()​

playTts(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:962

Speak text into a live call using the Plivo Speak API.

POSTs a JSON body to /v1/Account/{authId}/Call/{callUuid}/Speak/ with the text, voice (default 'WOMAN'), and language (default 'en-US').

Parameters​

input​

PlayTtsInput

TTS parameters (text, optional voice, call ID).

Returns​

Promise<void>

Implementation of​

IVoiceCallProvider.playTts

verifyWebhook()​

verifyWebhook(ctx): WebhookVerificationResult

Defined in: packages/agentos/src/io/channels/telephony/providers/plivo.ts:779

Verify an incoming Plivo webhook request using HMAC-SHA256 (v3 scheme).

Computes computePlivoV3Signature over the request's method, URL and fields (read by readPlivoRequest, as parseWebhookEvent reads them) in both SDKs' texts (see PlivoCanonicalStyle) and compares each in constant time with every signature listed in X-Plivo-Signature-V3 and X-Plivo-Signature-Ma-V3.

Parameters​

ctx​

WebhookContext

Raw webhook request context.

Returns​

WebhookVerificationResult

Verification result with valid: true if a signature matches.

Implementation of​

IVoiceCallProvider.verifyWebhook