> ## Documentation Index
> Fetch the complete documentation index at: https://help.commbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get User Objects
> This API retrieves conversation objects associated with a specific user identity. In its upgraded V2 version, it also provides the real-time count of unread chat messages for each conversation, enabling organizations to display up-to-date unread message indicators on their websites or applications.
Path param includes the userIdentityId.
Obtain this 'user_identity' value from the Get Object API using the channel and conversation IDs.
## OpenAPI
````json GET /v2/users/identities/{USER_IDENTITY_ID}/objects
{
"openapi": "3.0.3",
"info": {
"title": "CommBox API",
"x-logo": {
"url": "https://www.commbox.io/logo/commbox_logo_large.png"
},
"version": "2.07",
"termsOfService": "https://www.commbox.io/end-user-license-agreement-eula/",
"contact": {
"name": "commbox",
"url": "https://www.commbox.io",
"email": "contactus@commbox.io"
}
},
"servers": [
{
"url": "https://api.commbox.io/",
"description": "Production server"
}
],
"paths": {
"/v2/users/identities/{USER_IDENTITY_ID}/objects": {
"get": {
"tags": [
"Users"
],
"summary": "Get User Objects",
"description": "This API retrieves conversation objects associated with a specific user identity. In its upgraded V2 version, it also provides the real-time count of unread chat messages for each conversation, enabling organizations to display up-to-date unread message indicators on their websites or applications.
Path param includes the userIdentityId.
Obtain this 'user_identity' value from the Get Object API using the channel and conversation IDs.",
"operationId": "Get_User_Objects",
"parameters": [
{
"name": "USER_IDENTITY_ID",
"in": "path",
"description": "Only return objects created by this user",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"totalUnreadChatMessages": {
"type": "integer",
"description": "Total count of unread chat messages across all conversations"
},
"status": {
"type": "integer"
},
"description": {
"type": "string"
},
"response_time": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"objectId": {
"type": "integer"
},
"streamId": {
"type": "integer"
},
"subStreamId": {
"type": "integer"
},
"streamProviderId": {
"type": "string"
},
"streamProviderType": {
"type": "integer"
},
"user_identity": {
"type": "integer"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"moduleId": {
"type": "integer"
},
"userStreamProviderId": {
"type": "string"
},
"userStreamProviderType": {
"type": "integer"
},
"content": {
"type": "string"
},
"message": {
"type": "string"
},
"createdTime": {
"type": "string",
"format": "date-time"
},
"updatedTime": {
"type": "string",
"format": "date-time"
},
"closedTime": {
"type": "string",
"format": "date-time",
"nullable": true
},
"firstResponseTime": {
"type": "string",
"format": "date-time"
},
"lastResponseTime": {
"type": "string",
"format": "date-time"
},
"statusId": {
"type": "integer"
},
"assignedManagerId": {
"type": "integer"
},
"lastAssignedManagerId": {
"type": "integer"
},
"type": {
"type": "integer"
},
"user": {
"$ref": "#/components/schemas/User"
},
"isManager": {
"type": "boolean"
},
"childs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"objectId": {
"type": "integer"
},
"content": {
"type": "string"
},
"message": {
"type": "string"
},
"createdTime": {
"type": "string",
"format": "date-time"
},
"streamProviderType": {
"type": "integer"
},
"type": {
"type": "integer"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"managerId": {
"type": "integer"
},
"isManager": {
"type": "boolean"
},
"encryptedId": {
"type": "string"
},
"identity": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"streamProviderId": {
"type": "string"
},
"streamProviderType": {
"type": "integer"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"thumbnailUrl": {
"type": "string"
}
}
},
"uniqueId": {
"type": "string",
"nullable": true
},
"phone1": {
"type": "string",
"nullable": true
},
"phone2": {
"type": "string",
"nullable": true
},
"email": {
"type": "string",
"nullable": true
},
"firstName": {
"type": "string",
"nullable": true
},
"lastName": {
"type": "string",
"nullable": true
},
"gender": {
"type": "string",
"nullable": true
},
"numberIdentities": {
"type": "integer"
},
"locale": {
"type": "string",
"nullable": true
},
"birthday": {
"type": "string",
"nullable": true
},
"remarks": {
"type": "string",
"nullable": true
},
"content": {
"type": "string",
"nullable": true
}
}
}
}
}
},
"activityLogs": {
"type": "array",
"items": {
"type": "object"
}
},
"tagsObjectId": {
"type": "array",
"items": {
"type": "integer"
}
},
"customerParticipants": {
"type": "array",
"items": {
"type": "object"
}
},
"unreadMessages": {
"type": "integer",
"description": "Count of unread messages for this specific conversation"
}
}
}
}
}
},
"examples": {
"success": {
"summary": "Successful response with conversation data",
"value": {
"totalUnreadChatMessages": 2,
"status": 200,
"description": "Operation successful",
"response_time": "2026-02-12T15:09:23.9981289Z",
"data": [
{
"objectId": 396001,
"streamId": 19155,
"subStreamId": 0,
"streamProviderId": "",
"streamProviderType": 0,
"user_identity": 558355,
"firstName": "",
"lastName": "",
"moduleId": 0,
"userStreamProviderId": "d7655a64-ac14-4aa1-8907-1e26402ac6da",
"userStreamProviderType": 6,
"content": "{\"guidRT\":\"d34f89f73ffb4ec9909b7da1964cb7cb\",\"languages\":[{\"Item1\":\"en\",\"Item2\":1471163}]}",
"message": "What is your ID number?
",
"createdTime": "2026-02-12T15:01:02",
"updatedTime": "2026-02-12T15:08:16",
"closedTime": null,
"firstResponseTime": "2026-02-12T15:01:27",
"lastResponseTime": "2026-02-12T15:09:13",
"statusId": 1,
"assignedManagerId": 0,
"lastAssignedManagerId": 0,
"type": 0,
"user": {
"id": 545516,
"managerId": null,
"isManager": false,
"encryptedId": null,
"identity": null,
"uniqueId": "",
"phone1": "",
"phone2": "",
"email": "",
"firstName": "",
"lastName": "",
"gender": "",
"numberIdentities": 1,
"locale": "",
"birthday": "",
"remarks": "",
"content": "{}"
},
"isManager": false,
"childs": [
{
"id": 1471164,
"objectId": 396001,
"content": "{\"messageAlreadyRenderedFromClient\":true}",
"message": "Hi, How can I help you?",
"createdTime": "2026-02-12T15:00:57",
"streamProviderType": 0,
"type": 11,
"user": {
"id": 545437,
"managerId": 545437,
"isManager": true,
"encryptedId": "HnJymfEHh8dORgiV0otwEgRpcFYJqKfueiQqPvbZTrs%3d",
"identity": {
"id": 558237,
"streamProviderId": "",
"streamProviderType": 0,
"firstName": "AI Agent",
"lastName": "",
"thumbnailUrl": ""
},
"uniqueId": null,
"phone1": null,
"phone2": null,
"email": null,
"firstName": null,
"lastName": null,
"gender": null,
"numberIdentities": 0,
"locale": null,
"birthday": null,
"remarks": null,
"content": null
}
}
],
"activityLogs": [],
"tagsObjectId": [],
"customerParticipants": [],
"unreadMessages": 2
}
]
}
}
}
}
}
},
"400": {
"description": "Bad Request - The request could not be understood by the server. Incoming parameters might not be valid",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400
},
"description": {
"type": "string",
"example": "Bad Request"
},
"response_time": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - The supplied credentials, if any, are not sufficient to access the resource",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401
},
"description": {
"type": "string",
"example": "Unauthorized access"
},
"response_time": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"404": {
"description": "Not Found - The requested resource is not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400
},
"description": {
"type": "string",
"example": "Not found"
},
"response_time": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests - Too many requests have been made in a short period of time (Throttling)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 429
},
"description": {
"type": "string",
"example": "Too Many Requests"
},
"response_time": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error - The server could not return the representation due to an internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 500
},
"description": {
"type": "string",
"example": "Operation failed"
},
"response_time": {
"type": "string",
"format": "date-time"
}
}
},
"example": {
"status": 500,
"description": "Operation failed",
"response_time": "2025-04-15T07:24:52.956691Z"
}
}
}
},
"501": {
"description": "Not Implemented - The requested operation is not supported",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 501
},
"description": {
"type": "string",
"example": "Not Implemented"
},
"response_time": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"Id": {
"type": "integer",
"format": "int64",
"description": "User ID. This is a commbox generated number for the customer"
},
"UniqueId": {
"type": "string",
"format": "50",
"description": "User’s unique identifier. This can be an email, social security number or any other type of unique string determined by the brand administrators"
},
"Phone1": {
"type": "string",
"format": "numeric string (20)",
"description": "User’s phone number (should include country and area code without leading + or 00)"
},
"Phone2": {
"type": "string",
"format": "numeric string (20)",
"description": "User’s additional phone number (should include country and area code without leading + or 00)"
},
"Email": {
"type": "string",
"format": "255",
"description": "User's Email."
},
"FirstName": {
"type": "string",
"format": "100",
"description": "User’s first name"
},
"LastName": {
"type": "string",
"format": "100",
"description": "User’s last name"
},
"Gender": {
"type": "string",
"format": "1",
"description": "User’s gender (‘M’ for male, ‘F’ for female)"
},
"Locale": {
"type": "object",
"description": "User’s locale"
},
"Birthday": {
"type": "string",
"format": "date",
"description": "User’s birthday"
},
"NumIdentities": {
"type": "integer",
"description": "Number of active identities that are connected to this user"
},
"IsManager": {
"type": "boolean",
"description": "Indicates whether this user is a agent or an admin (true) or a customer (false)"
},
"Remarks": {
"type": "string",
"description": "Free text containing general remarks about the user"
},
"Identity": {
"type": "object",
"description": "Identity object that is connected to the user"
}
}
}
}
}
}
````