Adds a message to an existing conversation. The server derives the final sender from the authenticated caller: visitors send as themselves and operators send as the current operator. The default message type is `text`. Use `type=file` or `type=image` with metadata for uploaded files, and `replyToId` to quote an earlier message. For outbound WhatsApp provider templates, an operator may set `metadata.channelTemplateKey` and optional string values in `metadata.channelTemplateParameters`; the configured locale mapping is resolved when the message is delivered. The endpoint publishes the message to realtime subscribers, updates unread counters, and fires message webhooks. 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. A successful send persists one message and may enqueue notifications, webhook deliveries, AI work, analytics, and realtime publication after commit. 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/conversations/{id}/messagesOrganization 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": "7f1f4d83-0a0e-4f34-9c4b-9a98d6e1c2ab",
"orgId": "8a8f4d83-0a0e-4f34-9c4b-9a98d6e1c2ab",
"conversationId": "9f1f4d83-0a0e-4f34-9c4b-9a98d6e1c2ab",
"senderType": "operator",
"senderId": "6f1f4d83-0a0e-4f34-9c4b-9a98d6e1c2ab",
"content": "Hello, how can I help you today?",
"type": "text",
"metadata": {},
"isRead": false,
"isEdited": false,
"editedAt": null,
"createdAt": "2026-06-23T08:00:00.000Z",
"deletedAt": null,
"replyToId": null,
"mentions": [],
"searchVector": "'hello':1 'help':6 'today':8",
"quotedMessage": null
}{
"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/11111111-1111-4111-8111-111111111111/messages' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer convor_sk_...' \
--header 'Content-Type: application/json' \
--data '{
"content": "Hello, how can I help you today?",
"senderType": "operator",
"type": "text"
}'const response = await fetch("https://api.convor.io/api/conversations/11111111-1111-4111-8111-111111111111/messages", {
method: "POST",
headers: {
"Accept": "application/json",
"Authorization": "Bearer convor_sk_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"content": "Hello, how can I help you today?",
"senderType": "operator",
"type": "text"
}),
});
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?
Schedule a message to send later
Creates a message with a scheduled delivery time. The message is stored immediately but only published to Centrifugo when the scheduled time arrives. 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. The scheduled time must be in the future. The scheduler later publishes the stored message and changes its schedule status from `pending`; creating another request creates another scheduled message. 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.
Attachments
Private file attachments linked to customer conversations