Conversion
The conversion endpoint is called when a sales conversion event takes place in the client application.
https://{tagserver.domain}/tagserver/v1/dataCollection/conversion
| URI | Conversion |
|---|---|
| HTTP Method | POST |
| Formats | JSON |
Parameters
| Parameter Name | Description | Required | Data Constraints |
|---|---|---|---|
| agentGroupID |
Id of the current agent group as defined in Portal. This parameter is used to determine hours of operations. Note:
|
No | Integer |
| attributes | List of any modifiable name/value attributes that is associated with this customer, engagement or session. | No | N/A |
| attributes:action | Action being performed on this attribute. | No |
Must be one of:
Default value is append. |
| attributes:attributeType | Type of attribute being set or modified. | Yes |
Must be one of:
|
| attributes:externalCustomerID | Used for visitor attributes. If this visitor attribute can be used as a unique identifier for the user, it must be indicated by a yes value in this field. | No | Must be either yes or no. Default is no. |
| attributes:name | Name of this attribute. | Yes | String |
| attributes:value | Value of this attribute. Can be multi-valued. | Yes | String |
| businessUnitID |
Id of the current business unit as defined in Portal. This parameter is used to determine hours of operations. Note:
|
No | Integer |
| clientOrderNumber | Unique identifier for this order | No | String, possible values are: [az], [A-Z], [0-9], [-], [_] |
| conversionAttributes | List of any name/value pairs that is associated with this conversion. | No | N/A |
| conversionAttributes:name | Name of this conversion attribute. | Yes | String |
| conversionAttributes:value | Value of this conversion attribute | Yes | String |
| customVariables | Used to store targeting information for chat routing. | No | N/A |
| customVariables:action | Action to be performed on this custom variable. | No |
Must be one of:
Default value is append. |
| customVariables:name | Name of this custom variable | Yes | String |
| customVariables:persistence | Recommended persistence lifespan. | No | Must be either volatile or persistent. Default value is persistent. |
| customVariables:value | Value of this custom variable. Can be multi-valued. | Yes | String |
| engagementID | ID of the engagement. This value is provided by the Nuance platform. Used only for engagement attributes. | No, but required for engagementattribute s | String, possible values are: [az], [A-Z], [0-9], [-], [_] |
| orderType | Client provided order type to be associated to this order. | No | String, possible values are: [az], [A-Z], [0-9], [ ], [-], [_] |
| products | List of product information associated with this conversion. | Yes | N/A |
| products:count | Product count. | Yes, must be present at least in one product | Integer |
| products:product | Product name. | Yes | String |
| products:productAttributes | List of product attributes associated with this product. | No | N/A |
| products:productAttributes:nam e | Name of this product attribute | Yes | String |
| products:productAttributes:valu e | Value of this product attribute. | Yes | String |
| products:type | Product type. | No | String |
| products:value | Product value or cost. | No | Number |
| sessionID | Id of current session. | No, but required for applicationattributes | String |
| siteID | ID of the site. This value is provided by Nuance and is a static value for the client application. | Yes | Integer |
| tcCustomerID | The customerID parameter is provided by the CEAPI when the /engagement endpoint is called OR by the DCAPI when the /startSession endpoint is called | Yes | String, possible values are: [az], [A-Z], [0-9], [-], [_] |
| viewID | Identifier for the current content displayed (or otherwise provided) to the customer. | No | String |
| flexibleResponse | If true and response body is empty, returns 204 | No | Must be either 'true' or 'false'. |
| sessionID (can be spelled as sessionId, but not in both variants in the same request body) | Id of current session | No, but required for session attributes | String, possible values are: [a-z], [A-Z], [0-9], [-], [_] |
| conversationID | Id of NDEP async chat conversation, used for async chats only | No | Integer |
| initialCustomerID | Id of initial customer Id for NDEP async chat conversation, used for async chats only | No | Integer |
JSON Input data example
{
"tcCustomerID": "12345",
"siteID": 6789,
"clientOrderNumber": "123456789",
"orderType": "orderTypeValue",
"viewID": "6789231234",
"products": [{
"product": "iPhone7s",
"type": "phones",
"count": 1,
"value": 100.00,
"productAttributes": [{
"name": "attributeName",
"value": "attributeValue"
}
]
}
],
"conversionAttributes": [{
"name": "attributeName",
"value": "attributeValue"
}
],
"attributes": [{
"name": "sale",
"value": "iPhone 5S",
"attributeType": "visitorAttribute",
"action": "set"
}, {
"name": "sale",
"value": "Galaxy S7",
"attributeType": "visitorAttribute"
}
]
}JSON Schema
{
"$schema": "http://json-schema.org/schema#",
"type": "object",
"properties": {
"tcCustomerID": {
"type": "string"
},
"tcCustomerId": {
"type": "string"
},
"siteID": {
"type": "integer"
},
"sessionID": {
"type": "string"
},
"sessionId": {
"type": "string"
},
"clientOrderNumber": {
"type": "string"
},
"orderType": {
"type": "string"
},
"viewID": {
"type": "string"
},
"engagementID": {
"type": "integer"
},
"businessUnitID": {
"type": "integer"
},
"agentGroupID": {
"type": "integer"
},
"flexibleResponse": {
"type": "boolean"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product": {
"type": "string"
},
"count": {
"type": "integer"
},
"value": {
"type": "number"
},
"productAttributes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
},
"required": ["product", "count"]
},
"conversionAttributes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"attributes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
},
"attributeType": {
"type": "string",
"enum": ["engagementAttribute", "visitorAttribute", "sessionAttribute"]
},
"action": {
"type": "string",
"enum": ["set", "remove", "append"]
},
"externalCustomerID": {
"type": "string",
"enum": ["yes", "no"]
}
},
"required": ["name", "value", "attributeType"]
}
},
"customVariables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
},
"action": {
"type": "string",
"enum": ["set", "remove", "append"]
},
"persistence": {
"type": "integer"
}
},
"required": ["name", "value"]
}
}
},
"oneOf": [{
"required": [
"tcCustomerID",
"siteID",
"products"
]
}, {
"required": [
"tcCustomerId",
"siteID",
"products"
]
}
]
}Examples
Request
POST https://{tagserver.domain}/tagserver/v1/dataCollection/conversionPOST body:
{
"tcCustomerID": "465657113802851330",
"siteID": 306,
"businessUnitID": 22,
"agentGroupID": 10004091,
"clientOrderNumber": "123456789",
"orderType": "orderTypeValue",
"viewID": "6789231234",
"sessionID": "55552456234234",
"engagementID": 123433332111,
"products": [{
"product": "iPhone 7$",
"type": "phones",
"count": 1,
"value": 100.00,
"productAttributes": [{
"name": "key1_1",
"value": "!value1_1"
}, {
"name": "<>key1_2",
"value": "value1_2"
}
]
}, {
"product": "Lenovo",
"type": "pad",
"count": 2,
"value": 200.00
}, {
"product": "Samsung",
"type": "phones",
"count": 3,
"value": 300.00,
"productAttributes": [{
"name": "key3_1",
"value": "value3_1,value_3_1_1"
}, {
"name": "key3_2",
"value": "value3_2"
}
]
}
],
"conversionAttributes": [{
"name": "convName1 <>@",
"value": "convValue1!@#"
}, {
"name": "#^ convName2",
"value": "^&convValue2"
}
],
"customVariables": [{
"name": "attributeName@&^",
"value": "attributeValue",
"persistence": 48,
"action": "append"
}, {
"name": "attribute Name2",
"value": "attributeValue2_!<",
"persistence": 168,
"action": "set"
}
],
"attributes": [{
"name": "visAttr 1",
"value": "visAttr Value11",
"attributeType": "visitorAttribute",
"externalCustomerID": "Yes",
"action": "set"
}, {
"name": "visAttr2 #^",
"value": "visAttrValue22 !$>",
"attributeType": "visitorAttribute",
"externalCustomerID": "No",
"action": "set"
}, {
"name": "attr1",
"value": "visAttrValue22 !$>",
"attributeType": "sessionAttribute",
"action": "set"
}, {
"name": "attr2",
"value": "visAttrValue22 !$>",
"attributeType": "engagementAttribute",
"action": "remove"
}
]
}Response
200 OK
Request
POST https://{tagserver.domain}/tagserver/v1/dataCollection/conversionPOST body:
{
"tcCustomerID": "465657113802851330",
"siteID": 306,
"products": [{
"product": "Lenovo",
"count": 2
}
]
}Response
200 OK
