> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oration.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Post ticket message
> Add a message to a ticket's conversation thread.
Add a message to a ticket's thread. This is the same conversation thread agents see in the ticket detail view — public replies and internal notes both live here.
If `authorType` is `user`, the message is automatically attributed to the user who owns the API key — you cannot pass a different `authorUserId`. For `ai_agent`, you must pass the matching `authorAgentId`. For `customer`, pass `authorCustomerId` when you have it, but it is not required yet.
## Path parameters
Ticket UUID. Find it from [Get ticket](/api-reference/endpoint/tickets/get) or [Search tickets](/api-reference/endpoint/tickets/search).
## Request body
The ticket `ticketId` comes from the URL path — do not include it in the body.
Rich HTML body shown in the thread.
Plain-text version of the body, used for search, SMS, and accessibility.
Who this message is from: `user`, `customer`, `system`, or `ai_agent`.
* `user` — attributed to the API key's owning user automatically. Do not pass `authorUserId`.
* `customer` — optionally pair with `authorCustomerId` (see note below).
* `ai_agent` — requires `authorAgentId`.
* `system` — no author reference needed; use for automated/system-generated entries.
Customer UUID. Recommended when `authorType` is `customer`, but not enforced yet — pass it when you have it so the thread shows the right customer.
Voice/AI agent UUID. Required when `authorType` is `ai_agent`.
Set to `true` to add an internal note that is never sent to the customer. `false` posts a customer-visible reply.
Channel this message is associated with, e.g. `manual`, `api`. See [Create ticket](/api-reference/endpoint/tickets/post) for the full list of sources.
Groups internal-note side threads. Omit unless you are replying within a specific side thread.
Provider message ID, used to deduplicate messages ingested from an external channel.
Email threading headers (`messageId`, `inReplyTo`, `references`, `fromAddress`, `toAddresses`, `ccAddresses`, `bccAddresses`, `subject`). Only relevant for email-sourced messages.
Provider-specific extras (e.g. Slack or WhatsApp metadata) that do not have a dedicated field.
ISO 8601 timestamp for a delayed send. Pair with `status: "scheduled"`.
ISO 8601 timestamp the message was delivered. Defaults to the current time if omitted.
One of `draft`, `scheduled`, `sent`, or `failed`.
Posting a public reply (`isPrivate: false`) updates the ticket's `lastAgentActivityAt`, and sets `firstResponseAt` the first time it happens. This endpoint does not trigger any webhook.
The request fails with a validation error if `authorType` is `ai_agent` without `authorAgentId`. `authorType: "customer"` without `authorCustomerId` is currently allowed while customer matching on the tickets platform matures — this will likely become required in the future.
## OpenAPI
````yaml POST /tickets/{ticketId}/messages
openapi: 3.1.0
info:
title: Oration API
description: Rest API for Oration AI
version: 1.0.0
servers:
- url: https://www.oration.ai/api/v2
security: []
tags:
- name: auth
- name: users
- name: posts
- name: tickets
externalDocs:
url: https://docs.oration.ai
paths:
/tickets/{ticketId}/messages:
post:
operationId: edge-workspaces-ticketMessage-create
parameters:
- in: header
name: x-api-key
schema:
type: string
minLength: 1
required: true
- in: header
name: x-workspace-slug
schema:
type: string
required: true
- in: header
name: x-workspace-id
schema:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required: true
- in: path
name: ticketId
schema:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
threadId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
bodyHtml:
type: string
bodyPlain:
type: string
authorType:
type: string
enum:
- user
- customer
- system
- ai_agent
authorCustomerId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
authorAgentId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
isPrivate:
default: false
type: boolean
source:
anyOf:
- type: string
enum:
- email
- chat_widget
- voice
- whatsapp
- sms
- customer_portal
- form
- manual
- api
- slack
- microsoft_teams
- instagram
- discord
- telegram
- type: 'null'
externalMessageId:
anyOf:
- type: string
- type: 'null'
emailInfo:
anyOf:
- anyOf:
- anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: array
items: {}
- type: 'null'
channelMetadata:
anyOf:
- anyOf:
- anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: array
items: {}
- type: 'null'
scheduledAt:
anyOf:
- type: string
- type: 'null'
sentAt:
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- draft
- scheduled
- sent
- failed
required:
- bodyHtml
- bodyPlain
- authorType
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
ticketId:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
threadId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
bodyHtml:
type: string
bodyPlain:
type: string
authorType:
type: string
enum:
- user
- customer
- system
- ai_agent
authorUserId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
authorCustomerId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
authorAgentId:
anyOf:
- type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
isPrivate:
type: boolean
source:
anyOf:
- type: string
enum:
- email
- chat_widget
- voice
- whatsapp
- sms
- customer_portal
- form
- manual
- api
- slack
- microsoft_teams
- instagram
- discord
- telegram
- type: 'null'
externalMessageId:
anyOf:
- type: string
- type: 'null'
emailInfo:
anyOf:
- anyOf:
- anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: array
items: {}
- type: 'null'
channelMetadata:
anyOf:
- anyOf:
- anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: array
items: {}
- type: 'null'
scheduledAt:
anyOf:
- type: string
- type: 'null'
sentAt:
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- draft
- scheduled
- sent
- failed
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
createdAt:
type: string
updatedAt:
type: string
required:
- ticketId
- threadId
- bodyHtml
- bodyPlain
- authorType
- authorUserId
- authorCustomerId
- authorAgentId
- isPrivate
- source
- externalMessageId
- emailInfo
- channelMetadata
- scheduledAt
- sentAt
- status
- id
- createdAt
- updatedAt
additionalProperties: false
'400':
description: Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/error.BAD_REQUEST'
'401':
description: Authorization not provided
content:
application/json:
schema:
$ref: '#/components/schemas/error.UNAUTHORIZED'
'403':
description: Insufficient access
content:
application/json:
schema:
$ref: '#/components/schemas/error.FORBIDDEN'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
security:
- Authorization: []
components:
schemas:
error.BAD_REQUEST:
type: object
properties:
message:
type: string
description: The error message
example: Invalid input data
code:
type: string
description: The error code
example: BAD_REQUEST
issues:
description: An array of issues that were responsible for the error
example: []
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
title: Invalid input data error (400)
description: The error information
example:
code: BAD_REQUEST
message: Invalid input data
issues: []
error.UNAUTHORIZED:
type: object
properties:
message:
type: string
description: The error message
example: Authorization not provided
code:
type: string
description: The error code
example: UNAUTHORIZED
issues:
description: An array of issues that were responsible for the error
example: []
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
title: Authorization not provided error (401)
description: The error information
example:
code: UNAUTHORIZED
message: Authorization not provided
issues: []
error.FORBIDDEN:
type: object
properties:
message:
type: string
description: The error message
example: Insufficient access
code:
type: string
description: The error code
example: FORBIDDEN
issues:
description: An array of issues that were responsible for the error
example: []
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
title: Insufficient access error (403)
description: The error information
example:
code: FORBIDDEN
message: Insufficient access
issues: []
error.INTERNAL_SERVER_ERROR:
type: object
properties:
message:
type: string
description: The error message
example: Internal server error
code:
type: string
description: The error code
example: INTERNAL_SERVER_ERROR
issues:
description: An array of issues that were responsible for the error
example: []
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
title: Internal server error error (500)
description: The error information
example:
code: INTERNAL_SERVER_ERROR
message: Internal server error
issues: []
securitySchemes:
Authorization:
type: http
scheme: bearer
````