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 two cases:
| Situation | Caller ID presented |
|---|---|
| A user places a call | The user's resolved outbound number |
| An inbound call is forwarded to an external number | The original caller |
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.
A transfer a user performs falls into one case or the other depending on its kind. A blind transfer of an inbound call to an external number forwards it. An attended transfer presents the transferring user, because its consultation was a call the user placed. See Calls a user transfers.
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. For a call a user places, 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. A temporary number is chosen only when no other number qualifies, so numbers ported in after the account was created take over from its temporary number without any change to settings.
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
The two kinds of transfer present different caller IDs. Each behaves the same from any device: a desk phone, a softphone, or the web and SDK clients.
Blind. The call is handed on as it is, so the target is shown the party being transferred. When that is a call that arrived on one of the account's numbers and the target is an external number, the transfer is a forward: it presents the original caller, exactly as a forwarded inbound call does. A call that arrived with no caller number is the exception: it presents an account number instead, as a Call Control API transfer does. Otherwise it presents an account number, resolved as a call the transferring user places. That includes a call the user placed to an external number, then blind-transferred to another external number.
A forwarded inbound call keeps its original from_number. When the party being transferred is one the user called, the transfer starts a new call from that party, so its from_number is the transferred party's own number rather than the user's.
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, so the target keeps seeing the transferring user. 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.
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 blind transfer a user performs to 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
When the call arrived on one of the account's numbers and carried a caller number, the transfer verb behaves as above, presenting the original caller, as a blind transfer a user performs does. This path and a blind transfer a user performs are 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.