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?	Default Value	Description
Query Parameters
sk	STRING	Yes	N/A	Site Key for your Space.
tid	STRING	No	N/A	Unique Thunderhead Identifier with which you want to associate the Interaction.
Headers
Content-Type	STRING	Yes	application/json
Authorization	STRING	Yes	Bearer (TOKEN)
dataMimeType	STRING	Yes	N/A	Set to application/json to return optimizations as a collection of actions; that is, return more than one action.
Body
url	STRING	Yes	N/A	Full Touchpoint/Interaction URI as configured in MXO for the target Interaction
customerKey	STRING	No	N/A	The key for the specific, recognized, customer with which you want to associate the Interaction. Required IF customerKeyName is provided.
customerKeyName	STRING	No	customerkey	The API Name of the key with which the customerKey value should associated as part of the Interaction.
properties	ARRAY	No	N/A	Provided to return optimizations as a collection of actions; that is, return more than one action.
device	OBJECT	No	N/A	An array of objects consisting of container name/value pairs. For example, "name":"ck", "value":"1234"}.

Interaction response elements

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


Element	Type	Description
statusCode	INTEGER	The status of the request sent the server.
tid	STRING	The TID of the customer assigned to the interaction. The value should be retained for later use to properly track anonymous activity
trackers	ARRAY	The collection of Activity Capture Points associated with the interaction or region.
captures	ARRAY	The collection of Page Element Attribute Capture Points associated with the interaction or region.
optimizations	ARRAY	The 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"
}