Create conversation

curl --request POST \
  --url https://{your-subdomain}.neetochat.com/api/external/v2/conversations \
  --header 'Accept: <accept>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "visitor_attributes": {
    "email": "sam@example.com",
    "name": "Sam Brown",
    "phone_number": "+14155550123",
    "user_identifier": "customer-1042",
    "traits": {
      "plan": "Pro"
    }
  },
  "messages_attributes": [
    {
      "body": "Hi, I need help with a refund."
    }
  ],
  "title": "Refund for order #1042",
  "status": "open",
  "priority": "high",
  "assignee_email": "oliver@example.com",
  "group_name": "Billing",
  "tags": [
    "refund",
    "priority-customer"
  ],
  "ticket_fields": {
    "Order number": "1042"
  },
  "origin_page_url": "https://example.com/pricing",
  "origin_page_title": "Pricing"
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Api-Key': '<x-api-key>',
    Accept: '<accept>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    visitor_attributes: {
      email: 'sam@example.com',
      name: 'Sam Brown',
      phone_number: '+14155550123',
      user_identifier: 'customer-1042',
      traits: {plan: 'Pro'}
    },
    messages_attributes: [{body: JSON.stringify('Hi, I need help with a refund.')}],
    title: 'Refund for order #1042',
    status: 'open',
    priority: 'high',
    assignee_email: 'oliver@example.com',
    group_name: 'Billing',
    tags: ['refund', 'priority-customer'],
    ticket_fields: {'Order number': '1042'},
    origin_page_url: 'https://example.com/pricing',
    origin_page_title: 'Pricing'
  })
};

fetch('https://{your-subdomain}.neetochat.com/api/external/v2/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{your-subdomain}.neetochat.com/api/external/v2/conversations"

payload = {
    "visitor_attributes": {
        "email": "sam@example.com",
        "name": "Sam Brown",
        "phone_number": "+14155550123",
        "user_identifier": "customer-1042",
        "traits": { "plan": "Pro" }
    },
    "messages_attributes": [{ "body": "Hi, I need help with a refund." }],
    "title": "Refund for order #1042",
    "status": "open",
    "priority": "high",
    "assignee_email": "oliver@example.com",
    "group_name": "Billing",
    "tags": ["refund", "priority-customer"],
    "ticket_fields": { "Order number": "1042" },
    "origin_page_url": "https://example.com/pricing",
    "origin_page_title": "Pricing"
}
headers = {
    "X-Api-Key": "<x-api-key>",
    "Accept": "<accept>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "conversation": {
    "id": "de414e85-a1b5-4240-a465-7b32606980ce",
    "status": "open",
    "title": "Refund for order #1042",
    "priority": "low",
    "channel_name": "b945fd3cd2573017052901d6dbd0832f",
    "origin_page_url": "https://example.com/pricing",
    "origin_page_title": "Pricing",
    "created_at": "2026-09-23T18:07:53.661Z",
    "updated_at": "2026-10-05T16:26:58.143Z",
    "agent": {
      "id": "05665eee-4602-4317-8f7f-767b04274e5f",
      "name": "Oliver Smith",
      "email": "oliver@example.com"
    },
    "group": {
      "id": null,
      "name": null
    },
    "visitor": {
      "id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
      "name": "Sam Brown",
      "email": "sam@example.com",
      "phone_number": null,
      "user_identifier": null
    }
  }
}

{
  "error": "A conversation must include at least one message."
}

POST

conversations

Create conversation

curl --request POST \
  --url https://{your-subdomain}.neetochat.com/api/external/v2/conversations \
  --header 'Accept: <accept>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "visitor_attributes": {
    "email": "sam@example.com",
    "name": "Sam Brown",
    "phone_number": "+14155550123",
    "user_identifier": "customer-1042",
    "traits": {
      "plan": "Pro"
    }
  },
  "messages_attributes": [
    {
      "body": "Hi, I need help with a refund."
    }
  ],
  "title": "Refund for order #1042",
  "status": "open",
  "priority": "high",
  "assignee_email": "oliver@example.com",
  "group_name": "Billing",
  "tags": [
    "refund",
    "priority-customer"
  ],
  "ticket_fields": {
    "Order number": "1042"
  },
  "origin_page_url": "https://example.com/pricing",
  "origin_page_title": "Pricing"
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Api-Key': '<x-api-key>',
    Accept: '<accept>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    visitor_attributes: {
      email: 'sam@example.com',
      name: 'Sam Brown',
      phone_number: '+14155550123',
      user_identifier: 'customer-1042',
      traits: {plan: 'Pro'}
    },
    messages_attributes: [{body: JSON.stringify('Hi, I need help with a refund.')}],
    title: 'Refund for order #1042',
    status: 'open',
    priority: 'high',
    assignee_email: 'oliver@example.com',
    group_name: 'Billing',
    tags: ['refund', 'priority-customer'],
    ticket_fields: {'Order number': '1042'},
    origin_page_url: 'https://example.com/pricing',
    origin_page_title: 'Pricing'
  })
};

