Enterprise Communications APIGet StartedReference
Reference
Select ProductPortal

URL Click Forwarding

If your system needs to know whether URLs inserted into SMS messages have been clicked, check how long the clicker took between receiving the message and clicking the URL or discover details about the clicker's operating system, you can have details forwarded to a URL of your choosing.

📘

Enabling URL Click Forwarding

Please contact you account manager or support to setup your URL click forwarding URL. You will need to provide your URL and whether you would like JSON or XML data.

Security

Although you can specify an HTTP URL, we recommend that you specify HTTPS to ensure data security. We use only TLS 2048 bit encryption. We do not support SSL 2.0 or 3.0. Note that we cannot accommodate self signed certificates.

Tracked URL Click Handler

We forward click-through events as an HTTP POST containing either JSON or XML. Each POST contains a batch of up to a maximum of 100 click events per submission, therefore you may receive any number of click details from 1 to 100 per request and possibly multiple requests. We attempt to serialise the requests to minimise contention for your servers, but we run a load balanced environment and if we receive multiple clicks across several servers there is a possibility of simultaneous requests arriving on your platform.

Your URL handler must be publicly accessible and be capable of processing the received message within 10 seconds. Once you have processed you should return an HTTP 200 OK response. If we don’t receive a 200 OK response within 10 seconds the submission will be considered failed and be retried later.

We strongly recommend a buffer and then process model to ensure that you can respond successfully within the 10 seconds window. In this model you would accept the forwarding click through information and queue it into queuing system such as MSMQ, ActiveMQ or RabbitMQ for processing in batches.

Body

PropertyDescription
RequestIdentifier*A unique identifier for this request
ClickDetails*An array of 1 - 100 ClickDetail objects

ClickDetail Object

TrackingUrlId*A unique identifier for the shortened URL. This has a different value for each recipient of the URL
UserId*The Id of the user who requested the tracked URL the click relates to
PhoneNumber*The international format phone number the click relates to e.g. for the UK: 447709000000
TrackedUrl*The tracked URL the click relates to
ClientIdentifierIf the message was sent via Campaign Manager, ClientIdentifier contains the campaign name
ClientRefContains the messageId of the message that contained the URL
UserAgent*The user agent string of the clicker
ReferrerThe referrer IP address if available
DeviceNameThe clicker's handset device name if available (not widely supported in mobile browsers)
DeviceManufacturerThe clicker's handset device manufacturers name if available (not widely supported in mobile browsers)
IsWarningPageServed*If the tracked URL has been marked as unsafe, we will display a warning page on which the user be required to click an additional link to proceed to the tracked URL
ShortenDate*The date and time the original URL was set for tracking
ClickDate*The date and time of the click

Examples

The format of the data (JSON or XML) that's forwarded to your handler URL is optional, simply specify what format you want when requesting setup.

{
	"RequestIdentifier":"1c712b5c-af6d-4527-b6d7-5ebb199f174d",
	"ClickDetails":
	[{
		"TrackedUrl":"https://dotdigital.com/",
		"ClientIdentifier":"My Campaign Manager Campaign Name",
		"ClientRef":null,
		"TrackingUrlId":716005,
		"UserId":1,
		"PhoneNumber":"447700900000",
		"UserAgent":"Mozilla/5.0 (BlackBerry; U; BlackBerry 9800; en-US) 				AppleWebKit/534.8+ (KHTML, like Gecko) Version/6.0.0.446 Mobile",
		"Referrer":"127.0.0.1","DeviceName":"BlackBerry 9800",
		"DeviceManufacturer":"BlackBerry",
		"IsWarningPageServed":false,
		"ShortenDate":"\/Date(1382000166965)\/",
		"ClickDate":"\/Date(1382000769338)\/"
	},{
		"TrackedUrl":"https://dotdigital.com/",
		"ClientIdentifier":null,
		"ClientRef":"My ClientRef",
		"TrackingUrlId":716006,
		"UserId":1,
		"PhoneNumber":"447700900001",
		"UserAgent":"Mozilla/5.0 (BlackBerry; U; BlackBerry 9800; en-US) 				AppleWebKit/534.8+ (KHTML, like Gecko) Version/6.0.0.446 Mobile",
		"Referrer":"127.0.0.1",
		"DeviceName":"BlackBerry 9800",
		"DeviceManufacturer":"BlackBerry",
		"IsWarningPageServed":false,
		"ShortenDate":"\/Date(1382000166965)\/",
		"ClickDate":"\/Date(1382000769617)\/"
	}]
}

<?xml version="1.0" encoding="utf-8"?>
<ClickForward xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 					xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RequestIdentifier>44e2c952-ff50-4774-a013-3fd1380355e7</RequestIdentifier>
  <ClickDetails>
    <ClickDetail>
      <TrackingUrlId>716007</TrackingUrlId>
      <UserId>1</UserId>
      <PhoneNumber>447700900000</PhoneNumber>
      <UserAgent>Mozilla/5.0 (BlackBerry; U; BlackBerry 9800; en-US) 				AppleWebKit/534.8+ (KHTML, like Gecko) Version/6.0.0.446 Mobile
      </UserAgent>
      <Referrer>127.0.0.1</Referrer>
      <DeviceName>BlackBerry 9800</DeviceName>
      <DeviceManufacturer>BlackBerry</DeviceManufacturer>
      <IsWarningPageServed>false</IsWarningPageServed>
      <ShortenDate>2013-10-17T09:02:13.3924392Z</ShortenDate>
      <ClickDate>2013-10-17T09:12:15.7199392Z</ClickDate>
      <TrackedUrl>http://www.bbc.co.uk</TrackedUrl>
      <ClientIdentifier>My Identifier</ClientIdentifier>
    </ClickDetail>
    <ClickDetail>
      <TrackingUrlId>716008</TrackingUrlId>
      <UserId>1</UserId>
      <PhoneNumber>447700900001</PhoneNumber>
      <UserAgent>Mozilla/5.0 (BlackBerry; U; BlackBerry 9800; en-US) 				AppleWebKit/534.8+ (KHTML, like Gecko) Version/6.0.0.446 Mobile
      </UserAgent>
      <Referrer>127.0.0.1</Referrer>
      <DeviceName>BlackBerry 9800</DeviceName>
      <DeviceManufacturer>BlackBerry</DeviceManufacturer>
      <IsWarningPageServed>false</IsWarningPageServed>
      <ShortenDate>2013-10-17T09:02:13.3936892Z</ShortenDate>
      <ClickDate>2013-10-17T09:12:15.9911892Z</ClickDate>
      <TrackedUrl>http://www.bbc.co.uk</TrackedUrl>
      <ClientIdentifier>My Identifier</ClientIdentifier>
    </ClickDetail>
  </ClickDetails>
</ClickForward>