> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Telephony

> Public telephony signatures and configuration in @agentium/core 4.0.0.

Import these **35 exports** from `@agentium/core`. Read the [telephony guide](/voice/telephony) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## CallAuthorization

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallAuthorization {
    operation: "create" | "read" | "hangup" | "reconcile" | "event";
    identity: CallIdentity;
    request: OutboundCallRequest;
    ref?: CallReference;
}
```

Related: [`CallIdentity`](/api-reference/core/telephony#callidentity), [`CallReference`](/api-reference/core/telephony#callreference), [`OutboundCallRequest`](/api-reference/core/telephony#outboundcallrequest).

## CallErrorCode

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export type CallErrorCode = "invalid-input" | "unauthorized" | "conflict" | "not-found" | "capacity" | "aborted" | "timeout" | "provider-rejected" | "provider-unavailable" | "invalid-response" | "unresolved" | "store-unavailable";
```

## CallFailureOutcome

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export type CallFailureOutcome = "not-dispatched" | "rejected" | "unknown";
```

## CallHangupResult

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallHangupResult {
    ref: CallReference;
    /** Acceptance of the command is not terminal call evidence. */
    acknowledged: true;
}
```

Related: [`CallReference`](/api-reference/core/telephony#callreference).

## CallIdentity

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
/** Host-verified identity. Never populate this from a dial payload or webhook alone. */
export interface CallIdentity {
    tenantId: string;
    userId: string;
}
```

## CallIntentKey

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallIntentKey {
    tenantId: string;
    intentId: string;
}
```

## CallIntentRecord

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallIntentRecord {
    request: OutboundCallRequest;
    providerId: string;
    digest: string;
    revision: number;
    creation: "dispatching" | "accepted" | "rejected" | "unknown";
    snapshot?: CallSnapshot;
    hangup: "none" | "dispatching" | "acknowledged" | "unknown" | "rejected";
    errorCode?: CallErrorCode;
}
```

Related: [`CallErrorCode`](/api-reference/core/telephony#callerrorcode), [`CallSnapshot`](/api-reference/core/telephony#callsnapshot), [`OutboundCallRequest`](/api-reference/core/telephony#outboundcallrequest).

## CallIntentStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
/** Production implementations MUST make claim and revision CAS atomic and durable.
 * Never expire unresolved entries: eviction permits a duplicate outbound call.
 * Scope the unique index to tenantId + intentId, and enforce immutable request/digest/provider.
 */
export interface CallIntentStore {
    claim(record: CallIntentRecord): Promise<{
        claimed: boolean;
        record: CallIntentRecord;
    }>;
    get(key: CallIntentKey): Promise<CallIntentRecord | undefined>;
    compareAndSet(key: CallIntentKey, revision: number, next: CallIntentRecord): Promise<boolean>;
}
```

Related: [`CallIntentKey`](/api-reference/core/telephony#callintentkey), [`CallIntentRecord`](/api-reference/core/telephony#callintentrecord).

## CallOperationOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallOperationOptions {
    /** Aborts local waiting/network, never promises a remote hangup. */
    signal?: AbortSignal;
    timeoutMs?: number;
}
```

## CallReference

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallReference {
    providerId: string;
    routeId: string;
    callId: string;
    /** Only LiveKit uses these, with a configured room and deterministic participant. */
    roomName?: string;
    participantIdentity?: string;
}
```

## CallRouteConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallRouteConfig {
    routeId: string;
    /** A host allowlist, snapshotted when the provider is constructed. */
    allowedFrom: readonly string[];
}
```

## CallSnapshot

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface CallSnapshot {
    ref: CallReference;
    status: CallStatus;
    /** Bounded native status; no raw responses, credentials or recording URLs. */
    providerStatus: string;
}
```

