> ## 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.
# Create Object
> This API creates a new conversation (Object) in a specified channel (Stream) and returns the Object ID.
Add the Stream ID in the path along with the required parameters in the request body.
### Supported channels:
- **Email** - Create email conversations with optional attachments
- **SMS** - Send SMS messages (single or multi-recipient)
- **WhatsApp** - Send WhatsApp messages using WhatsApp templates
- **Chat** - Create chat conversations
### For emails with attachments:
Use multipart/form-data format:
- Enter the data pairing the type and its value (see example)
- Add a field named **file**
- Select your attachment file from your computer.
When using cURL or code, use the syntax: --form 'file=@/path/to/your-file.pdf'
- You can add multiple files by repeating the **file** field
## OpenAPI
````json POST /streams/{STREAM_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": {
"/streams/{STREAM_ID}/objects": {
"post": {
"tags": [
"Objects"
],
"summary": "Create Object",
"description": "This API creates a new conversation (Object) in a specified channel (Stream) and returns the Object ID.\n\nAdd the Stream ID in the path along with the required parameters in the request body.\n\n### Supported channels:\n - **Email** - Create email conversations with optional attachments\n - **SMS** - Send SMS messages (single or multi-recipient)\n - **WhatsApp** - Send WhatsApp messages using WhatsApp templates\n - **Chat** - Create chat conversations\n\n### For emails with attachments:\nUse multipart/form-data format:\n - Enter the data pairing the type and its value (see example)\n - Add a field named **file**\n - Select your attachment file from your computer.\n When using cURL or code, use the syntax: --form 'file=@/path/to/your-file.pdf'\n - You can add multiple files by repeating the **file** field\n\n",
"operationId": "Create_Object",
"parameters": [
{
"name": "STREAM_ID",
"in": "path",
"description": "A unique identifier for the channel (CommBox generated)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Request body containing the conversation details, user information, and channel-specific parameters",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Object"
},
"examples": {
"Mail": {
"summary": "Email without attachments",
"value": {
"data": {
"Type": 5,
"StatusId": 1,
"StreamProviderType": 4,
"StreamProviderId": "b9910a75a46c492c9cf46a910cdba0012",
"UserStreamProviderId": "john.doe@gmail.com",
"UserStreamProviderType": 4,
"ManagerId": 12345,
"Content": {
"subject": "mail subject",
"to": [
{
"address": "john.doe@gmail.com"
}
]
},
"Message": "some message",
"User": {
"UniqueId": "01234567",
"LastName": "Doe",
"FirstName": "John",
"Phone1": "05055555555",
"Email": "john.doe@gmail.com",
"Remarks": "some remark for user"
}
}
}
},
"SMS": {
"value": {
"data": {
"Type": 4,
"StatusId": 1,
"StreamProviderType": 5,
"StreamProviderId": "972544444444",
"UserStreamProviderId": "972544444444",
"UserStreamProviderType": 5,
"ManagerId": 36197,
"Message": "some message",
"User": {
"UniqueId": "01234567",
"LastName": "Doe",
"FirstName": "John",
"Phone1": "180095845823",
"Email": "john.doe@gmail.com",
"Remarks": "some remark for user"
}
}
}
},
"SMS Multi-recipient": {
"value": {
"data": {
"Type": 4,
"StatusId": 1,
"StreamProviderType": 5,
"UserStreamProviderId": "972544444444",
"UserStreamProviderType": 5,
"ManagerId": 36197,
"sendToClient": true,
"Content": {
"to": [
"972522222222"
]
},
"Message": "some message",
"User": {
"UniqueId": "01234567",
"LastName": "Doe",
"FirstName": "John",
"Phone1": "972544444444",
"Email": "john.doe@gmail.com",
"Remarks": "some remark for user"
}
}
}
},
"WhatsApp": {
"value": {
"data": {
"Type": 4,
"StatusId": 1,
"StreamProviderType": 5,
"StreamProviderId": "972544444444",
"UserStreamProviderId": "972544444444",
"UserStreamProviderType": 5,
"ManagerId": 36197,
"Content": {
"to": [
"972522222222"
],
"whatsapp_hsm_name": "test_template",
"whatsapp_localizable_params": [
"check_1"
],
"whatsapp_language_code": "en"
},
"Message": "some message",
"User": {
"UniqueId": "01234567",
"LastName": "Doe",
"FirstName": "John",
"Phone1": "972544444444",
"Email": "john.doe@gmail.com",
"Remarks": "some remark for user"
}
}
}
},
"Chat": {
"value": {
"data": {
"Type": 4,
"StatusId": 1,
"StreamProviderType": 0,
"UserStreamProviderId": "972544444444",
"UserStreamProviderType": 5,
"UserIdentity": 100000000419660,
"ManagerId": 36197,
"Message": "some message",
"createChildObject": true,
"User": {
"UniqueId": "01234567",
"LastName": "Doe",
"FirstName": "John",
"Phone1": "972544444444",
"Email": "JohnDoe@gmail.com",
"Remarks": "some remark for user"
}
}
}
}
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "string",
"description": "JSON string containing email metadata and conversation details (same structure as application/json examples above)",
"example": "{\"Type\": 5, \"StatusId\": 13, \"StreamProviderType\": 4, \"UserStreamProviderId\": \"sender@yourdomain.com\", \"UserStreamProviderType\": 4, \"ManagerId\": 28361974, \"Content\": {\"subject\": \"Invoice for September 2024\", \"to\": [{\"address\": \"customer@example.com\", \"name\": \"John Doe\"}]}, \"Message\": \"Please find attached your invoice.\", \"User\": {\"UniqueId\": \"CUST-12345\", \"LastName\": \"Doe\", \"FirstName\": \"John\", \"Phone1\": \"1234567890\", \"Email\": \"customer@example.com\"}}"
},
"file": {
"type": "array",
"description": "File attachment(s). Use 'file' as the form field name. Multiple files can be attached by repeating the 'file' field.",
"items": {
"type": "string",
"format": "binary"
}
}
}
},
"examples": {
"Mail with single attachment": {
"summary": "Email with one PDF attachment",
"description": "In the 'data' field, paste the JSON below. In the 'file' field, click 'Choose File' and select invoice.pdf from your computer.",
"value": {
"data": "{\"Type\": 5, \"StatusId\": 13, \"StreamProviderType\": 4, \"UserStreamProviderId\": \"sender@yourdomain.com\", \"UserStreamProviderType\": 4, \"ManagerId\": 28361974, \"Content\": {\"subject\": \"Invoice for September 2024\", \"to\": [{\"address\": \"customer@example.com\", \"name\": \"John Doe\"}]}, \"Message\": \"Please find attached your invoice for September 2024.\", \"User\": {\"UniqueId\": \"CUST-12345\", \"LastName\": \"Doe\", \"FirstName\": \"John\", \"Phone1\": \"1234567890\", \"Email\": \"customer@example.com\"}}"
}
},
"Mail with multiple attachments": {
"summary": "Email with 3 file attachments (PDF, Excel, PowerPoint)",
"description": "In the 'data' field, paste the JSON below. Add 3 separate 'file' fields and select report.pdf, analysis.xlsx, and presentation.pptx from your computer.",
"value": {
"data": "{\"Type\": 5, \"StatusId\": 13, \"StreamProviderType\": 4, \"UserStreamProviderId\": \"sender@yourdomain.com\", \"UserStreamProviderType\": 4, \"ManagerId\": 28361974, \"Content\": {\"subject\": \"Monthly Report and Analysis\", \"to\": [{\"address\": \"manager@example.com\", \"name\": \"Jane Manager\"}], \"cc\": [{\"address\": \"team@example.com\", \"name\": \"Team Lead\"}]}, \"Message\": \"Please review the attached monthly report and analysis.\", \"User\": {\"UniqueId\": \"MGR-001\", \"LastName\": \"Manager\", \"FirstName\": \"Jane\", \"Email\": \"manager@example.com\"}}"
}
}
},
"encoding": {
"data": {
"contentType": "application/json"
},
"file": {
"contentType": "application/octet-stream"
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": 200
},
"description": {
"type": "string",
"example": "OK"
},
"response_time": {
"type": "string",
"example": "2024-08-06T07:51:52.2581942Z"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 294159
}
}
}
}
}
}
}
},
"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": 404
},
"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"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Object": {
"type": "object",
"properties": {
"SubStreamId": {
"type": "integer",
"format": "int64",
"description": "The subchannel ID of the conversation"
},
"Type": {
"type": "integer",
"format": "int64",
"description": "The type of object used (text, link, photo, etc.)- See Enum for code"
},
"StatusId": {
"type": "string",
"description": "The conversation’s current state (Open, Resolved, etc.) – See Enum for code"
},
"StreamProviderType": {
"type": "integer",
"format": "int64",
"description": "CommBox identification for the communication channel type (stream)- see Enums"
},
"StreamProviderId": {
"type": "string",
"description": "Unique identifier by external provider (WhatsApp, email, etc.) for the original conversation "
},
"UserStreamProviderId": {
"type": "string",
"description": "unique identifier of user, usually an email or a phone number, as it appears at the original provider"
},
"UserStreamProviderType": {
"type": "integer",
"format": "int64",
"description": "Type of identifier used in of the userStreamProviderId parameter - See Enums"
},
"UserIdentity": {
"type": "integer",
"format": "int64",
"description": "A CommBox generated number for the user."
},
"ManagerId": {
"type": "integer",
"format": "int64",
"description": "The manager (agent) who create the object (optional)"
},
"Content": {
"type": "string",
"format": "JSON string",
"description": "String containing extended properties of the object"
},
"Message": {
"type": "string",
"description": "(required) The text of the primary message. Required field"
},
"sendToClient": {
"type": "boolean",
"description": "When true, will send SMS messages without saving them (relevant for SMS streams only)"
},
"User": {
"type": "object",
"description": "The customer (end-user) of the object"
}
}
}
}
}
}
````