Skip to main content

Class: PlivoVoiceProvider

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

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:769

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:749

Provider identifier, always 'plivo'.

Implementation of​

IVoiceCallProvider.name

Accessors​

webhookIdentity​

Get Signature​

get webhookIdentity(): "legacy" | "stable-v1"

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

Declares whether callback ids satisfy the durable manager contract.

Returns​

"legacy" | "stable-v1"

Stable normalized identity contract required by durable callback processing.

Implementation of​

IVoiceCallProvider.webhookIdentity

Methods​

hangupCall()​

hangupCall(input): Promise<void>

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

Cancels pending requests through Request; real call ids use the existing Call endpoint.

Parameters​

input​

HangupCallInput

Returns​

Promise<void>

Implementation of​

IVoiceCallProvider.hangupCall


initiateCall()​

initiateCall(input): Promise<InitiateCallResult>

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

Initiates a call, retaining a separate request id until a verified callback binds the call leg.

Parameters​

input​

InitiateCallInput

Returns​

Promise<InitiateCallResult>

Implementation of​

IVoiceCallProvider.initiateCall


parseWebhookEvent()​

parseWebhookEvent(ctx): WebhookParseResult

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

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.

In carrier mode each event carries a stable id from stableCarrierEvents and the callback's RequestUUID; a DTMF event's occurrence is the signed SequenceNumber or Timestamp, else the callback URL's event_key, and a DTMF event with none throws.

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:940

Refuses pending request ids; speaks only to a bound carrier call.

Parameters​

input​

PlayTtsInput

Returns​

Promise<void>

Implementation of​

IVoiceCallProvider.playTts


verifyWebhook()​

verifyWebhook(ctx): WebhookVerificationResult

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

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