Objects
Updated at January 7th, 2025
Objects are conversations between the bot or the agent and the customers, where each segment of the conversation is referred to as a Child. Every conversation must have a designated Stream – a communication channel such as Chat, Email, Text/SMS, etc., that hosts the conversation.
The Object APIs category concentrates on a specific conversation, where the Stream is part of the identifying parameters. In the Streams APIs category, the Channel is the focal point of the request, and the objects and users are the filtering aspects.
POST: Create Object
This API creates a Conversation in a specified channel and returns an Object Id.
Sends the Stream (channel) id with body parameters.
POST /streams/{STREAM_ID}/objects
Authorizations:
path Parameters
|
STREAM_ID required
|
integer <int64>
Stream ID. This is a Cirrus generated number |
Request Body schema:
Description of request body parameters
| SubStreamId | integer <int64>
The subchannel ID of the conversation |
| Type | integer <int64>
The type of object used (text, link, photo, etc.)- See Enum for code |
| StatusId | string
The conversation’s current state (Open, Resolved, etc.) – See Enum for code |
| StreamProviderType | integer <int64>
Type of the object original stream provider |
| StreamProviderId | integer <int64>
A Cirrus generated number for the original stream provider |
| UserStreamProviderId | string
unique identifier of user, usually an email or a phone number, as it appears at the original provider |
| UserStreamProviderType | integer <int64>
Type of identifier used in of the userStreamProviderId parameter |
| UserIdentity | integer <int64>
A Cirrus generated number for the user. |
| ManagerId | integer <int64>
The manager (agent) who create the object (optional) |
| Content | string <JSON string>
String containing extended properties of the object |
| Message | string
(required) The text of the primary message. This is a mandatory/required field |
| sendToClient | boolean
If true - send message without saving it (relevant for SMS streams only) |
| createChildObject | boolean
If true - |
| User | object
The user that created the object |
POST: Create Child Object
This API creates a message (child) in a conversation (object) on behalf of the agent, sending it to the customer, or on behalf of the customer, displaying it to the agent.
The API returns the new child’s ID.
Required path parameters include the Stream (channel) ID and the Object (conversation) ID.
Required body parameters for a message on behalf of the customer:
a) The data “Type” see Enums
b) UserStreamProviderId – the email or phone number of the person you are sending the message on their behalf.
c) UserStreamProviderType of the channel. See Enums
d) The messages
Required body parameters for a message on behalf of the agent:
a) The data “Type” - See Enums
b) Add this Boolean field 'IsManager': true,
c) Enter the agent’s user ID 'UserIdentity' : 12345678,
d) UserStreamProviderId – the email or phone number of the person you are sending the message on their behalf.
e) UserStreamProviderType of the channel. See Enums
f) The messages
Note: After 24 hours from last sent message, APIs messages sent to customers will be blocked by WhatsApp.
POST /streams/STREAM_ID/objects/OBJECT_ID/child
POST /streams/STREAM_ID/objects/STREAM_PROVIDER_ID/STREAM_PROVIDER_TYPE/child
Authorizations:
path Parameters
|
STREAM_ID required
|
integer <int64>
The unique identifier for the stream (Cirrus channel) |
|
OBJECT_ID required
|
integer <int64>
The unique identifier for the object (Cirrus conversation) |
Request Body schema: application/json
Payload containing child object information
| id | integer <int64>
|
| type | integer <int64>
The type of the object |
| IsManager | boolean
Indicates whether this child was created by a manager |
| CreatedTime | string <datetime>
When the child was created |
| Message | string
The text containing the child’s primary message |
| Content | string <JSON string>
String containing extended properties of the child |
| User | object
The user that created the child |
GET: Object
This API returns the details of a specific conversation (object).
Data includes information about the customer, the agent, and a separate account of the messages (Child) of the conversation (Object).
Note that the last communication will appear at the top of the report.
Required path params are the Stream (channel) Id and Object (conversation) Id - Stream Id could be encrypted or not.
(GET) /streams/STREAM_ID/objects/OBJECT_ID
Example:
https://api.commbox.io/streams/532/objects/293854
Note: When Children are not included in the request, the API only returns the last message. When requesting logs (optional), the return will include all system actions (for example, CRM activity) for the conversation.
path Parameters
|
STREAM_ID required
|
integer <int64>
Stream Id is a Cirrus generated number for the channel. |
|
OBJECT_ID required
|
integer <int64>
Object Id is a Cirrus generated number for the conversation. |
query Parameters
| includeChilds | boolean
Return objects with their childs (optional, default false) |
| includeActivityLog | boolean
Return objects with their activity log (optional, default false) |
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | Array of objects |
data objects:
| objectId | integer
A Cirrus generated number for the conversation |
| streamid | integer
A Cirrus generated number for the channel – This will be the unencrypted format of the channel Id. |
| substreamid | integer
A Cirrus generated number for the subchannel. A Sub-stream is not required when calling an API. |
| streamProviderId | string
|
| streamProviderType | integer
|
| user_identity | integer
|
| firstName | string
When not provided, system will use the email address. |
| lastName | string
|
| userStreamProviderId | string
The unique Id for communication (email, phone number) |
| userStreamProviderType | integer
A Cirrus generated number – see Enums |
| content | string
|
| message | string
|
| createdTime | string
|
| updatedTime | string
|
| closeTime | string
|
| statusId | integer
|
| assignedManagerId | integer
Id of agent / admin |
| type | integer
|
| isManager | boolean
If True: User is an agent / admin If False: User is a customer |
| user | object |
user objects:
| id | integer
|
| uniqueId | string
|
| phone1 | string
As appears in the Customer Info section. System adds country code. |
| phone2 | string
|
string
|
|
| firstName | string
|
| lastName | string
|
| gender | string
|
| numberIdentities | integer
|
| locale | string
|
| birthday | string
|
| remarks | string
|
| content | string
|
| childs | Array of objects or objects |
child:
| id | integer
|
| object_id | integer
|
| content | string
|
| message | string
|
| createdTime | string
|
| streamProviderType | integer
|
| user | object |
user:
| id | integer
|
| managerId | integer
|
| isManager | boolean
|
| identity | object |
identity:
| id | integer
|
| streamProviderId | string
|
| streamProviderType | integer
|
| firstName | string
|
| lastName | string
|
| thumbnailUrl | string |
GET: Object's Activities
This API returns the data of a specific Activity Type listed in the query param of a specific conversation (object). Use the ActivityType Enum listed above to receive the desired information.
(GET) /objects/OBJECT_ID/activities?activityType=X_from_Enum
Example: To see the remarks added to the conversation (activity type #1)
https://api.commbox.io/objects/56575395/activities?activityType=1
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object Id is a Cirrus generated number for the conversation. |
Response Schema: application/json
| status | string
|
||||||||||||||||||||||||||
| description | string
|
||||||||||||||||||||||||||
| response_time | string
|
||||||||||||||||||||||||||
Array of objects
|
|||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||
GET: Object's Transcript
This API returns the transcript of a specific conversation (object).
Data includes information about the conversation (objectId), customer, the channel, sub-channel.
Note: The transcript field includes the conversation transcript with an external hyperlink to the Object (conversation) .
Required path params are the Stream (channel) Id and Object (conversation) Id - Stream Id could be encrypted or not.
(GET) /streams/STREAM_ID/objects/OBJECT_ID/transcript
Example:
https://api.commbox.io/streams/532/objects/293854/transcript
path Parameters
|
STREAM_ID required
|
integer <int64>
Stream Id is a Cirrus generated number for the channel. |
|
OBJECT_ID required
|
integer <int64>
Object Id is a Cirrus generated number for the conversation. |
Response Schema: application/json
| status | string
|
||||||||||||||||||||||||||||||||||||
| description | string
|
||||||||||||||||||||||||||||||||||||
| response_time | string
|
||||||||||||||||||||||||||||||||||||
Array of objects
|
|||||||||||||||||||||||||||||||||||||
Array
One of
| |||||||||||||||||||||||||||||||||||||
POST: Set Object Status
The conversation’s status indicates where the conversation has reached or heading. Statuses include “Open”, “Resolved”, “Archived”, etc.
This API updates the status of the conversation. See the Enum section for the Object Status Type.
https://api.commbox.io/objects/{OBJECT_ID}/status/{STATUS_ID}
Required path parameters include the Object (Conversation) Id and the desired updated status Id.
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object ID. This is a Cirrus generated number |
|
STATUS_ID required
|
integer
Status ID. This is a Cirrus generated number |
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | string |
POST: Set Object Content
Set the object's content.
https://api.commbox.io/objects/{OBJECT_ID}/content
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object ID. This is a Cirrus generated number |
Request Body schema: application/json
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | string |
POST: Add Acitvity Log
https://api.commbox.io/objects/{OBJECT_ID}/activitylog
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object ID. This is a Cirrus generated number |
Request Body schema: application/json
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | string |
POST: Add Remark Log
https://api.commbox.io/objects/{OBJECT_ID}/remarks
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object ID. This is a Cirrus generated number |
Request Body schema: application/json
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | string |
POST: Set Custom Indicator
https://api.commbox.io/objects/{OBJECT_ID}/indicators
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object ID. This is a Cirrus generated number |
Request Body schema: application/json
Optional description for new mail object in Markdown
object
|
|||||||||
| |||||||||
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | string |
DEL: Delete Custom Indicator
https://api.commbox.io/objects/{OBJECT_ID}/indicators/{INDICATOR_ID}
path Parameters
|
OBJECT_ID required
|
integer <int64>
Object ID. This is a Cirrus generated number |
|
INDICATOR_ID required
|
integer <int64>
Indicator ID. This is a Cirrus generated number |
Response Schema: application/json
| status | string
|
| description | string
|
| response_time | string
|
| data | string |
