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

# Twilio call adapter

> Configure Twilio outbound calls, credentials, media routing, and status handling.

Use `createTwilioCallProvider` from `@agentium/core/telephony`. It implements outbound create, read, hangup, and normalization of already verified status events.

## Before you connect

An owned caller ID, account SID, HTTPS TwiML answer endpoint, and optional HTTPS status callback. Return a complete Basic header from `authorization()`.

```bash theme={null}
npm install @agentium/core@4.0.0
```

This adapter uses HTTP and does not require the carrier's Node SDK. You may still use that SDK in your host to validate callbacks or issue application credentials.

## Configure the provider

This complete factory accepts host-owned configuration. Constructing it does not place a call. Read secrets and route values from your server configuration before calling it.

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

export function createProvider(config: TwilioCallConfig) {
  return createTwilioCallProvider({
    routeId: config.routeId,
    allowedFrom: config.allowedFrom,
    accountSid: config.accountSid,
    answerUrl: config.answerUrl,
    statusCallbackUrl: config.statusCallbackUrl,
    authorization: config.authorization,
    timeoutMs: config.timeoutMs,
  });
}
```

`routeId` identifies a fixed host-approved route. Version it when the account or destination infrastructure changes. `allowedFrom` is a snapshot of permitted E.164 caller IDs. `authorization` returns the full HTTP header and can read rotating credentials on each request.

Pass this provider to [OutboundCallService](/telephony/quickstart) with an intent store and an authorization function. The [call lifecycle recipe](/examples/telephony) exercises create, deduplication, read, and hangup without dialing.

## Provider behavior

Uses the Calls REST resource. Hangup reads the call first: queued/ringing calls are cancelled; active calls are completed. Your answer endpoint returns TwiML and establishes any media stream.

## Status and failure handling

Verify provider signature, account, freshness, and replay constraints before normalizing a callback. Resolve tenant and intent from trusted storage; see [callbacks and recovery](/telephony/callbacks).

Create is never automatically retried by this adapter. A timeout after dispatch may mean the carrier accepted the call. Keep the original intent and reconcile it before attempting another effect. Hangup acknowledgement is not a terminal call status.

See the provider's [call API documentation](https://www.twilio.com/docs/voice/api/call-resource) for account provisioning, answer documents, and media configuration. Agentium's [telephony contract](/api-reference/core/telephony) describes its neutral request, status, and error types.


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