Enhanced alert personalisation

Using ‘lookups’ and shortlinks

When sending bulk SMS, emails and TTS voice calls it is possible to replace some or all of the message or voice content with information unique to each recipient; this is known as performing ‘lookups’. Items such as recipient telephone number (or email address), current date and time and sending number or email address can be specified. In addition, if contact groups are used instead of simple recipient lists then you can supply your own lookups (such as firstname, lastname or any other item you so choose). 

In addition it is possible to specify the use of a ‘shortlink’. This results in a unique (per-recipient) small url being placed in the SMS or email (or even in the TTS voice call but this would be less useful), allowing the recipient to ‘click’ on that link when they receive the message. The link will take them back via AlertingHub for collection of information such as browser, OS type, recipient number or email address and so on. If you specify an onward url as part of the sendalert then AlertingHub will automatically forward the recipients ‘click’ to your url, together with pertinent information about the recipient. If you do not specify an onward url the recipient will simply see an AlertingHub ‘thank-you’ landing page.

Lookups are specified using the ‘lookups’ JSON section with the relevant alert section in /sendalert as shown here and described in the table following:

"lookups": {
    "performLookups": true,
    "uniqueLookups": true,
    "shortlink": {
        "reference": "a-reference",
        "url": "https://my-companies-url.com/alertinghub-click-through"
    }
}

ParameterRequirementDefaultDescription
performLookupsOptionalfalseWhether to actually perform lookups or not. You would normally set this to true to perform lookups.
uniqueLookupsOptionalfalseSpecifies if the lookups to be used will include items that will be unique to each recipient.
shortlinkOptionalNot setSpecifies shortlink properties if short links are to be used. If you specify a shortlink section then performLookups and uniqueLookups will be automatically set to a true value.
  referenceOptionalOverall alert client-ref Reference to associate with the shortlinks.
  urlOptionalNoneSpecifies your own url that the recipient will be redirected to after clicking the shortlink.
  avoidPreviewOptional"none"Optional method to employ to try to avoid accidental triggering / following of the link by browsers/email previews etc. One of "none" (where no action is taken), "useMiddleMan" or "useSpacedLink".
  • useMiddleMan ensures that when the link is clicked the link returns some html/javascript to then auto-redirect to the true link with some validation parameters.
  • useSpacedLink results in the system adding a space between the https: and remaining url. This will involve a user having to cut-n-paste the link into a browser in order to follow the link.


To use the lookups in an SMS, email message or TTS voice call you need to encase the relevant special keyword within curly braces {}, so to specify the recipients own telephone number in an SMS simply use {recipient} in the SMS text. (If no “lookups” section is specified in the alert section of /sendalert or “performLookups” is set to false then no lookups are performed.) The currently supported keywords are:

Lookup keywordDescriptionNeed to set uniqueLookups
{recipient}The telephone number or email address of the recipient.Yes
{sender}The telephone number or email address of the sender.No
{alertid}The internal unique alert-id for this /sendalert api call.No
{reference}The reference from the lookups part of the alert or the overall client-ref from the /sendalert api callNo
{type}sms for SMS
email for emails
No
{datetime-[TZ]-[format]}Datetime of sending. [TZ] is an optional timezone and must be in the conventional ISO format such as 'America/Los_Angeles'. The [format] should be replaced with a date/time format string where DD = day, MM = month, YYYY = year, HH = hour, mm = minute, ss = seconds. Example of just current date with default timezone (UTC): {datetime--DD/MM/YYYY}.No
{shortlink}A unique short-url per-recipient.Yes


It should be noted that if lookups are used that are per-recipient unique (“uniqueLookups” is true or “shortlink” is specified) then there are some additional constraints in terms of the number of recipients that can be included in any one /sendalert request. This is currently set at 500 recipients per request.