Event catalog

To offer guidance for publishing and subscribing to event data, Exchange provides a list of events that Exchange recognizes as typical activities in common business situations. Exchange refers to these events as recognized events.

Different business applications view and track customer and entity interactions in different ways. Each application can observe different interactions and record data for different attributes for each interaction. Because Exchange provides a way to view customer actions across multiple applications, it establishes a standard framework for describing typical business interactions. This framework is described in the Acoustic Exchange event catalog.

The event catalog lists various identifier and descriptive attributes that event publishers can use to describe an event. As an event publisher, you can provide values for all of the standard event attributes, or for only few of them. However, some attributes are required of all events.

Event publishers might not provide values for every possible attribute in an event. Endpoints that subscribe to events must design their systems to ignore missing values in the JSON payload that Acoustic Exchange provides when it delivers the event data to the subscribing endpoint.

Event types

Acoustic Exchange defines several types of recognized events and organizes them into classes that are based loosely on the channel in which the events are observed.

Acoustic Exchange defines the following event types.

Web Events
Email Events
Mobile Events
Social Events
SMS Events
Contact Center Events
Aggregate Events

Exchange also recognizes custom events that are defined by Exchange Business Partners, but only after consultation and agreement on the event name, event code, and support for event attributes. Such consultation helps ensure that Exchange can correctly recognize and process the data that the custom event promises to deliver.

Custom events

If Exchange recognized events do not adequately describe the event data that an endpoint can provide, the endpoint can define a custom event.

Endpoints that define custom events typically define custom event attributes. However, the endpoint must use caution when it defines an event code for a custom event. Event publishers cannot use an event code that is already used by an Exchange recognized event. To avoid potential confusion and errors, consult with Exchange before defining a custom event.

Endpoints that subscribe to custom events must consult with the event publisher to determine the event attributes that they can expect.

Event publishers cannot add custom event attributes to an Exchange recognized event.

Event attributes

Every event that you publish to Exchange must define attributes that describe the event. The number and quality of attributes that you include in the event can improve the value of the event notification to event subscribers and Exchange users.

When an endpoint publishes an event, the call to v1/event typically includes several event attributes. Each attribute specifies a name, value, and data type. The attributes in the event notification must include required attributes. The event notification might also include certain recommended attributes that are considered best practice attributes. The publishing endpoint might also include other attributes that Exchange considers general attributes.

Exchange requires specific event attributes to distinguish between events, facilitate identity enhancement by the Exchange Identity Service, and to properly represent the event in the Exchange user interface. Some descriptive attributes of published events, specifically, the event code and event name, are defined when an endpoint registers the event with Exchange.

Exchange reserves specific property names for recognized events. When you register and publish a recognized event, use only the reserved property names.

Required event attributes

Exchange requires that you define specific attributes for all published events. Exchange applies depending on the type of event, or on the specific event, Exchange might impose more attribute requirements.

Exchange requires that you define the following attributes for all published events, including Exchange recognized events and custom events.

channel Where the event was observed.
name Name of the type of identifier that is used to identify the individual or entity that initiated the event. For example, emailAddress.
value The identifier value for the specific event that is being published by the endpoint.
code The event code that Acoustic Exchange assigned to the event. Acoustic Exchange assigns a unique event code to recognized and custom events.
Timestamp The date and time when the event was observed. The time must be submitted in ISO-8601 format.

For example, for social event publishers, unique user identifiers such as User ID, User Name (Facebook and Instagram), Twitter Handle, Twitter ID (Twitter), are required attributes that you define as identifiers during endpoint registration and include when you publish events from the endpoint.

The following example illustrates the structure of the JSON payload in the call to
v1/event to publish an event.

