Tracker postbacks & conversions

Conversions close the loop between an SMS and a business result: a recipient clicked your link, registered, deposited — and your tracker reports it back.

Ingestion endpoints

Public action/conversion ingestion requires the X-Api-Token header on every request:

Endpoint	Notes
GET /api/v1/track	Primary tracker endpoint
POST /api/v1/callback/action	JSON callback variant
GET /api/v1/action/track	Deprecated
POST /action	Legacy

Missing or invalid tokens return HTTP 401 before any side effect — no postback, webhook or database write happens. Tokens are validated against your current tracker token (and the unexpired previous one, so rotation is safe).

Note

Your tracker token is available in the portal. It is separate from API keys — scoped only to conversion ingestion.

Passing our click id to your tracker

Inbound conversions are attributed by code — the id of the short-link click that produced them. To get that id into your tracker, add the {clickid} placeholder to any sub parameter of the destination URL you shorten:

https://tracker.example.com/click?pid=18&sub5={clickid}

On every click the redirect replaces {clickid} (raw or percent-encoded) with the short code before sending the visitor on, so your tracker captures it. When a lead or sale happens, echo it back:

GET /api/v1/track?code=<captured clickid>&type=lead&revenue=25.00
X-Api-Token: <your tracker token>

type accepts any of your enabled action types — lead and sale ship as defaults since July 2026, but must be enabled in the portal’s Action Types settings before they appear as report columns (registration, deposit, ftd, … work the same way). If your CRM has no click context, POST to /api/v1/callback/action with the recipient’s phone instead.

URL placeholders for outgoing postbacks

When 23 Telecom calls your tracker (conversion/delivery postbacks), you can embed dynamic values in the configured URL:

https://tracker.example.com/postback?phone={phone}&status={status}&cost={cost}

Becomes:

https://tracker.example.com/postback?phone=%2B14155551234&status=DELIVRD&cost=0.0085

Available placeholders:

{message_id} {phone} {recipient} {sender_id} {cost}
{status} {status_code} {num_parts} {timestamp} {telecom_message_id}

The JSON body is still POSTed regardless of URL placeholders — placeholders exist for trackers that only read query strings.

Postback URL delivery

Tracker postbacks are unsigned: they do not include X-Webhook-Signature. Each request includes X-Event-Type; its User-Agent is 23Telecom-Postback/1.0 (the adjacent fragments form one value). It is sent once with no retry and may be dropped when the bounded delivery pool is full. If you need authenticated event delivery, use signed webhooks instead.

Conversion webhooks

Recorded conversions also fire the conversion webhook to your conversion_url, with your selected conversion_fields. Use this to mirror conversion data into your own analytics in real time.