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
API key is needed to authorize requests. You can get your API key via the management console.
A Bearer Token is needed to be set in the Authorization header of every API call.
For additional support you can contact us.
A unique identifier for the channel (CommBox generated)
Request body containing the conversation details, user information, and channel-specific parameters
Email without attachments
{
"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"
}
}
}{
"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"
}
}
}{
"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"
}
}
}{
"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"
}
}
}{
"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"
}
}
}The subchannel ID of the conversation
The type of object used (text, link, photo, etc.)- See Enum for code
The conversation’s current state (Open, Resolved, etc.) – See Enum for code
CommBox identification for the communication channel type (stream)- see Enums
Unique identifier by external provider (WhatsApp, email, etc.) for the original conversation
unique identifier of user, usually an email or a phone number, as it appears at the original provider
Type of identifier used in of the userStreamProviderId parameter - See Enums
A CommBox generated number for the user.
The manager (agent) who create the object (optional)
String containing extended properties of the object
(required) The text of the primary message. Required field
When true, will send SMS messages without saving them (relevant for SMS streams only)
The customer (end-user) of the object
Email with one PDF attachment
In the 'data' field, paste the JSON below. In the 'file' field, click 'Choose File' and select invoice.pdf from your computer.
{
"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\"}}"
}Email with 3 file attachments (PDF, Excel, PowerPoint)
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.
{
"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\"}}"
}JSON string containing email metadata and conversation details (same structure as application/json examples above)
File attachment(s). Use 'file' as the form field name. Multiple files can be attached by repeating the 'file' field.
OK
Bad Request - The request could not be understood by the server. Incoming parameters might not be valid
Unauthorized - The supplied credentials, if any, are not sufficient to access the resource
Not Found - The requested resource is not found
Too Many Requests - Too many requests have been made in a short period of time (Throttling)
Internal Server Error - The server could not return the representation due to an internal server error
{
"status": 500,
"description": "Operation failed",
"response_time": "2025-04-15T07:24:52.956Z"
}