Outbound telephony

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

Set up a carrier

Routes, identity, authorization, and persistence.

Run the local example

Exercise the call lifecycle without credentials or dialing.

Configure a route

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

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`	Account, answer/status URLs, Basic authorization
`createSignalWireCallProvider`	Space URL, account, cXML answer URL, Basic authorization
`createTelnyxCallProvider`	Connection ID, webhook URL, Bearer authorization
`createVonageCallProvider`	NCCO answer URL, event URL, application JWT
`createExotelCallProvider`	Account, region, AgentStream WSS URL, Basic authorization
`createLiveKitSipCallProvider`	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.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Outbound telephony

Set up a carrier

Run the local example

Configure a route

Create and track an intent

Handle uncertain outcomes

Adapters

Set up a carrier

Run the local example

​Configure a route

​Create and track an intent

​Handle uncertain outcomes

​Adapters

Configure a route

Create and track an intent

Handle uncertain outcomes

Adapters