Kognitiv Loyalty External Message Interface

This document describes Kognitiv Loyalty External Messaging Interface that allows for the movement of campaign data to and from a messaging provider in a standard generic format and method.

Contents

Revision Changes. 2

Campaign Creation and Transfer. 3

Campaign Creation Information: 3

File Transfer of Campaigns: 4

Campaign Results and Statistics. 5

CampaignSendStatus File Format. 5

CampaignOpenStatus File Format. 6

CampaignBounceStatistics File Format. 6

Web Services. 7

SaveBounceAction. 7

SaveOpenAction. 7

SetSendStatus. 7

Miscellaneous File Imports. 7

Invalid Email file import: 7

Opt-Out file file import: 7

Revision Changes

Revision 1 – 11/18/2010

· Campaign File – Changed delimiter to ‘vertical bar ’ or ‘pipe’ delimited… ‘|’

Revision 2 – 12/29/2010

· Campaign File – Changed file naming convention

[FileType][dash][SB][dash][SBCustomerId][dash][SmartButtonCampaignGuid][dash]
[FileCreationDate].csv

Revision 3 – 1/4/2011

· Campaign File – Added MemberPrimaryAccountId

· Campaign File – Removed MemberUnecryptedPassword – PCI Compliance

· Campaign File – Renamed MemberEmailAddress to MemberPrimaryEmailAddress

· Campaign File – Renamed MemberAddressLine1 to MemberPrimaryAddressLine1

· Campaign File – Renamed MemberAddressLine2 to MemberPrimaryAddressLine2

· Campaign File – Renamed MemberCity to MemberPrimaryCity

· Campaign File – Renamed MemberRegion to MemberPrimaryRegion

· Campaign File – Renamed MemberPostalCode to MemberPrimaryPostalCode

· Campaign File – Renamed MemberRegion to MemberPrimaryRegion

· Campaign File – Renamed MemberPhoneNumber to MemberPhoneNumber

· Campaign File – Removed MemberMobilePhone

Revision 4 – 1/10/2011

· Campaign File – Added data type and sizes

Revision 5 – 1/24/2012

· SetCampaignStatistic – Renamed to SetGenericCampaignStatistic

Revision 6 – 2/27/2012

· Renamed SetGenericCampaignStatistic to SetBounceCampaignStatistic

· CampaignSendStatus File Format – Changed parameters

· CampaignOpenStatus File Format – Changed parameters

· CampaignBounceStatus File Format – Changed parameters

Revision 7 – Added functionality for Text Messaging

Revision 8 – Added phone number formatting

Revision 9 – Added member preferred language

Revision 10 – 1/30/2015

{C}· Changed document format

{C}· Added WS links to new web services.

Campaign Creation and Transfer

Kognitiv Loyalty supports two types of Campaigns; Batch and Recurring. Kognitiv Loyalty Batch Messaging Campaign is used to send a one-time communication to a segment of your members; Email or Text. The Recurring Messaging Campaign is used to send daily recurring communications to segments of your members. For additional information regarding the creation of campaigns please refer to Kognitiv Loyalty online help on the appropriate campaign page.

Campaign Creation Information:

Unique Key:
All Campaigns can have multiple primary keys for identification for use in importing statistics at a later point.

Batch (one-time) campaigns

SmartButtonCampaignGuid: unique 32-bit unsigned integer

CampaignExternalReferenceKey: (Optional) 60 character string – user supplied and enforced for uniqueness across all campaigns.

Recurring Campaigns
Parent Campaign

SmartButtonCampaignGuid: unique 32-bit unsigned integer

CampaignExternalReferenceKey: (Optional) 60 character string – user supplied and enforced for uniqueness across all campaigns.

Instance Campaign (each day, a new instance ‘recurs’ from the parent)

SmartButtonCampaignGuid: unique 32-bit unsigned integer

InstanceExternalReferenceKey: (Exists ONLY if a ‘CampaignExternalReferenceInstanceKey’ is created in the parent) It contains the parent external reference key along with the date of the instance.

Format: [CampaignExternalReferenceKey][dash][year][month][day]

year, month and day are zero padded.

Campaign Custom Fields:

Each Campaign (batch or parent of a recurring campaign) can have campaign custom fields of type (integer, money, string, list items). These are user defined fields and exist for each batch campaign as well as the parent of recurring campaigns. Since recurring campaigns automatically create instances each day, the parent’s custom field values will be copied into each instance as it is created.

File Transfer of Campaigns:

Each Batch campaign or instance of a recurring campaign will be transferred in a flat file format to an FTP site supplied by Kognitiv Loyalty user. The following info is needed for the destination FTP. (This is setup as global settings, but copied and editable, on each batch campaign or recurring campaigns – This allows the creation of two recurring campaigns that target different FTP Sites)

FTP Address:

FTP User:

FTP User Password:

FTP Directory:

File Naming Convention:

[FileType][dash][SB][dash][SBCustomerId][dash][SmartButtonCampaignGuid][dash]

[FileCreationDate].csv

[FileType] values: B – Batch Campaign

RI – Recurring Instance of a recurring campaign

[SB] Hardcoded to SB

[SBCustomerId]                                Internal Customer ID.
                                                                *Note: This ID may change in the event of a Data Center
                                                                change. SB will provide advance notification if this change

is going to occur

[SmartButtonCampaignGuid] Internal Campaign Id

[FileCreationDate]: YYYYMMDDHHMISS

[year][minute][day][hour][minutes][seconds]

File Format:

The file will have a header in it listing all fields in the file, this is important in that the number of columns can changed based on the fields selected for the campaign. Some fields will always be present and will be noted below….

File will be ‘vertical bar’ or ‘pipe’ delimited… ‘|’

The file will only contain an email address ONE time to be sent. Blank emails will be filtered out.

[SmartButtonCampaignGuid] 32 bit unsigned integer

[CampaignExternalReferenceKey] varchar max(60) For recurring instances, this will be the ‘InstanceExternalReferenceKey’

[Campaign Custom Fields] varies for each custom field – The header will contain the column name supplied when the custom field was defined.

[MemberInternalGuid] unique 32-bit unsigned integer – unique for each member in system.

[MemberPrimaryEmailAddress] varchar max(256)

[MemberPrimaryAccountId] varchar max(60) most recent highest ranked loyalty id

[MemberFirstName] varchar max(60)

[MemberLastName] varchar max(60)

*** All the above fields are always present, the # of custom field columns depends on the number of custom fields created. If the communication is a Text message the Text custom field may be used for the content of the text ***

Optional Fields

[MemberPrimaryAddressLine1] varchar max(120)

[MemberPrimaryAddressLine2] varchar max(120)

[MemberPrimaryCity] varchar max(120)

[MemberPrimaryRegion] varchar max(120)

[MemberPrimaryPostalCode] varchar max(14)

[MemberPrimaryPhoneNumber] varchar max(30) Format (###-(###) ###-####)

[MemberBirthdate]: ISO 8601 Date Format - Full Date (YYYY-MM-DD)

[TotalPointsEarnedToDate] Decimal (-922,337,203,685,477.5808 to 922,337,203,685,477.5807)

[TotalPointsAvailableToSpend] Decimal (-922,337,203,685,477.5808 to 922,337,203,685,477.5807)

[MemberMobilePhoneNumber] varchar max(30) Format (###-(###) ###-####)

[MemberPreferredLanguage] varchar max(40)

Campaign Results and Statistics

The results of the campaign and campaign statistics can (optionally) be transferred back to Kognitiv by either flat file importing or Web Services.

** If the business requires the ESP vendor to mark member accounts for ‘invalid email’ and or ‘opt-out email status’ Kognitiv has two standalone file imports that use the member email address as the unique key to update the member accounts. Email Opt-Out File Format and Invalid Email File Format **

File Formats:

CampaignSendStatus File Format

This file allows each entry in the campaign to be moved from status ‘Sent to ESP’ to ‘Email Sent’
Flat File, No header, variable delimiter (user selected)

[SmartButtonCampaignGuid] 32 bit unsigned integer

[CampaignExternalReferenceKey] varchar max(60)

*** ONE of the above two fields must be present. If CampaignExternalReferenceKey is supplied for a recurring campaign, it must be the full ‘InstanceExternalReferenceKey’ ***

[MemberPrimaryEmailAddress] varchar max(256)

[EmailSentSatus] Numeric –

Values: 1 - Sent Successfully

2 - Sent Failure, (will record the failure message is the status is of this value

16 - Not Sent because member has previously unsubscribed

32 - Not Sent because email address is invalid

[Failure Message] varchar max(512)

CampaignOpenStatus File Format

This file allows each entry in the campaign to be moved marked as ‘open’. Multiple Opens can be tracked by sending the open status record multiple times.

Flat File, No header, variable delimiter (user selected)

[SmartButtonCampaignGuid] 32 bit unsigned intege

[CampaignExternalReferenceKey] varchar max(60)

*** ONE of the above two fields must be present. If CampaignExternalReferenceKey is supplied for a recurring campaign, it must be the full ‘InstanceExternalReferenceKey’ ***

[MemberPrimaryEmailAddress] varchar max(256)

[OpenTimestampUTC] DateTime - Format MM/DD/YYYY HH:MM:SS

CampaignBounceStatistics File Format

This file allows the storage of generic statistics numbers at the campaign level. Each time the file is imported, it will overwrite any statistics with a matching key.

Flat File, No header, variable delimitor (user selected)

[SmartButtonCampaignGuid] 32 bit unsigned intege

[CampaignExternalReferenceKey] varchar max(60)

*** ONE of the above two fields must be present. If CampaignExternalReferenceKey is supplied for a recurring campaign, it must be the full ‘InstanceExternalReferenceKey’ ***

[MemberPrimaryEmailAddress] varchar max(256)

[BounceType] varchar max(40)

Web Services

The information supplied in the above files can also be supplied via web services calls….

https://app.kognitivloyalty.com/WS/Campaign.asmx

Methods:

Miscellaneous File Imports

Invalid Email file import:

This file import updates Kognitiv Loyalty Invalid Email address to true, Invalid Email.

https://info.kognitivloyalty.com/default.asp?W69

File Specification:

No Header is required, first line is processed.

One column file. No delimiters are necessary
The Email addresses will be marked "invalid" system-wide. If more than one loyalty member shares an Email address, it will display as invalid all both accounts.

Email Address Datatype: Alphanumeric Max Length: 256 Required: Yes

Opt-Out file file import:

This file import updates Kognitiv Loyalty Do Not Email to true.
https://info.kognitivloyalty.com/default.asp?W72

File Specification:

No Header is required, first line is processed.

One column file. No delimiters are necessary

The Do Not Email status will be marked true, system-wide. If more than one loyalty member shares an Email address, it will display as Do Not Email all both accounts.

Email Address Datatype: Alphanumeric Max Length: 256 Required: Yes

Tags: message
Home: Kognitiv Loyalty © 2023 Kognitiv Corporation. All Rights Reserved.