Interaction API

The Interaction API allows you to:

Track customer activity from your touchpoint solution.
Update customer profile data stored in MXO.
Receive optimized content responses for the best conversation to have with a customer.
Buffer requests to support offline mode and to reduce network calls.

Important: Offline Interaction endpoints were deprecated and replaced by the new Batch Interaction API.

Authentication and authorization

MXO security framework uses OAuth 2.0 for authenticating access to data. For detailed information on how to create API credentials for a user and request an OAuth 2.0 token from MXO, see MXO API security.

Available API calls

We provide the API calls listed below:


Method	Summary	Details
POST	/one/oauth2/rt/api/2.0/interaction/	Send information about customer interactions to MXO in real-time. Use POST when you want to return optimizations in the response or when you want to register activity immediately.
PUT	/one/oauth2/rt/api/2.0/interaction/	Update the customer profile with details of captured and tracked activity. No optimizations are returned to customers.
PUT	/one/oauth2/rt/api/2.0/interaction/offline	Send individual historic offline interactions to MXO. No optimizations are returned to customers. You must provide the timestamp when the customer interaction occurred. If interactions are being buffered by the touchpoint, for example, if a mobile device goes offline for a short period of time, the timestamp relates to time at which the interaction occurred and not the time the interaction was flushed to MXO.
PUT	/one/oauth2/rt/api/2.0/interactions/offline	Send multiple offline interactions to MXO. No optimizations are returned to customers. Use to buffer multiple activities into a single request to MXO when you need to reduce network traffic or buffer activity when offline. This API supports a maximum of 100 offline interactions per call.

Interaction request elements

The table below provides an overview of the key elements to include as part of the interaction request.


Element	Type	Required	Description
Query parameters
sk	STRING	Required	Site key for your space.
tid	STRING	Optional	Unique identifier with which you want to associate the interaction.
Headers
Content-Type	STRING	Required	Default value: application/json.
Authorization	STRING	Optional	Default value: Bearer (TOKEN).
dataMimeType	STRING	Required	Set to application/json to return optimizations as a collection of actions; that is, return more than one action.
Body
url	STRING	Required	Full touchpoint/interaction URI as configured in MXO for the target interaction.
customerKey	STRING	Optional	Key for the specific, recognized, customer with which you want to associate the Interaction. Required if customerKeyName is provided.
customerKeyName	STRING	Optional	API name of the key with which the customerKey value should associated as part of the Interaction. Default value: customerkey.
properties	ARRAY	Optional	Provided to return optimizations as a collection of actions; that is, return more than one action.
device Important: The device object is optional. However, if included, it must contain non-empty deviceAppName, and both devType and osName must resolve to non-null enums to successfully persist.	OBJECT	Optional	Array of objects containing context and metadata about the user's device. For example: `{ "device": { "deviceAppName": "Chrome", "devType": "PERSONAL_COMPUTER", "osName": "WINDOWS" } }`
device child elements
deviceAppName	STRING	Optional	Name of the application on the device. Accepts any non-empty string.
deviceAppVersion	STRING	Optional	Version of the application.
devMfr	STRING	Optional	Device manufacturer name.
devModel	STRING	Optional	Device model name.
devType	STRING (ENUM)	Optional	Type of device. Accepted values: GAME_CONSOLE, PDA, PERSONAL_COMPUTER, SMART_TV, SMARTPHONE, TABLET, WEARABLE, OTHER, TV, DATA_COLLECTION_TERMINAL, WIRELESS_HOTSPOT, MOBILE_PHONE, SET_TOP_BOX, DESKTOP, VEHICLE_MULTIMEDIA_SYSTEM, PAYMENT_TERMINAL, SINGLE_BOARD_COMPUTER, MEDIA_PLAYER, REFRIGERATOR, PROJECTOR, DIGITAL_HOME_ASSISTANT, EMBEDDED_NETWORK_MODULE, TELEMATICS_CONTROL_UNIT, WRISTWATCH, VR_HEADSET. Note: Invalid values will automatically default to OTHER.
osName	STRING (ENUM)	Optional	Operating system name. Accepted values: ANDROID, WINDOWS, IOS, OSX, LINUX, OTHER, WINDOWS_NT, IPAD_OS, WINDOWS_RT, LINUX_MINT, WINDOWS_VISTA, LINUX_SLACKWARE, CHROME_OS, WINDOWS_11, WINDOWS_8_1, RIM, OS_2, FREEBSD, WINDOWS_10, WINDOWS_NT_4_10, WEBOS, WINDOWS_8, WINDOWS_XP, FUCHSIA, HARMONY_OS, OPENBSD, KAIOS, TIZEN, PLAYSTATION_4_OS, WINDOWS_NT_4_0, FIREFOX_OS, LG_PROPRIETARY, WINDOWS_MOBILE, PLAYSTATION_5_OS, SAMSUNG_PROPRIETARY, NETBSD, BREW, LINUX_UBUNTU, LINUX_FEDORA, WINDOWS_2000, WINDOWS_7. Note: Invalid values will automatically default to OTHER. Passing null or omitting this when device is present will result in a DeviceEvent precondition failure.
deviceOsVersion	STRING	Optional	Operating system version.
deviceLocationLatitude	NUMBER (DOUBLE)	Optional	Geographic latitude coordinate of the device.
deviceLocationLongitude	NUMBER (DOUBLE)	Optional	Geographic longitude coordinate of the device.
deviceLocationLastUpdate	DATE-TIME	Optional	Timestamp of last location update. Usually, an ISO-8601 formatted date/time string.
deviceLocationHorizontalAccuracy	NUMBER (FLOAT)	Optional	Horizontal accuracy radius of the location data.
ipAddress	STRING	Optional	IP address string. Passing "detect" will cause the API to automatically substitute it with the caller's remote IP address.
locale	STRING	Optional	Locale string (typically BCP-47 format, e.g., en-GB or en-US).
deviceFlashEnabled	BOOLEAN	Optional	Indicates if Adobe Flash is enabled (true/false).

