Macros

After this page you can write any template the platform accepts and know exactly what will be on the wire. A macro is a placeholder of the form {{namespace.field}}. Wherever you supply a template — a pixel URL or body, a custom header, the bid request of an external RTB target, a delivery endpoint's SIP headers — macros are replaced with values from the call in hand.

There is one vocabulary, listed below, and the platform uses it everywhere. What changes between places is not which macros exist but how their values are encoded, and whether caller identity is allowed through at all.

The six rules

1. A macro is a namespace and a field. {{call.ref}}, {{caller.state}}, {{tag.gclid}}. There is no arithmetic, no conditionals, no functions and nothing that could be made to run — the whole language is "look up this value".
2. A missing value expands to an empty string, never to its own braces. A macro that has no value for this call, and a macro that does not exist at all, both come out as nothing. A partner's parser copes with &value=; it does not cope with &value={{call.revnue}}.
3. Values are encoded for where they land. Percent-encoded in a URL, JSON-string-escaped in a JSON body, verbatim in a SIP header or a whisper. You never escape anything yourself.
4. Caller identity never reaches a URL. In a URL the caller-number macros become {{caller.hash}} instead. See Identity in a URL.
5. Spaces inside the braces are fine. {{ call.id }} and {{call.id}} are the same macro.
6. Three opening braces send a literal {{ through, for a partner whose own template language uses braces: {{{call.id}} arrives as {{call.id}}.

Event

Which delivery this is. Useful in a body a partner de-duplicates on, and in a URL when one endpoint serves several events.

Call

Caller

caller.suffix is on the hashed list and the area code is not, which looks inconsistent until you count: the number is only three macros long, and {{caller.areaCode}}{{caller.prefix}}{{caller.suffix}} would rebuild it in full in a query string. The area code and the exchange say roughly where a caller is and stay usable; the last four digits are what make it that caller, so they are the part withheld.

Number, campaign, publisher, buyer and target

Tags

• The key may contain dots. Everything after tag. is the key, so {{tag.utm.source}} reads the tag literally named utm.source.
• Only scalar values expand. A tag whose value is an object or an array comes out empty rather than as [object Object].
• A tag that is not on this call is empty, like any other missing value. There is no way to tell "no such tag" from "tag with an empty value", and a partner should not need to.
• In a URL, tags expand on your own pixels and are empty in a template a buyer wrote. See below.

Time

Bidding

These describe an auction. They belong in an external RTB target's bid template and in a delivery endpoint's templates, where there is an auction to describe. They are not available to a pixel — a tracking event has no auction behind it, so they would all be empty, and a pixel that uses one is refused when you save it.

The three modes

The same template expands differently depending on what it is. You do not choose the mode; where the template lives chooses it.

Identity in a URL

A URL ends up in access logs, referrer headers and analytics pipelines on both sides. A phone number there is a disclosure nobody chose, so it is prevented in code rather than discouraged in a note.

• There is no opt-in for a pixel. A pixel URL never carries a caller's number, whatever you type.
• A POST body is not a URL — it is not logged by intermediaries — so identity expands there in full. If a partner needs the real number, send it in a body.
• The hash is the same for the same caller every time, so a partner can de-duplicate or suppress on it without ever holding the number.
• The console tells you when a template you are saving is affected, rather than letting you find out from a partner's empty field.

Worked example: the same template, two ways

A conversion postback to an ad network, fired on call.converted for the call in the payload sample. As a GET pixel, its URL is expanded in URL mode:

https://ads.example.com/conversion?click={{tag.gclid}}&value={{call.revenue}}&ref={{call.ref}}&caller={{caller.e164}}

https://ads.example.com/conversion?click=Cj0KCQjw&value=42.00&ref=CA-482137&caller=9c1185a5c5e9fc54

{{tag.gclid}} expanded because it is your own pixel and the tag is yours. {{call.revenue}} arrived as dollars. {{caller.e164}} became the hash without being asked — the network gets something it can de-duplicate on and nothing it can dial.

The same facts as a POST body to a partner's API, expanded in JSON mode, where identity is allowed:

{
  "external_id": "{{call.ref}}",
  "phone": "{{caller.e164}}",
  "state": "{{caller.state}}",
  "seconds": {{call.duration}},
  "payout": "{{call.payout}}",
  "source": "{{publisher.name}}",
  "click_id": "{{tag.gclid}}"
}

{
  "external_id": "CA-482137",
  "phone": "+14155550142",
  "state": "CA",
  "seconds": 184,
  "payout": "27.50",
  "source": "Northwind Media",
  "click_id": "Cj0KCQjw"
}

seconds is unquoted because {{call.duration}} is a whole number; everything else is quoted because it is a string. Had publisher.name contained a quotation mark, JSON mode would have escaped it and the body would still parse.

When a macro comes out empty

An empty field in a partner's log is almost always one of these, in roughly this order of likelihood:

• The call genuinely has no such value. {{publisher.name}} on your own media, {{buyer.name}} on an unrouted call, {{call.answered_at}} on a call nobody answered.
• It is one of the ping-only fields — {{caller.city}}, {{caller.zip}}, {{publisher.ref}} — on a call that was dialled rather than won at auction. Nobody sent them, so there is nothing to expand.
• The tag is not on this call. Check the call's own tags in the call log; a tag captured by DNI only exists if the visitor's session was matched.
• It is a tag in a URL written by a buyer, where tags are withheld by design.
• The event fired too early. Money and duration are 0 before settlement. A pixel on call.connected reporting value=0.00 is working correctly and firing on the wrong event.

What it is not is a typo: a misspelt macro is refused when a pixel is saved, so a template that saved has only real macros in it.

Next steps