Skip to main content

Interface: IVoiceCallProvider

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:119

Core interface for telephony providers.

Implementations wrap provider-specific SDKs (Twilio REST API, Telnyx Call Control v2, Plivo Voice API) and normalize all interactions to this contract.

Example​

class TwilioProvider implements IVoiceCallProvider {
  readonly name = 'twilio';

  async initiateCall(input: InitiateCallInput): Promise<InitiateCallResult> {
    const call = await this.client.calls.create({
      to: input.toNumber,
      from: input.fromNumber,
      url: input.webhookUrl,
      statusCallback: input.statusCallbackUrl,
    });
    return { providerCallId: call.sid, success: true };
  }
  // ...
}

Properties​

name​

readonly name: VoiceProviderName

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:121

Provider identifier.

webhookIdentity?​

readonly optional webhookIdentity: "legacy" | "stable-v1"

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:124

Stable normalized identity contract required by durable callback processing.

Methods​

hangupCall()​

hangupCall(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:157

Hang up an active call.

Parameters​

input​

HangupCallInput

Returns​

Promise<void>

initiateCall()​

initiateCall(input): Promise<InitiateCallResult>

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:152

Initiate an outbound phone call. For 'notify' mode, the provider generates TwiML/SSML to speak the message and hang up. For 'conversation' mode, the provider sets up a bidirectional media stream.

Parameters​

input​

InitiateCallInput

Returns​

Promise<InitiateCallResult>

parseWebhookEvent()​

parseWebhookEvent(ctx): WebhookParseResult

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:142

Parse a verified webhook payload into normalized call events. Transforms provider-specific event formats into the common NormalizedCallEvent discriminated union.

Parameters​

ctx​

WebhookContext

Returns​

WebhookParseResult

playTts()?​

optional playTts(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:164

Play TTS audio into an active call (non-streaming). Used by providers that support in-call TTS via their API (e.g., Twilio's verb, Telnyx speak command).

Parameters​

input​

PlayTtsInput

Returns​

Promise<void>

startListening()?​

optional startListening(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:170

Start STT listening on an active call (non-streaming). Used by providers that support in-call speech recognition.

Parameters​

input​

StartListeningInput

Returns​

Promise<void>

stopListening()?​

optional stopListening(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:175

Stop STT listening on an active call.

Parameters​

input​

StopListeningInput

Returns​

Promise<void>

verifyWebhook()​

verifyWebhook(ctx): WebhookVerificationResult

Defined in: packages/agentos/src/io/channels/telephony/IVoiceCallProvider.ts:135

Verify the authenticity of an incoming webhook request. Each provider has its own signature scheme:

  • Twilio: HMAC-SHA1 signature header
  • Telnyx: Ed25519 public key verification
  • Plivo: HMAC-SHA256 verification

Parameters​

ctx​

WebhookContext

Returns​

WebhookVerificationResult