Create New Conversation

POST

api

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"
}
'

import requests

url = "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations"

payload = {
    "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"
}
headers = {
    "api_access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_access_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_access_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations"

	payload := strings.NewReader("{\n  \"source_id\": \"1234567890\",\n  \"inbox_id\": 1,\n  \"contact_id\": 1,\n  \"additional_attributes\": {\n    \"browser\": \"Chrome\",\n    \"browser_version\": \"89.0.4389.82\",\n    \"os\": \"Windows\",\n    \"os_version\": \"10\"\n  },\n  \"custom_attributes\": {\n    \"attribute_key\": \"attribute_value\",\n    \"priority_conversation_number\": 3\n  },\n  \"status\": \"open\",\n  \"assignee_id\": 1,\n  \"team_id\": 1,\n  \"snoozed_until\": \"2030-07-21T17:32:28Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations")
  .header("api_access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_id\": \"1234567890\",\n  \"inbox_id\": 1,\n  \"contact_id\": 1,\n  \"additional_attributes\": {\n    \"browser\": \"Chrome\",\n    \"browser_version\": \"89.0.4389.82\",\n    \"os\": \"Windows\",\n    \"os_version\": \"10\"\n  },\n  \"custom_attributes\": {\n    \"attribute_key\": \"attribute_value\",\n    \"priority_conversation_number\": 3\n  },\n  \"status\": \"open\",\n  \"assignee_id\": 1,\n  \"team_id\": 1,\n  \"snoozed_until\": \"2030-07-21T17:32:28Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_id\": \"1234567890\",\n  \"inbox_id\": 1,\n  \"contact_id\": 1,\n  \"additional_attributes\": {\n    \"browser\": \"Chrome\",\n    \"browser_version\": \"89.0.4389.82\",\n    \"os\": \"Windows\",\n    \"os_version\": \"10\"\n  },\n  \"custom_attributes\": {\n    \"attribute_key\": \"attribute_value\",\n    \"priority_conversation_number\": 3\n  },\n  \"status\": \"open\",\n  \"assignee_id\": 1,\n  \"team_id\": 1,\n  \"snoozed_until\": \"2030-07-21T17:32:28Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "account_id": 123,
  "inbox_id": 123
}

{
  "description": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

Email inboxes

When the target inbox is an Email inbox, a few extra fields control the subject line and the recipients of the outgoing email. They map to the fields an agent fills in when composing a new email conversation from the dashboard.

Dashboard field	API field	Notes
Via (From)	`inbox_id`	Not set directly. The From address is resolved from the inbox’s configuration.
To	`source_id` + `contact_id`	For an Email inbox, `source_id` is the contact’s email address.
Subject	`additional_attributes.mail_subject`	Stored on the conversation and reused for the whole thread.
Cc	`message.cc_emails`	Comma-separated list.
Bcc	`message.bcc_emails`	Comma-separated list.
—	`message.to_emails`	Comma-separated list. Overrides the contact’s email as the recipient.

curl --request POST \
  --url https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations \
  --header 'api_access_token: <your-access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "source_id": "john@example.com",
    "inbox_id": 1,
    "contact_id": 1,
    "additional_attributes": {
      "mail_subject": "Issue with my recent order"
    },
    "message": {
      "content": "Hi John, could you share your order number?",
      "cc_emails": "billing@example.com, support@example.com",
      "bcc_emails": "archive@example.com"
    }
  }'

cc_emails, bcc_emails and to_emails belong to the message object, not to additional_attributes. They are only processed for Email inboxes and are ignored on every other channel.

A few things to keep in mind:

All three email lists take a comma-separated string, not an array. Whitespace around the addresses is stripped. If any address is not a valid email, the request fails with Invalid email address.
mail_subject applies to the whole conversation, not just the first message. The first email goes out with the subject as-is; from the second message onwards, replies are sent as Re: <subject>. Private notes and activity messages are not counted.
If you omit mail_subject, Chatwoot falls back to [#<conversation_display_id>] New messages on this conversation.
The From address cannot be set per request. It is resolved from the inbox and channel configuration — for inboxes using SMTP or OAuth it is the channel’s email address, otherwise it is the inbox’s configured email address, falling back to the account’s support email.

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

Id of inbox in which the conversation is created
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

Show child attributes

Response

Success

number

ID of the conversation

account_id

number

Account Id

inbox_id

number

ID of the inbox

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"
}
'

import requests

url = "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations"

payload = {
    "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"
}
headers = {
    "api_access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_access_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_access_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations"

	payload := strings.NewReader("{\n  \"source_id\": \"1234567890\",\n  \"inbox_id\": 1,\n  \"contact_id\": 1,\n  \"additional_attributes\": {\n    \"browser\": \"Chrome\",\n    \"browser_version\": \"89.0.4389.82\",\n    \"os\": \"Windows\",\n    \"os_version\": \"10\"\n  },\n  \"custom_attributes\": {\n    \"attribute_key\": \"attribute_value\",\n    \"priority_conversation_number\": 3\n  },\n  \"status\": \"open\",\n  \"assignee_id\": 1,\n  \"team_id\": 1,\n  \"snoozed_until\": \"2030-07-21T17:32:28Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations")
  .header("api_access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_id\": \"1234567890\",\n  \"inbox_id\": 1,\n  \"contact_id\": 1,\n  \"additional_attributes\": {\n    \"browser\": \"Chrome\",\n    \"browser_version\": \"89.0.4389.82\",\n    \"os\": \"Windows\",\n    \"os_version\": \"10\"\n  },\n  \"custom_attributes\": {\n    \"attribute_key\": \"attribute_value\",\n    \"priority_conversation_number\": 3\n  },\n  \"status\": \"open\",\n  \"assignee_id\": 1,\n  \"team_id\": 1,\n  \"snoozed_until\": \"2030-07-21T17:32:28Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_id\": \"1234567890\",\n  \"inbox_id\": 1,\n  \"contact_id\": 1,\n  \"additional_attributes\": {\n    \"browser\": \"Chrome\",\n    \"browser_version\": \"89.0.4389.82\",\n    \"os\": \"Windows\",\n    \"os_version\": \"10\"\n  },\n  \"custom_attributes\": {\n    \"attribute_key\": \"attribute_value\",\n    \"priority_conversation_number\": 3\n  },\n  \"status\": \"open\",\n  \"assignee_id\": 1,\n  \"team_id\": 1,\n  \"snoozed_until\": \"2030-07-21T17:32:28Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "account_id": 123,
  "inbox_id": 123
}

{
  "description": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

Getting Started

Application APIs

Platform APIs

Client APIs

Other APIs

Email inboxes

Authorizations

Path Parameters

Body

Response

​Email inboxes

Authorizations

Path Parameters

Body

Response

Email inboxes