fetch('https://{your-subdomain}.neetochat.com/api/external/v2/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{your-subdomain}.neetochat.com/api/external/v2/conversations"

payload = {
    "visitor_attributes": {
        "email": "sam@example.com",
        "name": "Sam Brown",
        "phone_number": "+14155550123",
        "user_identifier": "customer-1042",
        "traits": { "plan": "Pro" }
    },
    "messages_attributes": [{ "body": "Hi, I need help with a refund." }],
    "title": "Refund for order #1042",
    "status": "open",
    "priority": "high",
    "assignee_email": "oliver@example.com",
    "group_name": "Billing",
    "tags": ["refund", "priority-customer"],
    "ticket_fields": { "Order number": "1042" },
    "origin_page_url": "https://example.com/pricing",
    "origin_page_title": "Pricing"
}
headers = {
    "X-Api-Key": "<x-api-key>",
    "Accept": "<accept>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "conversation": {
    "id": "de414e85-a1b5-4240-a465-7b32606980ce",
    "status": "open",
    "title": "Refund for order #1042",
    "priority": "low",
    "channel_name": "b945fd3cd2573017052901d6dbd0832f",
    "origin_page_url": "https://example.com/pricing",
    "origin_page_title": "Pricing",
    "created_at": "2026-09-23T18:07:53.661Z",
    "updated_at": "2026-10-05T16:26:58.143Z",
    "agent": {
      "id": "05665eee-4602-4317-8f7f-767b04274e5f",
      "name": "Oliver Smith",
      "email": "oliver@example.com"
    },
    "group": {
      "id": null,
      "name": null
    },
    "visitor": {
      "id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
      "name": "Sam Brown",
      "email": "sam@example.com",
      "phone_number": null,
      "user_identifier": null
    }
  }
}

{
  "error": "A conversation must include at least one message."
}

Replace {your-subdomain} with your workspace’s subdomain.
Learn how to find your subdomain in Workspace subdomain.

Headers

X-Api-Key

string

default:your-api-key

required

Use the X-Api-Key header to provide your workspace API key. Refer to Authentication for more information.

enum<string>

default:application/json

required

Specifies the expected response format. Must be set to application/json for proper API communication.

Available options:

application/json

Body

application/json

visitor_attributes

object

required

Details of the contact starting the conversation.

Hide child attributes

visitor_attributes.email

string<email>

required

Example:

"sam@example.com"

visitor_attributes.name

string

Example:

"Sam Brown"

visitor_attributes.phone_number

string

Example:

"+14155550123"

visitor_attributes.user_identifier

string

Your own identifier for the contact.

Example:

"customer-1042"

visitor_attributes.traits

object

Custom attributes to store on the contact.

Example:

{ "plan": "Pro" }

messages_attributes

object[]

required

Messages from the contact that start the conversation. At least one message with a body is required.

Hide child attributes

messages_attributes.body

string

required

Example:

"Hi, I need help with a refund."

title

string

Example:

"Refund for order #1042"

status

string

Status of the conversation. It must be one of the statuses of your workspace.

Example:

"open"

priority

enum<string>

Available options:

low,

medium,

high,

urgent

Example:

"high"

assignee_email

string<email>

Email of the team member to assign the conversation to. It is ignored when no team member has this email.

Example:

"oliver@example.com"

group_name

string

Name of the group to assign the conversation to. It is ignored when no group has this name.

Example:

"Billing"

Response

Created - Conversation created successfully

conversation

object

Hide child attributes

conversation.id

string<uuid>

Example:

"de414e85-a1b5-4240-a465-7b32606980ce"

conversation.status

string

Name of the conversation's status. The default statuses are new, open, waiting_on_customer, on_hold, closed, spam and trash, and your workspace may also have custom statuses.

Example:

"open"

conversation.title

string | null

Example:

"Refund for order #1042"

conversation.priority

enum<string>

Available options:

low,

medium,

high,

urgent

Example:

"low"

conversation.channel_name

string

Unique identifier of the conversation's chat channel.

Example:

"b945fd3cd2573017052901d6dbd0832f"

conversation.origin_page_url

string | null

URL of the page the conversation was started from.

Example:

"https://example.com/pricing"

conversation.origin_page_title

string | null

Title of the page the conversation was started from.

Example:

"Pricing"

conversation.created_at

string<date-time>

Example:

"2026-09-23T18:07:53.661Z"

conversation.updated_at

string<date-time>

Time the conversation was last changed. A new message or note in the conversation also updates it.

Example:

"2026-10-05T16:26:58.143Z"

conversation.agent

object

Team member assigned to the conversation. All fields are null when the conversation is unassigned.

Hide child attributes

conversation.agent.id

string<uuid> | null

Example:

"05665eee-4602-4317-8f7f-767b04274e5f"

conversation.agent.name

string | null

Example:

"Oliver Smith"

conversation.agent.email

string | null

Example:

"oliver@example.com"

conversation.group

object

Group assigned to the conversation. All fields are null when no group is assigned.

Hide child attributes

conversation.group.id

string<uuid> | null

Example:

null

conversation.group.name

string | null

Example:

null

conversation.visitor

object

Contact who started the conversation.

Hide child attributes

conversation.visitor.id

string<uuid>

Example:

"2c79a334-0bc8-44e4-9504-331f59d400ab"

conversation.visitor.name

string | null

Example:

"Sam Brown"

conversation.visitor.email

string | null

Example:

"sam@example.com"

conversation.visitor.phone_number

string | null

Example:

null

conversation.visitor.user_identifier

string | null

Example:

null

Getting Started

Conversations

Messages

Team Members

Create conversation

Headers

Body

Response