docs: explain Telnyx warm-transfer caller ID preservation

[piyush-gambhir]

A warm transfer creates a new outbound call to the human agent. Applications using Telnyx may want that recipient to see the original customer's number, so caller-ID-based identification and lookup can continue through the handoff.

The SDK already exposes the caller number and SIP headers needed for this. This PR documents how to use those options together, without introducing a provider flag or new runtime behavior.

What this adds

• An inbound A → Telnyx B → supervisor C example using the customer's number and a Diversion header identifying B.
• Instructions to obtain normalized numbers from trusted per-call context and select the Telnyx outbound trunk.
• The requirement to keep the original inbound call active, plus troubleshooting for 403 Unverified origination number D51.
• A manual live-call verification checklist, including caller-ID display and successful consultation/transfer.

The carrier requirements are grounded in Telnyx's external call transfer documentation. Telnyx checks both the active inbound call and the diversion information; a header alone does not authorize an arbitrary caller ID.

This contribution is independent of the Twilio CallToken PRs and is based directly on main.

Validation

• Checked the TypeScript snippet's syntax and option names against WarmTransferTaskOptions on upstream main.
• Ran the repository Prettier and ESLint commands directly with the existing toolchain; lint passed with 193 existing warnings. Unrelated formatter-only changes were excluded.
• Focused documentation formatting and git diff --check passed.
• Added a pointer from the existing warm-transfer example to the guide.
• No runtime behavior changed; no live Telnyx call was placed. Carrier acceptance and caller-ID presentation remain live-test steps.

Live QA status

Telnyx live carrier validation has not been completed. The available QA environment has a configured LiveKit Telnyx outbound trunk but lacks the Telnyx API credentials needed to provision/control a dedicated inbound test number. The separate Twilio CallToken live tests do not validate this SIP Diversion flow. Carrier acceptance and caller-ID presentation remain outstanding.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0d0e39a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.