Jump to

• Request
• Response
• Examples

Update the properties of an engagement

post

/engagement/api/agent/{fqSiteName}/v1/modifyProperties

This operation modifies the properties of an engagement or end user session. The allowable properties to be set if the type is ENGAGEMENT are CONTACT_ID and INCIDENT_ID. The allowable properties to be set if the type is USER are FIRST_NAME, LAST_NAME, EMAIL, QUESTION, PRODUCT_ID, CONTACT_ID and CATEGORY_ID. Custom fields are only permitted if the type is USER.
The following is the list of exception codes that can be returned from this operation:

• ACCESS_DENIED - Authentication failed.
• UNKNOWN_EXCEPTION - An unknown error has occurred.
• BAD_REQUEST - A field in the request is invalid.
• INTERNAL_SERVER_ERROR - An error occurred within the core server.

Request

Supported Media Types

• application/json; charset=utf-8

Path Parameters

• fqSiteName: string
  The fully qualified site name.

Header Parameters

• X-AID: string
  A header element containing the agent account identifier.
• X-JSESSIONID: string
  A header element containing the unique session identifier returned in the create automated agent session call.

Body ()

The object containing the request information.

Root Schema : com.rightnow.chat.rest.agent_api.model.requests.v1.ModifyPropertiesRequest

Type: object

Show Source

• customFields(optional): array customFields
  The list of custom fields.
• engagementId: integer(int64)
  The unique identifier of the chat engagement.
• propertiesMap(optional): object propertiesMap
  An optional map of key/value String pairs identifying the properties to be modified. The allowable map keys are : FIRST_NAME, LAST_NAME, EMAIL, QUESTION, PRODUCT_ID, CATEGORY_ID, CONTACT_ID, INCIDENT_ID
• sequenceNumber(optional): integer(int64)
  The client application defined transaction sequence number.
• timeCreated(optional): integer(int64)
  The time the request was created in milliseconds.
• type: string
  Allowed Values: [ "USER", "ENGAGEMENT" ]

  The engagement property type.

{
    "required":[
        "engagementId",
        "type"
    ],
    "properties":{
        "engagementId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the chat engagement."
        },
        "type":{
            "type":"string",
            "description":"The engagement property type.",
            "enum":[
                "USER",
                "ENGAGEMENT"
            ]
        },
        "propertiesMap":{
            "type":"object",
            "description":"An optional map of key/value String pairs identifying the properties to be modified.  The allowable map keys are : FIRST_NAME, LAST_NAME, EMAIL, QUESTION, PRODUCT_ID, CATEGORY_ID, CONTACT_ID, INCIDENT_ID"
        },
        "customFields":{
            "type":"array",
            "description":"The list of custom fields.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.common.model.types.v1.RestApiCustomField"
            }
        },
        "timeCreated":{
            "type":"integer",
            "format":"int64",
            "description":"The time the request was created in milliseconds."
        },
        "sequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The client application defined transaction sequence number."
        }
    }
}

Nested Schema : customFields

Type: array

The list of custom fields.

Show Source

• Array of: object com.rightnow.chat.rest.common.model.types.v1.RestApiCustomField

{
    "type":"array",
    "description":"The list of custom fields.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.common.model.types.v1.RestApiCustomField"
    }
}

Nested Schema : propertiesMap

Type: object

An optional map of key/value String pairs identifying the properties to be modified. The allowable map keys are : FIRST_NAME, LAST_NAME, EMAIL, QUESTION, PRODUCT_ID, CATEGORY_ID, CONTACT_ID, INCIDENT_ID

Nested Schema : com.rightnow.chat.rest.common.model.types.v1.RestApiCustomField

Type: object

Show Source

• id(optional): integer(int64)
  The custom field identifier
• name(optional): string
  Name of the custom field
• type(optional): string
  Allowed Values: [ "BOOLEAN", "DATE", "DATETIME", "INTEGER", "integer", "STRING", "DECIMAL" ]

  Type of custom field
• value(optional): string
  Value of the custom field

