📌 What does this feature allow?
This API allows you to create a ticket in Cloud Chat from any external system, such as:
-
A telephony system (e.g., when a call arrives)
-
A form filled out on your website
-
An integration with CRM, ERP, or any custom tool
By using this route, you can:
-
Create a new ticket with status open, pending, or closed
-
Associate the ticket with a contact via email, phone, or identifier
-
Include an initial message (inbound or outbound)
-
Set custom conversation attributes at the time of creation
🧭 When to use this API?
Use when you need to start a conversation in Cloud Chat without the customer sending a message through an active channel.
Examples:
-
Received a call outside of Cloud Chat? → Generate a ticket with the call summary.
-
Someone filled out a form? → Automatically create the ticket and start correspondence via email.
-
Want to centralize communications from other sources? → Use this API as an entry point.
🔗 Endpoint
POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations
🔐 Required Headers
{
"content-type": "application/json",
"api_access_token": "YOUR_API_TOKEN"
}
🧾 Request Body
{
"inbox_id": "1",
"contact_identifier": "id_123",
"contact_email": "[email protected]",
"contact_phone_number": "+12345",
"message": {
"content": "Hello, I just filled out the form on the website and need assistance.",
"message_type": "incoming"
},
"status": "open", // Optional
"private": false, // Optional
"custom_attributes": { // Optional
"example1": "valueXPTO"
},
"additional_attributes": { // optional
"mail_subject": "Support Protocol ABCD"
},
"assignee_id": "1" // Optional
}
🧠 Explanation of Main Fields
inbox_id: Identifier of the inbox, obtainable from the browser bar (URI/route) when accessing the inbox settings.
assignee_id (optional): Identifier of the agent to be assigned at creation.
To reference the contact, send one of the following three fields:
-
contact_identifier: Unique contact ID -
contact_email: Contact's email -
contact_phone_number: Contact's phone number
message: The message object with the following fields:
-
content: the message content
-
message_type:
-
"incoming": message from the customer
-
"outgoing": sent by the agent
-
"activity": internal note
-
-
private: whether the message is visible to the customer (false) or internal (true)
additional_attributes → mail_subject (optional)
If the ticket is handled via email channel, you can use this field to customize the email subject sent to the contact when the conversation starts.
custom_attributes (optional but powerful)
You can add any custom conversation field already existing in your configuration directly here. To learn how to create custom fields, see this FAQ.
🎯 Does the ticket start as "open"?
Yes. The ticket will be created with status "open" by default, unless the status field is provided in the request, which makes it visible and ready for immediate support in the specified inbox.
🧪 How to test?
-
Access your api_access_token in the configuration panel.
-
Copy ACCOUNT_ID, INBOX_ID, and CLOUDCHAT_DOMAIN as described in this import FAQ.
-
Send the request via Postman or script.
-
Check in Cloud Chat if the ticket appeared in the correct inbox with complete information.
⚠️ Common Errors
Incorrect use of unique identifiers
The fields identifier, phone_number, and email are unique contact attributes. They should not be fixed in ticket creation requests.
Because the request uses upsert, if these are fixed, the result will always be a single contact being updated on each call, with all conversations linked to it.
Creating a Ticket does not create a contact
Manual ticket creation via API does not generate new contacts. The system only uses existing contacts.
Therefore, if the contact does not exist, you must create it beforehand before starting a conversation. Create it following this FAQ!