Enhanced alert personalisation

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.

You can also use shortlinks to send recipients a tracked authenticator QR code (see the create authenticator API call) or, for emails, you can specify the {qrcode-issuer-label} lookup within an html email body (e.g. <img src=\”{qrcode-AlertingHub-DemoQrCode}\”>). These provide easy mechanisms to relay authentication codes to recipients without you having to manage them. You can also specify for normal shortlinks that the recipient, upon clicking the shortlink, must provide a valid authentication code to a previously established authenticator.

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"
    }
}

Parameter	Requirement	Default	Description
performLookups	Optional	false	Whether to actually perform lookups or not. You would normally set this to true to perform lookups.
uniqueLookups	Optional	false	Specifies if the lookups to be used will include items that will be unique to each recipient.
shortlink	Optional	Not set	Specifies 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.
reference	Optional	Overall alert client-ref	Reference to associate with the shortlinks.
url	Optional	None	Specifies your own url that the recipient will be redirected to after clicking the shortlink.
avoidPreview	Optional	"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.
authenticator	Optional	None	Specifies use of a tracked authenticator.
method	Optional	"none"	One of displayQRCode, askForAuthCode or none. If displayQRCode is specified then when the recipient clicks the link they will be shown a QR code for the tracked authenticator. If askForAuthCode is specified then the recipient, upon clicking the link will be asked to provide the current authentication code, if that matches then the link will be processed as normal (redirection etc.)
issuer	Optional	None	Issuer associated with the tracked authenticator. This is mandatory if method is displayQRCode or askForAuthCode.
label	Optional	None	Label associated with the tracked authenticator. This is mandatory if method is displayQRCode or askForAuthCode.

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 keyword	Description	Need 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 call	No
{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
{qrcode-issuer-label}	For emails only, will be replaced by the QR code for the authenticator identified by the issuer/label combination (from a previous call to the createauth API).	No

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.