This API allows you to update link clicks transactions from an external application within the customer retention period configured in the platform.
The SMS campaigns are used to drive users inside their mobile apps. For this purpose, clients typically want to use ‘mobile deep links’ within their SMS messages. In the case of iOS, these are known as ‘Universal Links’ and in the case of Android, these are known as ‘Android App Links’.
The ‘Universal Links’ and ‘Android App Links’ are special URLs that have been registered with Apple App Store and Google Play Store respectively. When an SMS message recipient clicks on one of these links, the smartphone OS will first check whether the smartphone has the relevant mobile app installed or not. If the mobile app is present, then the OS will re-direct (deep-link) the message recipient directly within the appropriate section within the mobile app. If the mobile app is not present on the smartphone, then the OS will re-direct the user to a mobile web page inside a browser. The iOS ‘Universal Links’ are essential for iOS app deep-linking, whereas the Android App Links are not as prevalent because Android OS allows other means to achieve this same result.
In this scenario, when the SMS marketing message contains one of the above ‘mobile deep links’, it is not possible for the Webex Campaign to track this click-event because the OS directly re-directs the message recipient bypassing the Webex Campaign’s ‘SmartLink’ feature. Therefore, this API will then need to be invoked by the client mobile app developers in order to create this link-click event within the Webex Campaign’s click-through database so that these clicks on the ‘universal links’ are incorporated in the CTR metrics within the Dashboard and Downloadable Reports.
More info about ‘Universal Links’ and ‘Android App Links’ can be found on the web here:
https://developer.android.com/training/app-links/
https://developer.apple.com/ios/universal-links/
https://www.appsflyer.com/resources/everything-marketer-needs-to-know-deep-linking/universal-links/
https://blog.branch.io/universal-links-uri-schemes-app-links-and-deep-links-whats-the-difference/
https://medium.com/@abhimuralidharan/universal-links-in-ios-79c4ee038272
Know your endpoint
Based on the domain you use to log in to Webex Campaign, the endpoint domain for your API varies. For more information, refer to the Know Your API Endpoints section.
Go to the Postman Collection section to learn how to import a Postman collection. Click the below button, If you already know how to import a postman collection.
Headers
The following table describes the request headers:
| Request Header | Description |
|---|---|
| content-Type | application/json |
| authorization | Access token or API Secret Key in Bearer format Example: Bearer $(key) |
Body Parameters
The following table describes the elements in the request body:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| short-url | String | Yes | This is the short URL that has been sent out from the platform within the promotion message. |
| user-agent | String | No | User agent of the browser from which link was clicked initially. Note: If the user agent is not available in the request, Browser/OS/ Device/Resolution etc. specific reports will not be available and they will be reported as Others category. The Browser/OS/Device/Resolution information will not be available in RTE and EDR as well. |
| ip-address | String | No | Specifies the IP address of the device from which initial message was opened and link was clicked. |
Request Example
{
"short-url":"http://shortdomain/dsltrack/employee/j460A8",
"user-agent":" Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36",
"ip-address":"203.199.178.211"
}
Response Parameters
This API will return the following response parameters:
| Parameter | Description |
|---|---|
| code | Returns the response code in case of failure. |
| description | Returns the description of the response in case of failure. |
| transaction-id | Returns the unique Transaction ID of the operation in case of success. |
Failure Response Codes
The API will return code within the response as per the following table in case of failure scenarios.
| HTTP Status Code | Code within API Response | Description |
|---|---|---|
| 200 | 1010 | The request was not processed. |
| 401 | 430 | Authorization failed. This resource is not allowed to access using this TOKEN or KEY |
| 498 | Invalid token or Access token expired | |
| 405 | 405 | Method not supported |
| 429 | 429 | Too many requests. Throttle limit reached for the time window. |
| 499 | 499 | Request failed. Check the exact reason of failure in application code and description of error stream. |
| 500 | 500 | Internal server error |
| 1001 | Invalid input JSON | |
| 1002 | Mandatory field missing | |
| 1003 | Promotion does not exist for the URL given. |