cid_choice and group_alias on a 3-way: setting caller ID from the API

When an agent opens a 3-way through the transfer API, the third party sees some caller ID number on their phone. By default that is whatever the campaign sets, but you do not have to accept the default. Two optional fields on the transfer_conference call, group_alias and cid_choice, let you decide what number shows up. They only apply to the values that place an outbound leg: DIAL_WITH_CUSTOMER and PARK_CUSTOMER_DIAL.

group_alias: a named caller ID

group_alias points at a preconfigured caller ID definition and uses its number for the outbound leg of the Three-way call. The alias has to exist and resolve to a valid number; if it does not, the call returns an error rather than dialing with a blank or bad CID (caller ID). This is the cleaner option when you maintain a set of approved outbound numbers and just want to choose one of them by name from your CRM.

cid_choice: pick the source

cid_choice is the alternate method. Instead of naming an alias, you tell VICIdial which existing number to reuse as the caller ID. It accepts four values: CAMPAIGN uses the campaign caller ID, AGENT_PHONE uses the agent phone number, CUSTOMER uses the customer number, and CUSTOM_CID uses a custom value. Passing an unrecognized value returns a cid_choice error, so typos fail loudly instead of dialing with the wrong number.

flowchart TD
  A[Open 3 way via API] --> B{How to set caller ID}
  B -->|Named alias| C[group_alias]
  B -->|Reuse a source| D[cid_choice]
  D --> E[CAMPAIGN]
  D --> F[AGENT_PHONE]
  D --> G[CUSTOMER]
  D --> H[CUSTOM_CID]
  C --> I[Outbound leg dials with chosen CID]
  E --> I
  F --> I
  G --> I
  H --> I

Knowing the four values keeps you from guessing. CAMPAIGN is the safe default that matches whatever the campaign already presents on outbound calls. AGENT_PHONE is useful when the third party should be able to call the agent back directly. CUSTOM_CID is the escape hatch for a specific number that none of the other sources would supply, like a dedicated transfer line. Each one resolves at the moment the outbound leg is placed, so the third party sees a number that is consistent with how you set the field.

The CUSTOMER option is the interesting one. Setting cid_choice to CUSTOMER makes the third party see the customer's own number, which is handy when the third party is a service that should recognize the customer rather than the call center. Just be careful with it, because presenting a number you do not control edges toward Caller ID spoofing territory, and the rules around that vary by region. Use it where it is legitimate and documented, not as a default.

Which one to use

Reach for group_alias when you have a managed list of approved numbers and want to choose by name. Reach for cid_choice when the right caller ID is simply one of the numbers already in play on the call. Both flow through the same Agent API request, so a CRM can set either one when it triggers the 3-way. For the broader story on what shows up on outbound 3-way legs, see 3-way call outbound caller ID, and the wider handoff context lives in our transfers and closers guide.

Caller ID is one of the easiest things to get wrong and one of the most visible when you do. If you want a dialer where outbound caller ID is managed cleanly across campaigns, see our pricing.