Starts a new conversation for an existing visitor in the current organization.
/api/conversationsStarts a new conversation for an existing visitor in the current organization. Widget callers should use the visitor identity returned during widget bootstrap and first create the visitor record with POST /api/tracking/visitors/track. 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.
Bearer API key or X-API-Key header.conversations:writeautomation_api)application/json
Conversation fields supplied in the request.
TypeScript Definitions
Use the request body type in TypeScript.
Conversation fields supplied in the request.
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",
"priority": "normal",
"source": "widget",
"aiEnabled": true,
"locale": "en",
"localeSource": "organization_default",
"localeLocked": false,
"localeUpdatedAt": null,
"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?
Visitor for whom the conversation is created.
Inbound channel recorded for the new conversation.