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 unassigned, or assigned only to the workspace's active email agent.

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

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

Body

channelstringrequired

Conversation channel type

One of: email, chat.

customer_idstringrequired

ID of the customer

Format: uuid.

subjectstring | null

Maximum length: 500.

statusstring | nullDefault: open

Conversation status

One of: open, closed.

prioritystring | nullDefault: normal

Conversation priority

One of: low, normal, high, urgent.

assignee_idstring | 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.

assignee_typestring | null

Type of assignee. Defaults to 'user' when assignee_id is provided and assignee_type is omitted.

One of: user, agent.

Request

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

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

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

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();

Response

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

400 Bad Request

{
    "error": "Error message",
    "code": "ERROR_CODE",
    "errors": {}
}

401 Unauthorized

{
    "error": "Error message",
    "code": "ERROR_CODE",
    "errors": {}
}

Response fields

idstring

Format: uuid.

channelstring

One of: email, chat.

customer_idstring

Format: uuid.

subjectstring | null

statusstring

One of: open, closed.

prioritystring

One of: low, normal, high, urgent.

assignee_idstring | 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.

assignee_typestring | null

Type of assignee: 'user' for users or 'agent' for AI agents.

One of: user, agent.

closed_atstring | null

Format: date-time.

first_response_atstring | null

Format: date-time.

last_message_atstring | null

Format: date-time.

is_spamboolean

spam_scorenumber | null

created_atstring | null

Format: date-time.

updated_atstring | null

Format: date-time.