Starts a new conversation for an existing visitor in the current organization. Widget callers should use the visitor identity returned during widget bootstrap and create the visitor record with `POST /api/tracking/visitors/track` before calling this endpoint. Operators can also create a conversation for an existing visitor. The optional `channel` field identifies where the conversation started, such as web, email, or api. New conversations start with AI enabled and then run assignment and routing rules. Authenticate with an organization API key sent in `X-API-Key` or as a Bearer token and carrying the exact `conversations:write` scope. API-key access also requires the Automation & API module (`automation_api`). Authorized dashboard sessions remain supported where the route already permits them. The request is isolated to the authenticated organization. Resource and site/project identifiers must belong to that organization; out-of-scope identifiers are not disclosed. Creation runs assignment and routing rules and may emit audit, webhook, notification, and realtime side effects after the database commit. Visitor bearer callers can create only for their own authenticated visitor identity; organization API keys can create for an existing visitor in the same organization. Retry behavior: This operation is not idempotent. After an ambiguous timeout, read the resource state before retrying to avoid duplicate work, messages, files, bookings, exports, or events.
/api/conversationsOrganization API key supplied as Authorization: Bearer convor_sk_....
In: header
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
{
"id": "9f1f4d83-0a0e-4f34-9c4b-9a98d6e1c2ab",
"organizationId": "8a8f4d83-0a0e-4f34-9c4b-9a98d6e1c2ab",
"visitorId": "550e8400-e29b-41d4-a716-446655440000",
"operatorId": null,
"status": "open",
"source": "widget",
"aiEnabled": true,
"title": null,
"messageCount": 0,
"hasUnreadMessages": false,
"tags": [],
"customFields": {},
"createdAt": "2026-06-23T08:00:00.000Z",
"updatedAt": "2026-06-23T08:00:00.000Z"
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}curl --request POST \
'https://api.convor.io/api/conversations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer convor_sk_...' \
--header 'Content-Type: application/json' \
--data '{
"visitorId": "550e8400-e29b-41d4-a716-446655440000",
"channel": "web"
}'const response = await fetch("https://api.convor.io/api/conversations", {
method: "POST",
headers: {
"Accept": "application/json",
"Authorization": "Bearer convor_sk_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"visitorId": "550e8400-e29b-41d4-a716-446655440000",
"channel": "web"
}),
});
const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
? null
: contentType.includes("json")
? await response.json()
: contentType.startsWith("text/")
? await response.text()
: await response.blob();
if (!response.ok) {
const message = typeof data === "object" && data !== null
&& "error" in data && typeof data.error === "object"
&& data.error !== null && "message" in data.error
? String(data.error.message)
: "Convor API request failed (" + response.status + ")";
throw new Error(message);
}
console.log(data);Was this page helpful?
Close a conversation
Closes one conversation in the current organization. The request body is optional, so a bare `POST` works. When a reason is provided, it is stored in conversation metadata as `closeReason`. On success the endpoint returns the updated conversation, writes an audit log entry, fires the resolved webhook, and triggers follow-up background tasks. Authenticate with an organization API key sent in `X-API-Key` or as a Bearer token and carrying the exact `conversations:write` scope. API-key access also requires the Automation & API module (`automation_api`). Authorized dashboard sessions remain supported where the route already permits them. The request is isolated to the authenticated organization. Resource and site/project identifiers must belong to that organization; out-of-scope identifiers are not disclosed. Retry behavior: Repeating the same request converges on the same resource state, but a retry may return a conflict or not-found response after the first request succeeds.
Delete a conversation
Soft-deletes one conversation in the current organization. Admin access is required. The conversation status is changed to `deleted` and all messages in that conversation are marked with `deletedAt` so they no longer appear in normal views. The record is not physically removed from the database. Access requires an active organization administrator session or an organization API key with the `conversations:write` scope. API-key calls also require the automation API module. Data is isolated to the authenticated organization; identifiers from another organization or site are not disclosed.