JSON	Required	Description
POST v1/event { “channel” : “”,	Yes	The type of device or method that the individual uses to interact with the business or service provider. For example, mobile if the customer used a cell phone. Email, if the customer made an email request.
“identifiers” : [ { “name” : “”, “value” : “” } ],	Required for individual events.	One or more unique name-value pairs that can be associated with a specific individual and only that individual.
“events” : [ { “code” : “”, “timestamp” : “<time	Yes	Acoustic defines the event code to identify the specific event. You must use the Exchange event code. Do not create a different one. The time stamp indicates when the event was observed by the publishing endpoint, not when the endpoint transmits the event notification. The format must be ISO-8601.
“attributes” : [ { “name” : “”, “value” : “”, “type” : “” } ] } ] }		The list of attributes that describe the event. The attributes that are included in the JSON package depend on the event. The attributes section must contain values for all required attributes for the event. You can add other attributes, depending on the information that the business application can gather and report.

Best practices for event attributes

Exchange has identified various event attributes that can be added to most event definitions
to enhance the potential insights that Exchange users can derive from the event notification.

Best practice attributes are based on the experience of Exchange and Acoustic Exchange Business Partners.

The examples that are presented are typical values. They do not represent the only values that are possible or acceptable.

Attribute Name	Data Type	Example (typical)	Description
activityCategory	string	Lead Generation	Category for a commercial activity or tactic.
activityCode	string		A tracking code for a commercial activity or tactic. Usually associated with the event for attribution purposes.
activityName	string	Email outreach	Name of the activity or tactic.
appName	string		Name of the application used during the interaction.
appVersion	string		Version of the application used during the interaction.
assetId	string		URL location for a physical asset.
browserName	string	Safari	Browser used on the device used during the interaction.
browserVersion	string		Browser version used on the device used during the interaction.
campaignCategory	string	Customer retention	Category for a campaign conducted to generate customer interactions.
campaignCode	string		Tracking code for a campaign conducted to generate customer interactions.
campaignName	string	New Year - New Opportunities!	Name of the campaign conducted to generate customer interactions.
carrier	string	Verizon	Carrier vendor of a mobile device.
channelType	string	Owned Paid	Classify a channel as owned or paid media.
connectionSpeed	string	4G	Wireless connection speed.
contactConsent	string	email\|mobile\|sms, opt-in\|opt-out Not case sensitive. Example value: sms,opt-out Indicates that an individual does not want to receive SMS messages.	Communication consent preference for an individual, as recorded by a messaging endpoint. Indicates channel and preference.
depth	string		Device screen depth
deviceType	string	Tablet	Type of device used during a customer event.
idPrivacy	string	Analytics Personalization Engagement Join Any	Permissible use of identifier as defined by the publisher of the event or identity. Note: Null defaults to Join.
initiator	string	Customer	Person or system that initiated the event. You can set the default during event registration.
ip	string		IP address of the device that was used during the event.
interactionId	string		Unique identifier for a visit. Sometimes called a session ID. Can be used to connect related events. For example, if a cookieId identifies a visitor, the interactionId identifies a visit by that person. One person can generate multiple visits, which are distinguished by multiple interactionIds A null value is acceptable, but you must generate a unique value when you publish the event.
interactionType	string		Classification to the event. For example, distinguish between events that generate revenue and events that do not generate revenue. You can set the default during event registration.
latitude	string		Event location latitude.
locale	string		Event location locale.
locationAddress	string		Event location address.
locationCity	string		Event location city.
locationCountry	string		Event location country.
locationName	string		Event location name.
locationRegion	string		Event location region.
longitude	string		Event location longitude.
model	string		Model of the device.
offerCategory	string		Classification category for an offer.
offerCode	string		Offer code, for attribution.
offerName	string		Name of the offer.
offerType	string		Type of offer.
OS	string	iOS	Operating system of the device used during an event.
platform	string	Gmail	Platform or client used on the device during an event.
resolution	string		Device screen resolution.
stageName	string	Learn	Stage or phase that describes the customer journey status of the event.
subChannel	string	SMS Web Live Chat Facebook (Typical examples. Not an inclusive list.)	A more granular descriptor of the channel where an event occurred.
type	string	email cookieid	Exchange privilege key mapping for published identifier. Used to join identities by identity type.
vendor	string	Apple	Vendor of the device used during an event.
versionOS	string	8	Operating system version of the device used during an event.