# Conversations

Browse the available operations for this resource.

Base URL: https://api.levr.ai/v1

Authentication: Bearer — Portal API key

[REST guide](https://docs.levr.ai/rest-api.md) · [OpenAPI specification](https://docs.levr.ai/generated/openapi.json)

OpenAPI defines exact REST schemas. Each record’s Application Contract defines its current questions and accepted answers.

## Connect your system to a group

Use chat to follow a business or Deal conversation from your CRM, or post an update from your underwriting system. Your API key is the sender: messages show its label, not the user who created the key. Rotating its token preserves that identity.

Give the key `conversations:read` to monitor groups, or `conversations:write` to send messages and upload files. The API exposes public groups within the key’s provider and source scope. Private groups and direct messages remain unavailable, even if the integration previously posted there. MCP and Levr AI instead act as the signed-in user and retain their origin attribution.

For a connected AI assistant, follow [Chat and messages with MCP](https://docs.levr.ai/mcp/resources/chat.md). MCP uses user OAuth and does not require this API key.

## Find the group

The following responses illustrate one workflow. IDs and timestamps are examples; copy values from your own responses.
The `example.invalid` link is illustrative; open the actual returned `frontend_link`.

List groups, optionally filtering by a Business or Deal ID copied from those APIs:

```http
GET /v1/conversations/?business_id=biz_6q3n8v2k9m4x7p5r
Authorization: Bearer YOUR_API_KEY
```

Example `200 OK` response:

```
{
  "object": "list",
  "items": [
    {
      "id": "chat_7k2m9q4v6x8n3p5r",
      "object": "conversation",
      "name": "Application updates",
      "kind": "group",
      "visibility": "public",
      "frontend_link": "https://example.invalid/chat/chat_7k2m9q4v6x8n3p5r",
      "created_at": "2026-01-15T09:00:00Z",
      "updated_at": "2026-01-15T09:30:00Z",
      "business_id": "biz_6q3n8v2k9m4x7p5r",
      "deal_id": null
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}
```

The `id` field is the conversation’s **slug**: a system-generated, opaque identifier such as
`chat_7k2m9q4v6x8n3p5r`. The API calls this value `id` in responses and `conversation_id` in URL parameters.
Copy it exactly; do not derive it from the group name or use a database ID.

Copy `items[0].id` as `conversation_id`. `business_id` and `deal_id` identify linked records when available;
`null` means no linked record is exposed. Here, `next_cursor: null` means there are no more groups in this result.

Use `deal_id` for a Deal, or `search` for a group name. Collections accept `page_size` from 1 to 100 and opaque `cursor` values. Group ordering accepts `created_at`, `-created_at`, `updated_at`, or `-updated_at` and defaults to `-updated_at`. Combine up to three ordering fields with commas. Keep the filters and ordering unchanged when following a cursor. Follow `next_cursor` until you find the intended group. Save its `chat_` ID; names can change. A business or Deal may have several groups, so confirm the group before posting. An empty list means no public group is available to this key; it does not create one.

Use `GET /v1/conversations/chat_7k2m9q4v6x8n3p5r/participants/` to inspect the audience. Copy participant IDs into `mentioned_participant_slugs` when mentioning someone; typing their name alone is not a mention.

Example participants response (`200 OK`):

```
{
  "object": "list",
  "items": [
    {
      "id": "chp_3m8q5v2n9k4x7p6r",
      "name": "Alex Rivera",
      "email": "alex@example.invalid",
      "participation_mode": "account",
      "created_at": "2026-01-15T09:00:00Z"
    },
    {
      "id": "chp_8v2k6q9m3n7x4p5r",
      "name": "Jordan Lee",
      "email": "jordan@example.invalid",
      "participation_mode": "email",
      "created_at": "2026-01-15T09:05:00Z"
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}
```

`account` identifies a Levr account; `email` identifies an email-only participant.
Mention Alex using `"mentioned_participant_slugs": ["chp_3m8q5v2n9k4x7p6r"]`.

Read its messages:

```http
GET /v1/conversations/chat_7k2m9q4v6x8n3p5r/messages/?page_size=20
Authorization: Bearer YOUR_API_KEY
```

Example messages response (`200 OK`):

```
{
  "object": "list",
  "items": [
    {
      "id": "msg_2v8q5n7k4m9x6p3r",
      "object": "chat_message",
      "conversation_id": "chat_7k2m9q4v6x8n3p5r",
      "text": "Please upload the latest bank statement.",
      "version": 1,
      "created_at": "2026-01-15T09:30:00Z",
      "edited_at": null,
      "deleted_at": null,
      "reply_to_id": null,
      "author": {
        "id": "chp_3m8q5v2n9k4x7p6r",
        "name": "Alex Rivera",
        "participation_mode": "account"
      },
      "origin": null,
      "attachments": []
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}
```

`author` identifies the sender. `reply_to_id: null` means this is not a reply; `attachments: []` means no files.
`edited_at` and `deleted_at` remain `null` until those actions occur.

Message ordering accepts `created_at` or `-created_at` and defaults to newest first (`-created_at`). Use `search` to match current message text. Participant ordering accepts those same two creation-time values and defaults to oldest first. Private groups, direct conversations, and out-of-scope IDs return `404` on detail, message, participant, attachment, edit, and delete endpoints, even if your integration was previously a participant. Follow `next_cursor` for older messages. Reading through the API does not mark messages read for a person. Deleted messages retain their ID and version but return empty content.

## Send an update

The target group is selected by the conversation slug **in the URL**, not in the JSON body:

```http
POST /v1/conversations/{conversation_id}/messages/
```

Replace `{conversation_id}` with the `id` returned by group discovery. Using the example response above:

```http
POST /v1/conversations/chat_7k2m9q4v6x8n3p5r/messages/
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: crm-case-148-update-3
Content-Type: application/json

{
  "text": "We have reviewed the statements. Please upload the latest bank statement."
}
```

Example `201 Created` response:

```
{
  "id": "msg_9p4r7k2v8m5q3n6x",
  "object": "chat_message",
  "conversation_id": "chat_7k2m9q4v6x8n3p5r",
  "text": "We have reviewed the statements. Please upload the latest bank statement.",
  "version": 1,
  "created_at": "2026-01-15T10:00:00Z",
  "edited_at": null,
  "deleted_at": null,
  "reply_to_id": null,
  "author": {
    "id": "chp_5n9x3q7v2k8m4p6r",
    "name": "Acme CRM",
    "participation_mode": "integration"
  },
  "origin": {
    "source": "external_api"
  },
  "attachments": []
}
```

The integration is the author (`chp_5n9x3q7v2k8m4p6r`), and `origin.source` records that the message came through the External API.
Save the returned message ID and version. Reuse the same key and body after a timeout to recover the original response. Changing the body with the same key returns `409`; use a new key for a new message. To reply to a specific message, include its ID as `reply_to_slug`.

Messages to email participants consume the sending provider’s guest-email allowance. A limit error rejects the send; it does not silently omit those recipients. Account notification emails are separate from this allowance.

## Include a file

POST one multipart field named `file` to `/v1/conversations/chat_7k2m9q4v6x8n3p5r/attachments/`, with an `Idempotency-Key`. Each file can be up to 25 MiB. Example `201 Created` upload response:

```
{
  "id": "chatfile_4q7n2v9k5m8x3p6r",
  "name": "bank-statement.pdf",
  "size": 48271,
  "content_type": "application/pdf"
}
```

`size` is in bytes. Copy the returned `id` into `attachment_slugs` when sending:

```json
{
  "text": "The assessment is attached.",
  "attachment_slugs": ["chatfile_4q7n2v9k5m8x3p6r"]
}
```

Use the actual returned ID. Uploading alone does not share a file: a draft is visible only to the uploading API identity. Sending binds it to one message. Conversations with email participants allow at most 18 MiB of combined attachments per message.

After sending, the message response includes that same file object in its `attachments` array.

Download an authorized original from `GET /v1/chat-attachments/{attachment_id}/download/`. Files attached to deleted messages are unavailable.

## Follow changes with webhooks

Subscribe your webhook destination to `chat.message_sent`, `chat.message_edited`, and `chat.message_deleted`. Each event contains `conversation_id`, `message_id`, and `version`. Fetch the current message from `GET /v1/chat-messages/{message_id}/` when you need its content.

Example `data` object within a `chat.message_sent` webhook (not the full delivery envelope):

```
{
  "conversation_id": "chat_7k2m9q4v6x8n3p5r",
  "message_id": "msg_9p4r7k2v8m5q3n6x",
  "version": 1
}
```

Use `message_id` to fetch the message; the webhook data contains identifiers and a version, rather than the message text.

Deduplicate webhook deliveries by their event ID. Events can arrive after later edits, so the fetched message may have a higher version. Access is checked again before delivery; making a group private stops further API access and delivery of queued events for it. Webhooks never grant access to a group.

Your own API messages also produce events. Compare the message’s author ID with the integration author ID returned by your sends before generating an automated response, to avoid a reply loop.

## Correct your integration’s message

Read `/v1/chat-messages/{message_id}/` and copy its `ETag`. PATCH that URL with a new `text`, `If-Match`, and `Idempotency-Key`. DELETE uses the same headers and no body. Only the API identity that sent the message may change it.

For example, reading `msg_9p4r7k2v8m5q3n6x` returns the message above with `ETag: "1"`. To correct it:

```http
PATCH /v1/chat-messages/msg_9p4r7k2v8m5q3n6x/
Authorization: Bearer YOUR_API_KEY
If-Match: "1"
Idempotency-Key: crm-case-148-correction-1
Content-Type: application/json

{
  "text": "We have reviewed the statements. No further documents are needed."
}
```

The `200 OK` response is the same message shape. These fields change (excerpt):

```
{
  "id": "msg_9p4r7k2v8m5q3n6x",
  "text": "We have reviewed the statements. No further documents are needed.",
  "version": 2,
  "edited_at": "2026-01-15T10:15:00Z"
}
```

The new response ETag is `"2"`. A subsequent deletion returns the message with a higher `version`,
`text: ""`, `attachments: []`, and a populated `deleted_at`.

A `412` means another change won: read the message again before deciding what to do. Edits and deletions update the chat transcript; they cannot retract emails already sent.


## Follow application reviews separately

A request to update documents or answers belongs to the application. Sending that review emails the selected collaborators; it does not send a chat message. Starting a discussion afterward is a separate action.

Subscribe to `deal_application.review_sent` or `client_intake_application.review_sent` to follow these requests. Each event identifies the application and includes `returned_document_count` and `review_note_count`. `updated_at` records when the review was sent. A review may contain documents, notes, or both. Draft notes and queued returns do not trigger an event.

Use `conversations` permissions for chat. Reading the linked application requires `deal_applications:read` or `client_intake_applications:read`; chat access does not grant application access. Webhook destinations have their own event subscriptions and provider or Lead source scope, independent of API keys.

These events report a sent review, not confirmed email delivery. They leave the application's status unchanged. Continue using application `updated` events for answer edits and `status_changed` events for decisions.


- [Find public chat groups](https://docs.levr.ai/rest-api-reference/conversations/list-conversations.md): `GET /conversations/`

- [Send a group message as your integration](https://docs.levr.ai/rest-api-reference/conversations/send-chat-message.md): `POST /conversations/{conversation_id}/messages/`

- [Upload a draft attachment](https://docs.levr.ai/rest-api-reference/conversations/upload-chat-attachment.md): `POST /conversations/{conversation_id}/attachments/`

- [Read a public group](https://docs.levr.ai/rest-api-reference/conversations/retrieve-conversation.md): `GET /conversations/{conversation_id}/`

- [Read group messages](https://docs.levr.ai/rest-api-reference/conversations/list-chat-messages.md): `GET /conversations/{conversation_id}/messages/`

- [Read the group audience](https://docs.levr.ai/rest-api-reference/conversations/list-chat-participants.md): `GET /conversations/{conversation_id}/participants/`
