> ## 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.

# Outbound telephony

> Manage authorized outbound call intents independently of your speech model and media transport.

`@agentium/core/telephony` provides outbound call control: create, read, request hangup, and apply verified status events. Connect the carrier's configured answer/media route to your voice runtime separately.

It does not provide inbound routing, audio transport, carrier instruction documents, number provisioning, campaigns, or callback signature verification.

<Columns cols={2}>
  <Card title="Set up a carrier" icon="phone" href="/telephony/quickstart">Routes, identity, authorization, and persistence.</Card>
  <Card title="Run the local example" icon="code" href="/examples/telephony">Exercise the call lifecycle without credentials or dialing.</Card>
</Columns>

## Configure a route

The host supplies persistence, authorization, and credentials. This factory is an integration example; no call is placed by constructing the service.

```typescript theme={null}
import {
  OutboundCallService,
  createTwilioCallProvider,
  type CallAuthorization,
  type CallIntentStore,
} from "@agentium/core/telephony";

function createCalls(
  store: CallIntentStore,
  authorize: (request: CallAuthorization) => Promise<boolean>,
  authorization: () => Promise<string>,
) {
  return new OutboundCallService({
    store,
    authorize,
    providers: [createTwilioCallProvider({
      routeId: "support-us-v1",
      allowedFrom: ["+14155550102"],
      accountSid: "AC_YOUR_ACCOUNT",
      answerUrl: "https://voice.example.com/answer",
      statusCallbackUrl: "https://voice.example.com/status",
      authorization,
    })],
  });
}
```

`authorization` returns the complete authorization header from the host's secret store. Version route IDs when changing account, URLs, trunk, or room configuration.

## Create and track an intent

On the configured service, `create()` accepts verified identity, a persistent business-operation `intentId`, an approved `routeId`, and E.164 `to` / `from` numbers. The caller ID must be allowed by that route.

Persist the intent before dispatch. Reusing the same ID and payload returns the existing record; a changed payload conflicts. The host enforces consent, allowed destinations, calling hours, rate/spend limits, and route permissions through `authorize`. Every read, hangup, reconciliation, and event update rechecks authorization and ownership.

## Handle uncertain outcomes

A timeout or connection failure after dispatch can leave an **unknown** outcome. Do not create a new intent to retry an ambiguous call. Inspect `getIntent()`, verify provider records or callbacks, then use `reconcile()` to bind the original call reference.

`CallIntentStore.claim` must be atomic by tenant and intent; `compareAndSet` must enforce revision and immutable fields. `InMemoryCallIntentStore` is for local experiments, not cross-process recovery. The SDK does not promise exactly-once dialing.

`hangup()` is a separately authorized effect. Its acknowledgement does not prove the call has ended. Read provider state or apply a verified event to confirm completion. Local cancellation does not terminate a remote call automatically.

## Adapters

| Factory | Host configuration |
| - | - |
| [`createTwilioCallProvider`](/telephony/twilio) | Account, answer/status URLs, Basic authorization |
| [`createSignalWireCallProvider`](/telephony/signalwire) | Space URL, account, cXML answer URL, Basic authorization |
| [`createTelnyxCallProvider`](/telephony/telnyx) | Connection ID, webhook URL, Bearer authorization |
| [`createVonageCallProvider`](/telephony/vonage) | NCCO answer URL, event URL, application JWT |
| [`createExotelCallProvider`](/telephony/exotel) | Account, region, AgentStream WSS URL, Basic authorization |
| [`createLiveKitSipCallProvider`](/telephony/livekit) | Borrowed SIP/room SDK ports, stored trunk and room |

Verify callbacks with the provider's required signature/token scheme before calling `normalizeVerifiedEvent()`. Resolve tenant and intent from trusted application state before `applyVerifiedEvent()`. Parsing a payload is not authentication.

Adapter fixtures verify local wire contracts. They do not certify live PSTN interoperability or your account's media/callback configuration.


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