> ## Documentation Index > Fetch the complete documentation index at: https://docs.onosso.app/llms.txt > Use this file to discover all available pages before exploring further. # Ask or tell the assistant > Stores the caller's message and answers before any model runs. The reply arrives on `/v1/events`: `conversation.status` with `{ turnId, status }` (`pending`, then `answered`), then `conversation.message` with `{ messageId }`. `clientMessageId` makes a retry return the first send's result. A recording is sent as the `uploadId` of `POST /v1/uploads` instead of `text`, after its PUT: the answer transcribes it, and the message shows in the conversation with its transcript once answered. A correction typed in a week item's or a person's detail carries `context` (`occurrenceId`, the item's id, or `personId`): the answer changes that item's activity, every week, and its `capture` can be undone. A document (a PDF, or a photo of one) is sent with `kind: "document"`, the `uploadId` of a `POST /v1/uploads` of kind `document` after its PUT, its `filename` and an optional `caption`: its first bytes must be the type it was uploaded as, and the answer reads it as a document sent on WhatsApp is read. ## OpenAPI ````yaml /openapi.json post /v1/conversation/messages openapi: 3.0.0 info: title: onosso version: 0.0.0 description: >- The household's API: the week, the people and the sessions the web app reads and changes. servers: [] security: [] tags: - name: Week description: The household's week, day by day. - name: People description: The people who make up the household. - name: Pets description: The pets of the house. - name: Invites description: Links that let someone join. - name: Sessions description: Where you are signed in. - name: Tokens description: Your personal API tokens. - name: Address description: Where the household lives. - name: Messages description: What each person receives from the product, and when. - name: Questions description: 'What needs a person: one queue, the same in the app and on WhatsApp.' - name: Shopping description: 'The household''s one list: places, items and marks.' - name: Conversation description: >- Each person's one conversation with the assistant, the same in the app and on WhatsApp. - name: MCP description: The house for an MCP client such as Claude Desktop, with a personal token. paths: /v1/conversation/messages: post: tags: - Conversation summary: Ask or tell the assistant description: >- Stores the caller's message and answers before any model runs. The reply arrives on `/v1/events`: `conversation.status` with `{ turnId, status }` (`pending`, then `answered`), then `conversation.message` with `{ messageId }`. `clientMessageId` makes a retry return the first send's result. A recording is sent as the `uploadId` of `POST /v1/uploads` instead of `text`, after its PUT: the answer transcribes it, and the message shows in the conversation with its transcript once answered. A correction typed in a week item's or a person's detail carries `context` (`occurrenceId`, the item's id, or `personId`): the answer changes that item's activity, every week, and its `capture` can be undone. A document (a PDF, or a photo of one) is sent with `kind: "document"`, the `uploadId` of a `POST /v1/uploads` of kind `document` after its PUT, its `filename` and an optional `caption`: its first bytes must be the type it was uploaded as, and the answer reads it as a document sent on WhatsApp is read. requestBody: required: true content: application/json: schema: anyOf: - type: object properties: clientMessageId: type: string format: uuid at: type: string format: date-time text: type: string minLength: 1 maxLength: 65536 context: anyOf: - type: object properties: occurrenceId: type: string maxLength: 64 pattern: >- ^atv_[0-7][0123456789abcdefghjkmnpqrstvwxyz0123456789ABCDEFGHJKMNPQRSTVWXYZ]{25}@\d{4}-\d{2}-\d{2}$ required: - occurrenceId additionalProperties: false - type: object properties: personId: type: string maxLength: 64 pattern: >- ^per_[0-7][0123456789abcdefghjkmnpqrstvwxyz0123456789ABCDEFGHJKMNPQRSTVWXYZ]{25}$ required: - personId additionalProperties: false required: - clientMessageId - at - text - type: object properties: kind: type: string enum: - document clientMessageId: type: string format: uuid at: type: string format: date-time uploadId: type: string format: uuid filename: type: string minLength: 1 maxLength: 255 caption: type: string minLength: 1 maxLength: 1024 required: - kind - clientMessageId - at - uploadId - filename - type: object properties: clientMessageId: type: string format: uuid at: type: string format: date-time uploadId: type: string format: uuid required: - clientMessageId - at - uploadId additionalProperties: false responses: '202': description: >- The message, stored, and the turn that will answer it; for a recording, the turn alone. content: application/json: schema: anyOf: - type: object properties: message: $ref: '#/components/schemas/ConversationMessage' turnId: type: string required: - message - turnId - type: object properties: turnId: type: string required: - turnId '400': description: >- The request's shape is invalid (`agent.invalid-message`, with `details.field` and `details.fieldCode`). content: application/json: schema: $ref: '#/components/schemas/DomainError' '401': description: The session is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Unauthorized' '403': description: >- The request came from another origin, or `media.upload-forbidden`: the `uploadId` is not one the caller's household created, or `agent.house-paused`: the house is not paid, so no recording is transcribed and no photo is read. content: application/json: schema: anyOf: - $ref: '#/components/schemas/Forbidden' - $ref: '#/components/schemas/DomainError' '404': description: >- `agent.context-not-found`: the `context` names an item of no activity of the caller's household, or a person not of it; nothing was stored. content: application/json: schema: $ref: '#/components/schemas/DomainError' '409': description: >- `agent.client-message-reused`: the `clientMessageId` was used for another message. content: application/json: schema: $ref: '#/components/schemas/DomainError' '422': description: >- `media.not-a-document`: the upload's first bytes are not the PDF, JPEG or PNG it was uploaded as, or it is a recording; nothing was stored. content: application/json: schema: $ref: '#/components/schemas/DomainError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/RequestTimeout' security: - session: [] components: schemas: ConversationMessage: type: object properties: id: type: string channel: type: string enum: - whatsapp - web - slack role: type: string enum: - user - assistant - team text: type: string at: type: string format: date-time links: type: array items: type: object properties: label: type: string href: type: string required: - label - href capture: $ref: '#/components/schemas/ConversationCapture' actions: type: array items: type: object properties: questionId: type: string optionId: type: string label: type: string required: - questionId - optionId - label description: >- Chips: the options of the caller's pending questions whose date the reply's week read covered; each answers through POST /v1/questions/{questionId}/answers. Absent when there are none. document: type: object properties: filename: type: string required: - filename description: >- The document the caller sent from the app, by its name; the file itself is never in the conversation. Absent for every other message. required: - id - channel - role - text - at - links DomainError: type: object properties: code: type: string details: type: object additionalProperties: nullable: true required: - code - details Unauthorized: type: object properties: message: type: string enum: - Unauthorized statusCode: type: number enum: - 401 required: - message - statusCode Forbidden: type: object properties: message: type: string enum: - Forbidden statusCode: type: number enum: - 403 required: - message - statusCode ConversationCapture: type: object properties: id: type: string format: uuid occurrenceIds: type: array items: type: string description: >- The week items the capture put in the week, `@`, by date. required: - id - occurrenceIds description: >- What the reply wrote to the week, undone as one unit by DELETE /v1/conversation/captures/{captureId}. Absent when the reply wrote nothing. Degraded: type: object properties: code: type: string enum: - request.timeout - service.unavailable correlationId: type: string required: - code - correlationId responses: ServiceUnavailable: description: A dependency is unavailable; retry after Retry-After seconds. content: application/json: schema: $ref: '#/components/schemas/Degraded' RequestTimeout: description: The request outlived its deadline. content: application/json: schema: $ref: '#/components/schemas/Degraded' securitySchemes: session: type: apiKey in: cookie name: __Secure-better-auth.session_token description: The session cookie set when you sign in to the web app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.