Skip to main content
POST
/
api
/
v1
/
accounts
/
{account_id}
/
conversations
Create New Conversation
curl --request POST \
  --url https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "source_id": "1234567890",
  "inbox_id": 1,
  "contact_id": 1,
  "additional_attributes": {
    "browser": "Chrome",
    "browser_version": "89.0.4389.82",
    "os": "Windows",
    "os_version": "10"
  },
  "custom_attributes": {
    "attribute_key": "attribute_value",
    "priority_conversation_number": 3
  },
  "status": "open",
  "assignee_id": 1,
  "team_id": 1,
  "snoozed_until": "2030-07-21T17:32:28Z",
  "message": {
    "content": "Hello, how can I help you?",
    "template_params": {
      "name": "sample_issue_resolution",
      "category": "UTILITY",
      "language": "en_US",
      "processed_params": {
        "1": "Chatwoot"
      }
    }
  }
}'
{
  "id": 123,
  "account_id": 123,
  "inbox_id": 123
}

Authorizations

​
api_access_token
string
header
required

This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.

Path Parameters

​
account_id
integer
required

The numeric ID of the account

Body

application/json
​
source_id
string
required

Conversation source id

Example:

"1234567890"

​
inbox_id
integer
required

Id of inbox in which the conversation is created <br/> Allowed Inbox Types: Website, Phone, Api, Email

Example:

1

​
contact_id
integer

Contact Id for which conversation is created

Example:

1

​
additional_attributes
object

Lets you specify attributes like browser information

Example:
{
  "browser": "Chrome",
  "browser_version": "89.0.4389.82",
  "os": "Windows",
  "os_version": "10"
}
​
custom_attributes
object

The object to save custom attributes for conversation, accepts custom attributes key and value

Example:
{
  "attribute_key": "attribute_value",
  "priority_conversation_number": 3
}
​
status
enum<string>

Specify the conversation whether it's pending, open, closed

Available options:
open,
resolved,
pending
Example:

"open"

​
assignee_id
integer

Agent Id for assigning a conversation to an agent

Example:

1

​
team_id
integer

Team Id for assigning a conversation to a team\

Example:

1

​
snoozed_until
string<date-time>

Snoozed until date time

Example:

"2030-07-21T17:32:28Z"

​
message
object

The initial message to be sent to the conversation

Response

Success

​
id
number

ID of the conversation

​
account_id
number

Account Id

​
inbox_id
number

ID of the inbox

⌘I