{
    "properties":{
        "name":{
            "type":"string",
            "description":"Name of the custom field"
        },
        "type":{
            "type":"string",
            "description":"Type of custom field",
            "enum":[
                "BOOLEAN",
                "DATE",
                "DATETIME",
                "INTEGER",
                "integer",
                "STRING",
                "DECIMAL"
            ]
        },
        "value":{
            "type":"string",
            "description":"Value of the custom field"
        },
        "id":{
            "type":"integer",
            "format":"int64",
            "description":"The custom field identifier"
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json; charset=utf-8

200 Response

The request completed successfully.

Body ()

Root Schema : com.rightnow.chat.rest.agent_api.model.responses.v1.ModifyPropertiesResponse

Type: object

Show Source

• clientId(optional): integer(int64)
  The unique identifier of the agent client, created to identify the agent during this agent session.
• clientIdString(optional): string
  The unique identifier of the agent client in string format, created to identify the agent during this agent session.
• clientSendTime(optional): integer(int64)
  The time when the client request was received in yyyy-MM-dd'T'HH:mm:ssXXX format.
• propertiesResultMap(optional): object propertiesResultMap
  The map of property modification results keyed by the property names identifying the success of each modification.
• sequenceNumber(optional): integer(int64)
  The client application defined transaction sequence number.
• sequenceNumberString(optional): string
  The client application defined transaction sequence number as a string.
• serviceFinishTime(optional): integer(int64)
  The time when the chat server completed processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format.
• serviceStartTime(optional): integer(int64)
  The time when the chat server began processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format.
• sessionId(optional): string
  The unique identifier of the agent session.

{
    "properties":{
        "propertiesResultMap":{
            "type":"object",
            "description":"The map of property modification results keyed by the property names identifying the success of each modification."
        },
        "clientSendTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the client request was received in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "serviceStartTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the chat server began processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "serviceFinishTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the chat server completed processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "sessionId":{
            "type":"string",
            "description":"The unique identifier of the agent session."
        },
        "clientId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the agent client, created to identify the agent during this agent session."
        },
        "clientIdString":{
            "type":"string",
            "description":"The unique identifier of the agent client in string format, created to identify the agent during this agent session."
        },
        "sequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The client application defined transaction sequence number."
        },
        "sequenceNumberString":{
            "type":"string",
            "description":"The client application defined transaction sequence number as a string."
        }
    }
}

Nested Schema : propertiesResultMap

Type: object

The map of property modification results keyed by the property names identifying the success of each modification.

400 Response

The validation of the request object failed.

Body ()

Root Schema : schema

Type: object

403 Response

The agent session identifier is unknown.

Body ()

Root Schema : schema

Type: object

404 Response

The resource was not found.

Body ()

Root Schema : schema

Type: object

500 Response

An error occurred in the chat server while processing the request.

Body ()

Root Schema : schema

Type: object

Back to Top

Examples

The following example shows how to modify multiple engagement properties with a single API call.

cURL Command Example

curl -X POST https://chat_rest_server_domain.com/engagement/api/agent/day001_221100_sql_001h/v1/modifyProperties?pool=297:1 -H 'Content-Type: application/json; charset=UTF-8' -H 'X-JSESSIONID: node01h8m13tljpm7ns8nayp0pid91' -d ' -H 'X-AID: 12' {"timeCreated" :1618317020415, "sequenceNumber" : 4,  "engagementId": 517, "type": "USER", "propertiesMap": { "CONTACT_ID":"10", "PRODUCT_ID":"44", "CATEGORY_ID":"27", "FIRST_NAME":"Update_First", "LAST_NAME":"Update_Last", "QUESTION":"Updated Question", "INCIDENT_ID":"321" }, "customFields": null}'

Request Body Example

The following shows an example of the request body in JSON format.

{
  "engagementId": 517,
  "type": "USER",
  "propertiesMap": {
    "CONTACT_ID":"10",
    "PRODUCT_ID":"44",
    "CATEGORY_ID":"27",
    "FIRST_NAME":"Update_First",
    "LAST_NAME":"Update_Last",
    "QUESTION":"Updated Question"
  },
  "customFields": null,
   "timeCreated": 1618317020415,
   "sequenceNumber": 4
}

Response Header Example

The following shows an example of the response header.

Status: 200 OK
Content-Type: application/json;charset=utf-8

Response Body Example

The following shows an example of the response body in JSON format.

{
  "propertiesResultMap": {
    "CONTACT_ID": true,
    "PRODUCT_ID": true,
    "CATEGORY_ID": true,
    "FIRST_NAME": true,
    "LAST_NAME": true,
    "QUESTION": true
  },
  "serviceStartTime": 1612295314598,
  "serviceFinishTime": 1612295314601,
  "sequenceNumber": 4,
  "sequenceNumberString": "4"
}

Back to Top