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

# Callbacks and call recovery

> Verify provider events, preserve intent ownership, and reconcile uncertain call creation.

Treat call creation, hangup acknowledgement, and terminal status as different facts. A network timeout cannot tell you whether the carrier accepted a call.

## Accept a verified event

Your HTTP endpoint must verify the original request using the provider's signature/token rules, including its account, freshness, and replay checks. Preserve the raw body or canonical URL where the provider requires them. Only then normalize the payload.

This host integration function deliberately accepts an already verified payload and an identity/intent resolved from trusted application records. It does not implement an HTTP authentication boundary.

```typescript theme={null}
import type {
  CallIdentity, OutboundCallProvider, OutboundCallService,
} from "@agentium/core/telephony";

export async function recordVerifiedCallback(
  calls: OutboundCallService,
  provider: OutboundCallProvider,
  identity: CallIdentity,
  intentId: string,
  verifiedPayload: unknown,
) {
  const event = provider.normalizeVerifiedEvent(verifiedPayload);
  return calls.applyVerifiedEvent(identity, intentId, event);
}
```

`normalizeVerifiedEvent()` parses data; it does not verify a signature. The service checks reference ownership and does not let late events regress an established terminal status. An event for an intent without a known call reference needs reconciliation first.

## Recover an ambiguous create

1. Keep the original business intent ID. Read `getIntent(identity, intentId)`.
2. Find the original call through trusted carrier records or a verified callback. Match account, route, destination, caller ID, and business operation in your host.
3. Call `reconcile(identity, intentId, ref)` with that verified reference. Agentium reads the provider to bind the reference to the unresolved intent.
4. Continue status tracking or issue a separately authorized hangup. Create a new intent only after the host has established that a new call is intended.

`reconcile` rejects intents that already have a snapshot or were definitively rejected. Agentium does not search your carrier account for you.

| Outcome | Meaning | Host action |
| - | - | - |
| `not-dispatched` | This operation failed before dispatch | Fix input, authorization, or local state |
| `rejected` | Provider rejection was established | Handle that rejection; do not treat it as a timeout |
| `unknown` | Remote effects are uncertain | Preserve intent and reconcile |

Cancellation aborts local waiting/network work. It does not promise remote hangup. A hangup acknowledgement also needs a subsequent read or verified event to establish a terminal status.


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