Outbound Caller ID
Which number the far end sees when a call leaves the platform, and what your integration receives on the call events.
How caller ID is decided
There are three cases:
| Situation | Caller ID presented |
|---|---|
| A user places a call | The user's resolved outbound number |
| A user transfers a call themselves | The user's resolved outbound number |
| An inbound call is forwarded to an external number | The original caller |
The first two rows are one case underneath: a transfer resolves exactly as if the transferring user had placed the call, so both land on the same number.
Forwarding is the case that differs. A call that arrives on one of the account's numbers and is then sent on to an external destination keeps the original caller, rather than presenting one of the account's own numbers.
The catch is that a user transferring that inbound call is not forwarding it. That falls under Calls a user transfers instead, so the external phone shows the transferring user's number and the original caller never reaches it.
Each case decides from_number as well as what rings. A forwarded call reports the original caller for its whole life, so an integration matching on from_number sees a customer's number rather than one of the account's own. In the first two cases from_number is the resolved outbound number.
Calls a user places
There is no external party to represent, so the call presents one of the account's own numbers, resolved in two steps:
- Take the user's outbound caller ID override if one is set, otherwise the account's default outbound number.
- Use that number only if it is active with outbound calling enabled. If it is not, or if neither is set, fall back to another active number on the account with outbound calling enabled.
Note that step 2 does not retry step 1's other candidate. A user override that is inactive or not outbound-enabled falls through to another active number rather than to the account default, so the call can present a number you did not expect.
The caller ID name is that number's configured caller ID name, falling back to the number itself when no name is set.
This covers calls dialed from a device and calls started through click-to-call, which resolve identically.
Calls a user transfers
A transfer a user performs themselves resolves the same way as a call the user places, landing on the same number, and never carries the original caller. This holds from any device — a desk phone, a softphone, or the web and SDK clients — and for both kinds of transfer. The reason differs between the two.
Warm (attended). The user calls the target and speaks to them before completing the transfer. That consultation is an ordinary outbound call, so it presented the user's number while the target's phone was ringing, before any transfer existed. Completing the transfer merges the two existing calls rather than placing a new one. The consultation call is merged rather than ended, so it emits no call.end; its terminating event is a call.transfer linking the two call ids.
Blind. A new outbound call is created at the moment of transfer and resolved against the transferring user, so from_number is that user's outbound number and the original caller is absent from the leg.
Blind transfer is the one case that is otherwise equivalent to forwarding but does not present the original caller. To reach an external destination showing the original caller, route the call with a dial plan, Find Me / Follow Me, or a ring group member rather than transferring it by hand.
Inbound calls forwarded to an external number
A call that arrived on a number the account owns presents the original caller, not the number it arrived on. Someone calling from +14155550101 into a main line that forwards to a mobile makes that mobile ring as +14155550101.
The arrival number still travels with the call as the number that forwarded it, so the carrier attributes the outbound leg to it and the call stays traceable to the number it came in on.
The caller's name carries across the same way, including the number's caller ID prefix if one is configured, so a call arriving on a number prefixed [Acme] reaches the destination as [Acme] John Smith. Whether a name is displayed at all is up to the receiving carrier.
This covers every path that forwards an inbound call onward:
- A dial plan's
external_dialnode - Find Me / Follow Me, where a user's step is an external number
- A ring group with an external number as a member
- Ring All Users, where a user's Find Me / Follow Me reaches an external number
- A call queue reaching an agent at an external number
- A transfer issued through the Call Control API
Ring groups, Ring All Users and call queues expand only the first step of a user's Find Me / Follow Me. An external number in a later step is reached only when a call goes to that user directly.
A call qualifies only if it arrived on a number the account owns. An internal caller (an extension, or a WebRTC user) never qualifies, so a call that starts internally and is routed outward always presents an account number.
One exception to the resolution order: when an internal call reaches a dial plan's external_dial node, it presents an active number with outbound calling enabled directly, consulting neither the user override nor the account default.
Transfers through the Call Control API
The transfer verb is the one transfer that forwards. When the call arrived on one of the account's numbers and carried a caller number, it behaves as above, presenting the original caller — unlike a transfer a user performs. This path is stricter than the other forwarding paths above: an inbound call with no caller number falls back to the account number rather than forwarding.
Otherwise it resolves as a call a user places does, but without the user override: the account's default outbound number, falling back to another active number with outbound calling enabled. Two differences from a call a user places:
- The user's own override is never consulted, even when one is set.
- If neither resolves, the transfer is refused rather than connected. A call is never sent out without an attributable number.
The dial verb originates a fresh call rather than redirecting an existing one, so it always presents the account number and never forwards the inbound caller.
Call forwarding set on a phone
Forwarding configured on a desk phone is performed by the phone itself, not the platform, so it does not go through the resolution described here. A ring group can suppress it with ignore_forwarding, which treats a redirecting member as busy. See Ring Groups.