Interaction response elements

For each interaction request, the elements listed below may be present in the response.


Element	Type	Description
statusCode	INTEGER	Status of the request sent the server.
tid	STRING	TID of the customer assigned to the interaction. The value should be retained for later use to properly track anonymous activity
trackers	ARRAY	Collection of activity capture points associated with the interaction or region.
captures	ARRAY	Collection of page element attribute capture points associated with the interaction or region.
optimizations	ARRAY	Array of optimization points returned for the customer, based on any decisioning associated with the interaction or region.

Response status codes

MXO can return the following status codes in a response.


Status Code	Description
200	Request successfulHandler
400	Bad Input Parameter
401	Invalid OAuth 2.0 token
403	User lacks permissions to perform operation
404	Not found
405	Method not allowed
500	Internal server error

Example use case — Tell MXO about a customer interaction on a touchpoint

You want to record details in the AEP about a customer interaction on a touchpoint.

Example parameters


Field	Description
Site Key	ONE-NX8P2RSAAU-1813
Touchpoint and Context	api://my.touchpoint/customer/interaction
Customer Key	my-customer-id
TID	Returned on first request

Example API call - Request


Field	Description
Request Method	POST
Request URL	/one/oauth2/rt/api/2.0/interaction?sk=ONE-NX8P2RSAAU-1813
Request Headers	Authorization header: HTTP Basic. Generated using the credentials supplied for the request, encoded in Base64. Example: Authorization: Basic MmU4ZmVjMGUtMzRmYi00ODUxLTgwMGUtOTk4OTMzMWU1NWQ yOmQ3ZjQ0ODRmLTk4MTctNDc3OC05MTYxLTZlYjA2ZDFmNmNmNw== Content-Type: application/x-www-form-urlencoded
Request Body	`{ "customerKey":"my-customer-id", "uri":"api://my.touchpoint/customer/interaction" }`

Example API call - Response

Expected response code

200 SUCCESS

Expected response body

{
   "statusCode": 200,
   "tid":"dedc2983-4666-4641-8047-61250a878f89"
}