> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create conversation

> Create a new conversation. Assignment Rules: assignees must belong to the same workspace as the API key. Chat conversations can be assigned to users (or left unassigned). Agent assignment is limited to the conversation's original chat agent. Email conversations can be assigned to users, left…

Create a new conversation. Assignment Rules: assignees must belong to the same workspace as the API key. Chat conversations can be assigned to users (or left unassigned). Agent assignment is limited to the conversation's original chat agent. Email conversations can be assigned to users, left unassigned, or assigned only to the workspace's active email agent.

```http
POST https://api.weav.com/v1/conversations
```

Requires a token with the `external-api:write` ability.

## Body

<ParamField body="channel" type="string" required>
Conversation channel type

One of: `email`, `chat`.
</ParamField>

<ParamField body="customer_id" type="string" required>
ID of the customer

Format: `uuid`.
</ParamField>

<ParamField body="subject" type="string | null">
Maximum length: 500.
</ParamField>

<ParamField body="status" type="string | null" default="open">
Conversation status

One of: `open`, `closed`.
</ParamField>

<ParamField body="priority" type="string | null" default="normal">
Conversation priority

One of: `low`, `normal`, `high`, `urgent`.
</ParamField>

<ParamField body="assignee_id" type="string | null">
ID of user or agent to assign conversation to. Must belong to the same workspace. For chat, agent assignments are limited to the conversation's original chat agent. For email, only the active email agent can be assigned as agent.

Format: `uuid`.
</ParamField>

<ParamField body="assignee_type" type="string | null">
Type of assignee. Defaults to 'user' when assignee_id is provided and assignee_type is omitted.

One of: `user`, `agent`.
</ParamField>

## Request

<CodeGroup>

```bash cURL
curl --request POST \
  --url 'https://api.weav.com/v1/conversations' \
  --header "Authorization: Bearer ${WEAV_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
  "channel": "email",
  "customer_id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
  "status": "open",
  "priority": "normal",
  "assignee_id": "550e8400-e29b-41d4-a716-446655440000"
}'
```

```js JavaScript
const body = {
  "channel": "email",
  "customer_id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
  "status": "open",
  "priority": "normal",
  "assignee_id": "550e8400-e29b-41d4-a716-446655440000"
};
const response = await fetch("https://api.weav.com/v1/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEAV_API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});
console.log(await response.json());
```

```python Python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WEAV_API_TOKEN']}"}
body = {"channel": "email", "customer_id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d", "status": "open", "priority": "normal", "assignee_id": "550e8400-e29b-41d4-a716-446655440000"}
response = requests.post("https://api.weav.com/v1/conversations", headers=headers, json=body)
print(response.json())
```

```php PHP
use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('POST', 'https://api.weav.com/v1/conversations', [
    'headers' => ['Authorization' => 'Bearer '.getenv('WEAV_API_TOKEN')],
    'json' => array (
  'channel' => 'email',
  'customer_id' => '9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d',
  'status' => 'open',
  'priority' => 'normal',
  'assignee_id' => '550e8400-e29b-41d4-a716-446655440000',
),
]);
echo $response->getBody();
```

</CodeGroup>

## Response

<CodeGroup>

```json 201 Created
{
    "id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
    "channel": "email",
    "customer_id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
    "subject": "string",
    "status": "open",
    "priority": "low",
    "assignee_id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
    "assignee_type": "user",
    "closed_at": "2026-01-01T00:00:00Z",
    "first_response_at": "2026-01-01T00:00:00Z",
    "last_message_at": "2026-01-01T00:00:00Z",
    "is_spam": false,
    "spam_score": 0,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
}
```

```json 400 Bad Request
{
    "error": "Error message",
    "code": "ERROR_CODE",
    "errors": {}
}
```

```json 401 Unauthorized
{
    "error": "Error message",
    "code": "ERROR_CODE",
    "errors": {}
}
```

</CodeGroup>

## Response fields

<ParamField body="id" type="string">
Format: `uuid`.
</ParamField>

<ParamField body="channel" type="string">
One of: `email`, `chat`.
</ParamField>

<ParamField body="customer_id" type="string">
Format: `uuid`.
</ParamField>

<ParamField body="subject" type="string | null">

</ParamField>

<ParamField body="status" type="string">
One of: `open`, `closed`.
</ParamField>

<ParamField body="priority" type="string">
One of: `low`, `normal`, `high`, `urgent`.
</ParamField>

<ParamField body="assignee_id" type="string | null">
ID of the assigned user or agent. Assignees must belong to the same workspace. Chat conversations can only use the original chat agent when assigning an agent. Email conversations can only use the active email agent when assigning an agent.

Format: `uuid`.
</ParamField>

<ParamField body="assignee_type" type="string | null">
Type of assignee: 'user' for users or 'agent' for AI agents.

One of: `user`, `agent`.
</ParamField>

<ParamField body="closed_at" type="string | null">
Format: `date-time`.
</ParamField>

<ParamField body="first_response_at" type="string | null">
Format: `date-time`.
</ParamField>

<ParamField body="last_message_at" type="string | null">
Format: `date-time`.
</ParamField>

<ParamField body="is_spam" type="boolean">

</ParamField>

<ParamField body="spam_score" type="number | null">

</ParamField>

<ParamField body="created_at" type="string | null">
Format: `date-time`.
</ParamField>

<ParamField body="updated_at" type="string | null">
Format: `date-time`.
</ParamField>

---

This knowledge base is built and hosted on [Weav](https://weav.com).