ConfigManual
Asterisk

Setting Caller ID in Asterisk: CALLERID, ANI, and Why the Carrier Overrides You

Himanshu Pal

Himanshu Pal

The function

Caller ID in Asterisk is handled by the CALLERID() function, which gets or sets caller ID data on the channel. It can be both read from and written to, which makes it the tool for both inspecting an incoming call and shaping an outgoing one.

The three forms you will use most:

${CALLERID(num)}    ; the number
${CALLERID(name)}   ; the display name
${CALLERID(all)}    ; both, as: Name <number>

Setting outbound caller ID before dialling a trunk:

exten => _0X.,1,Set(CALLERID(all)="Sales Team" <2095551212>)
 same => n,Dial(PJSIP/trunk/${EXTEN},30)
 same => n,Hangup()

Note the format of all: the name in quotes, the number in angle brackets. Getting that syntax wrong is a common cause of caller ID that silently does not apply.

The fields beyond num and name

Caller ID is richer than most people realise. The function supports a long list of datatypes, and a few matter in real deployments:

  • num and name — the number and display name presented to the callee.
  • ANI — Announced Number Identification, the billing number that made the call. It is usually the same as num but it can legitimately differ, and some carriers bill or authenticate against ANI rather than the displayed number.
  • DNID — Dialed Number IDentifier: the number that was actually dialled. Useful on a trunk carrying many DIDs, where you need to know which one the caller rang.
  • RDNIS — Redirected Dialed Number Identification Service: where the call was originally sent before being forwarded. This is how you tell that a call reached you via a diverted number, which matters for voicemail routing and for reporting.
  • pres — the presentation indicator, controlling whether the number may be displayed at all.

There are also privacy variants (priv-*), subaddress fields, and per-field validity and character-set indicators. You rarely need them, but knowing they exist saves guessing when a carrier asks about one.

The distinction between num and ANI is the one that catches people. If a carrier rejects your calls with a policy error despite a correct displayed number, the ANI may be what they are actually checking.

Presentation: asking for the number to be withheld

The presentation indicator says whether the caller ID should be shown. Asterisk accepts values including allowed, prohib and unavailable, plus screened variants such as allowed_passed_screen and prohib_not_screened.

exten => _9X.,1,Set(CALLERID(pres)=prohib)
 same => n,Dial(PJSIP/trunk/${EXTEN})

Treat this as a request rather than a guarantee. Whether the far end honours it is outside your control, and emergency services see the number regardless — as they should.

Why the number you set is not the number displayed

This is the most common frustration with outbound caller ID, and the answer is usually not in your configuration.

Carriers routinely override caller ID. Most will only present numbers you have verified as yours, and substitute your main account number for anything else. This is deliberate: unrestricted caller ID setting is exactly how spoofing and fraud work, and regulators in most countries now require carriers to police it.

So if your carefully set number is being replaced, the sequence to check is:

  1. Is the number registered with the carrier? Most require each presented number to be on your account or explicitly authorised.
  2. Is the format right? Many carriers require full E.164 with country code and reject or rewrite national formats.
  3. Are you setting it before Dial()? Setting caller ID after the call has been placed does nothing.
  4. Is something downstream resetting it? A trunk configuration or an SBC can override what the dialplan set.

Ask the carrier what they actually accept rather than experimenting — this is one of the areas where guessing wastes the most time.

Practical patterns

Per-department outbound identity — present the right number depending on who is calling:

[internal-sales]
exten => _0X.,1,Set(CALLERID(all)="Sales" <441632960111>)
 same => n,Goto(outbound,${EXTEN},1)

[internal-support]
exten => _0X.,1,Set(CALLERID(all)="Support" <441632960222>)
 same => n,Goto(outbound,${EXTEN},1)

Tagging inbound calls so agents see context before answering:

exten => _X.,1,Set(CALLERID(name)=VIP-${CALLERID(name)})
 same => n,Queue(support)

Recording the original destination of a forwarded call using RDNIS, which is otherwise lost:

exten => _X.,1,Set(CDR(userfield)=via-${CALLERID(RDNIS)})

Frequently asked questions

Why is my outbound caller ID being replaced?

The carrier is overriding it — normally because the number is not verified on your account, or the format is not what they accept. Carriers police caller ID to prevent spoofing, and this is not something you can configure around.

What is the difference between num and ANI?

num is the number presented to the person you are calling. ANI is the billing number that made the call. They are usually identical but can differ, and some carriers authenticate or bill on ANI.

How do I find out which of my numbers was dialled?

Use DNID, the Dialed Number IDentifier. On a trunk carrying multiple DIDs it tells you which one the caller rang.

How do I withhold caller ID?

Set CALLERID(pres) to prohib before dialling. Whether it is honoured depends on the far end, and emergency services will still receive the number.

asteriskcalleridanidialplantrunk