Using Link Tracking Service in Messages

Message link tracking and Conversion

Messages that contain URLs can also contain a keyword (#track) that will trigger a URL replacement in the message. The first time when the end user clicks the tracked URL, the Syniverse SMS API service will notify the Customer that a "click-thru" and then a "conversion" event has taken place.

A conversion is a record of a response from a user to a message, not represented by a direct reply, but rather by recipient interaction (behavior) For example, following a URL provided in an SMS message is a conversion event. Replying to a message can also be a conversion event. Each conversion event is associated with a recipient disposition (e.g. whether the response was positive or negative.) Conversion events can also be posted by the enterprise/application if these events originate outside of the Syniverse Communication API service’s awareness. In that context, we provide an optional service that customer can subscribe to which can still track this and provide reporting and analytics based on them.

How this works:

Our Communication Gateway offers Link Tracking capabilities for Message Requests with a URL shortening service. URLs within messages can be flagged for tracking. For tracked URLs, the service will replace the URL with a secured shortened URL (, that points to the link tracking service. The first-time when the end user navigates to the tracked URL, the link tracking service will update the message status to "CLICKTHRU" to show that the link was clicked. There will also be a Message State Change event generated and sent to any delivery configuration endpoints for this application. Subsequent clicks on the tracked URL do not trigger any notification and only opens the link's URL.

In order to flag a URL to be tracked, the url is passed as an argument to the #track directive in the message body. 

Here is a sample message request with a tracked URL:


curl -X POST \ \
  -H 'Authorization: Bearer [TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{"from":"
channel:Bxn9SHBYhl89KnXXXXXXXX ",

"to":["+1408555XXXX"],"body":"Hello Kola, thanks for your patronage, please visit us at #track(\"\") cool information for you for new information"}'

Here is the message received on the Handset:

"Hello Kola, thanks for your patronage, please visit us at for new information"

Please note that when using the message console UI, be sure to remove the escape in the sample url above.

State Event for Messages:

Your application will receive several event states with a final one of “CLICKTHRU” assuming you have a webhook setup. The CLICKTHRU state will be part of several fields in the JSON posted to your application via your webhook and this state will only be received once the end-user clicks on the shortened link in the message

Sample JSON for a CLICKTHRU Event State:

"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"previous_state": "DELIVERED",
"message_request_id": "9E0qhwPclVXnqMjbaYF4J5",
"message_id": "uFAbXDeSXGMzgK5Qoxw5g2",
"to_address": "+1408555XXXX",
"has_attachment": false,
"reason_description": "SUCCESS",
"application_id": 631,
"reason_code": "200",
"sender_id_alias": "Gladiator",
"company-id": 92,
"sender_id_id": "EjihJOXWJE24OXXXXXXXXX",
"external_message_request_id": "",
"new_state": "CLICKTHRU",
"fragments_count": 1,
"from_address": "1877555XXXX",
"mt_price": 0.0095
Was this article helpful?
0 out of 0 found this helpful


Article is closed for comments.