Related: [`CallReference`](/api-reference/core/telephony#callreference), [`CallStatus`](/api-reference/core/telephony#callstatus).

## CallStatus

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export type CallStatus = "queued" | "ringing" | "active" | "completed" | "busy" | "no-answer" | "cancelled" | "failed" | "unknown";
```

## createExotelCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export declare function createExotelCallProvider(config: ExotelCallConfig): OutboundCallProvider;
```

Related: [`ExotelCallConfig`](/api-reference/core/telephony#exotelcallconfig), [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider).

## createLiveKitSipCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/livekit.ts)

```typescript theme={null}
export declare function createLiveKitSipCallProvider(config: LiveKitSipCallConfig): OutboundCallProvider;
```

Related: [`LiveKitSipCallConfig`](/api-reference/core/telephony#livekitsipcallconfig), [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider).

## createSignalWireCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
/** SignalWire Compatibility/cXML API; not the separate SWML Calling API. */
export declare function createSignalWireCallProvider(config: SignalWireCallConfig): OutboundCallProvider;
```

Related: [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider), [`SignalWireCallConfig`](/api-reference/core/telephony#signalwirecallconfig).

## createTelnyxCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export declare function createTelnyxCallProvider(config: TelnyxCallConfig): OutboundCallProvider;
```

Related: [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider), [`TelnyxCallConfig`](/api-reference/core/telephony#telnyxcallconfig).

## createTwilioCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
/** Twilio Programmable Voice Call resource (2010-04-01). */
export declare function createTwilioCallProvider(config: TwilioCallConfig): OutboundCallProvider;
```

Related: [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider), [`TwilioCallConfig`](/api-reference/core/telephony#twiliocallconfig).

## createVonageCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export declare function createVonageCallProvider(config: VonageCallConfig): OutboundCallProvider;
```

Related: [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider), [`VonageCallConfig`](/api-reference/core/telephony#vonagecallconfig).

## ExotelCallConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export interface ExotelCallConfig extends TelephonyHttpConfig {
    accountSid: string;
    region: "mumbai" | "singapore";
    /** AgentStream endpoint operated by the host. Media framing remains host-owned. */
    streamUrl: string;
    statusCallbackUrl?: string;
}
```

Related: [`TelephonyHttpConfig`](/api-reference/core/telephony#telephonyhttpconfig).

## InMemoryCallIntentStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/service.ts)

```typescript theme={null}
/** Local/test store only. It does not survive process loss or coordinate multiple workers. */
export declare class InMemoryCallIntentStore implements CallIntentStore {
    constructor(maxIntents?: number);
    claim(value: CallIntentRecord): Promise<{
        claimed: boolean;
        record: CallIntentRecord;
    }>;
    get(value: CallIntentKey): Promise<CallIntentRecord | undefined>;
    compareAndSet(value: CallIntentKey, revision: number, next: CallIntentRecord): Promise<boolean>;
}
```

Related: [`CallIntentKey`](/api-reference/core/telephony#callintentkey), [`CallIntentRecord`](/api-reference/core/telephony#callintentrecord), [`CallIntentStore`](/api-reference/core/telephony#callintentstore).

## LiveKitCallRoomPort

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/livekit.ts)

```typescript theme={null}
export interface LiveKitCallRoomPort {
    getParticipant(roomName: string, identity: string): Promise<{
        identity: string;
        attributes: Record<string, string>;
    }>;
    removeParticipant(roomName: string, identity: string): Promise<unknown>;
}
```

## LiveKitSipCallConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/livekit.ts)

```typescript theme={null}
export interface LiveKitSipCallConfig extends CallRouteConfig {
    sip: LiveKitSipCallPort;
    rooms: LiveKitCallRoomPort;
    trunkId: string;
    /** Host-owned room. Use one route per room, never accept a caller-supplied room. */
    roomName: string;
    timeoutMs?: number;
}
```

Related: [`CallRouteConfig`](/api-reference/core/telephony#callrouteconfig), [`LiveKitCallRoomPort`](/api-reference/core/telephony#livekitcallroomport), [`LiveKitSipCallPort`](/api-reference/core/telephony#livekitsipcallport).

## LiveKitSipCallPort

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/livekit.ts)

```typescript theme={null}
/** Structural subset of livekit-server-sdk SipClient; no SDK import or credentials. */
export interface LiveKitSipCallPort {
    createSipParticipant(trunkId: string, number: string, roomName: string, options: {
        participantIdentity: string;
        fromNumber: string;
        waitUntilAnswered: false;
        hidePhoneNumber: true;
    }): Promise<{
        participantIdentity: string;
        roomName: string;
        sipCallId: string;
    }>;
}
```

## NormalizedCallEvent

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface NormalizedCallEvent extends CallSnapshot {
    eventId?: string;
    occurredAt?: string;
}
```

Related: [`CallSnapshot`](/api-reference/core/telephony#callsnapshot).

## OutboundCallProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface OutboundCallProvider {
    readonly id: string;
    readonly routeId: string;
    readonly capabilities: Readonly<{
        transport: "http" | "livekit-sip";
        /** All supplied adapters require reconciliation after ambiguous dispatch. */
        automaticCreateRetry: false;
        callbackVerification: "host";
        hangup: "call" | "active-legs" | "sip-participant";
    }>;
    create(request: OutboundCallRequest, options?: CallOperationOptions): Promise<CallSnapshot>;
    get(ref: CallReference, options?: CallOperationOptions): Promise<CallSnapshot>;
    hangup(ref: CallReference, options?: CallOperationOptions): Promise<CallHangupResult>;
    /** Parse only AFTER the host verifies provider signature, account, freshness and replay. */
    normalizeVerifiedEvent(payload: unknown): NormalizedCallEvent;
}
```

Related: [`CallHangupResult`](/api-reference/core/telephony#callhangupresult), [`CallOperationOptions`](/api-reference/core/telephony#calloperationoptions), [`CallReference`](/api-reference/core/telephony#callreference), [`CallSnapshot`](/api-reference/core/telephony#callsnapshot), [`NormalizedCallEvent`](/api-reference/core/telephony#normalizedcallevent), [`OutboundCallRequest`](/api-reference/core/telephony#outboundcallrequest).

## OutboundCallRequest

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface OutboundCallRequest {
    /** Stable within the tenant; persisted before dispatch. Reuse only for identical input. */
    intentId: string;
    identity: CallIdentity;
    routeId: string;
    to: string;
    from: string;
}
```

Related: [`CallIdentity`](/api-reference/core/telephony#callidentity).

## OutboundCallService

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/service.ts)

```typescript theme={null}
export declare class OutboundCallService {
    constructor(config: OutboundCallServiceConfig);
    create(value: OutboundCallRequest, options?: CallOperationOptions): Promise<CallIntentRecord>;
    getIntent(identity: CallIdentity, intentId: string): Promise<CallIntentRecord>;
    get(identity: CallIdentity, intentId: string, options?: CallOperationOptions): Promise<CallIntentRecord>;
    hangup(identity: CallIdentity, intentId: string, options?: CallOperationOptions): Promise<CallIntentRecord>;
    /** Host must establish correspondence to the original intent independently (provider logs/callback).
     * A failed/unknown create is never retried here. Binding cannot replace a known call.
     */
    reconcile(identity: CallIdentity, intentId: string, ref: CallReference, options?: CallOperationOptions): Promise<CallIntentRecord>;
    /** The host verifies signatures/account/freshness before invoking; no HTTP webhook endpoint is exposed. */
    applyVerifiedEvent(identity: CallIdentity, intentId: string, event: NormalizedCallEvent): Promise<CallIntentRecord>;
}
```

Related: [`CallIdentity`](/api-reference/core/telephony#callidentity), [`CallIntentRecord`](/api-reference/core/telephony#callintentrecord), [`CallOperationOptions`](/api-reference/core/telephony#calloperationoptions), [`CallReference`](/api-reference/core/telephony#callreference), [`NormalizedCallEvent`](/api-reference/core/telephony#normalizedcallevent), [`OutboundCallRequest`](/api-reference/core/telephony#outboundcallrequest), [`OutboundCallServiceConfig`](/api-reference/core/telephony#outboundcallserviceconfig).

## OutboundCallServiceConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/service.ts)

```typescript theme={null}
export interface OutboundCallServiceConfig {
    providers: readonly OutboundCallProvider[];
    store: CallIntentStore;
    /** Required for every operation, including deduplicated reads and callbacks. */
    authorize: (request: CallAuthorization) => boolean | Promise<boolean>;
}
```

Related: [`CallAuthorization`](/api-reference/core/telephony#callauthorization), [`CallIntentStore`](/api-reference/core/telephony#callintentstore), [`OutboundCallProvider`](/api-reference/core/telephony#outboundcallprovider).

## SignalWireCallConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export interface SignalWireCallConfig extends TwilioCallConfig {
    spaceUrl: string;
}
```

Related: [`TwilioCallConfig`](/api-reference/core/telephony#twiliocallconfig).

## TelephonyError

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
/** Safe to log: does not retain raw provider errors, payloads, URLs or credential causes. */
export declare class TelephonyError extends Error {
    readonly code: CallErrorCode;
    readonly outcome: CallFailureOutcome;
    readonly httpStatus?: number | undefined;
    constructor(code: CallErrorCode, outcome: CallFailureOutcome, httpStatus?: number | undefined);
}
```

Related: [`CallErrorCode`](/api-reference/core/telephony#callerrorcode), [`CallFailureOutcome`](/api-reference/core/telephony#callfailureoutcome).

## TelephonyHttpConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/types.ts)

```typescript theme={null}
export interface TelephonyHttpConfig extends CallRouteConfig {
    /** Resolves a complete Authorization header; allows rotating Basic/Bearer credentials. */
    authorization: () => string | Promise<string>;
    fetch?: typeof globalThis.fetch;
    timeoutMs?: number;
}
```

Related: [`CallRouteConfig`](/api-reference/core/telephony#callrouteconfig).

## TelnyxCallConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export interface TelnyxCallConfig extends TelephonyHttpConfig {
    connectionId: string;
    webhookUrl?: string;
}
```

Related: [`TelephonyHttpConfig`](/api-reference/core/telephony#telephonyhttpconfig).

## TwilioCallConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export interface TwilioCallConfig extends TelephonyHttpConfig {
    accountSid: string;
    answerUrl: string;
    statusCallbackUrl?: string;
}
```

Related: [`TelephonyHttpConfig`](/api-reference/core/telephony#telephonyhttpconfig).

## VonageCallConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/telephony/http-providers.ts)

```typescript theme={null}
export interface VonageCallConfig extends TelephonyHttpConfig {
    answerUrl: string;
    eventUrl?: string;
    /** Official regional API origins may be selected by the host. */
    apiOrigin?: "https://api.nexmo.com" | "https://api-us.vonage.com" | "https://api-eu.vonage.com" | "https://api-ap.vonage.com";
}
```

Related: [`TelephonyHttpConfig`](/api-reference/core/telephony#telephonyhttpconfig).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.