> ## Documentation Index
> Fetch the complete documentation index at: https://suporte.deumboom.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversas API V1

> CRUD do sensor Conversas no Core: registros, participantes e comentários em /core/v1/conversation*.

A **Conversas API V1** é o contrato HTTP usado pela plataforma Core para **criar, listar, editar e excluir** registros de conversas de gestão. Replica o módulo [Conversas](/core/sensores/conversas).

É a API da interface: payloads do cadastro, filtro paginado, participantes em recurso separado e comentários com anexo.

<Info>
  Autenticação: JWT de usuário (`Authorization: Bearer eyJ…`) com `conversation:read` / `conversation:manage`. O token `bvt_` **não** acessa estas rotas. Para integrações e o conector MCP, use a [Conversas API V2](/api/conversas-v2).
</Info>

```http theme={null}
https://api.deumboom.com/core/v1/conversation
```

***

## Recursos

### Conversa

Base: `/core/v1/conversation`

| Método | Path | Permissão | Status |
| - | - | - | - |
| `POST` | `/core/v1/conversation` | `conversation:manage` | 201 |
| `GET` | `/core/v1/conversation/read-all` | `conversation:read` | 200 |
| `GET` | `/core/v1/conversation/read-all/company/{company-id}` | `conversation:read` | 200 |
| `GET` | `/core/v1/conversation/{conversation-id}` | `conversation:read` | 200 |
| `POST` | `/core/v1/conversation/read-filter` | `conversation:read` | 200 |
| `PUT` | `/core/v1/conversation` | `conversation:manage` | 200 |
| `DELETE` | `/core/v1/conversation/{conversation-id}` | `conversation:manage` | 204 |

`DELETE` é soft delete (`deletedAt`). A listagem ignora registros excluídos.

### Participantes

Base: `/core/v1/conversation-participant`

| Método | Path | Permissão | Status |
| - | - | - | - |
| `POST` | `/core/v1/conversation-participant` | `conversation_participant:manage` | 201 |
| `POST` | `/core/v1/conversation-participant/bulk` | `conversation_participant:manage` | 201 |
| `GET` | `/core/v1/conversation-participant/{conversation-participant-id}` | `conversation_participant:read` | 200 |
| `DELETE` | `/core/v1/conversation-participant/{conversation-participant-id}` | `conversation_participant:manage` | 204 |

Na V1 a conversa **não grava participantes no `POST` do registro**. Crie a conversa e em seguida vincule as pessoas.

### Comentários

Base: `/core/v1/conversation-comment`

Create e update usam `multipart/form-data` (JSON no part `data` + arquivos opcionais).

| Método | Path | Permissão | Status |
| - | - | - | - |
| `POST` | `/core/v1/conversation-comment` | `conversation:manage` | 201 |
| `GET` | `/core/v1/conversation-comment/read-all/conversation/{conversation-id}` | `conversation:read` | 200 |
| `GET` | `/core/v1/conversation-comment/{conversation-comment-id}` | `conversation:read` | 200 |
| `PUT` | `/core/v1/conversation-comment` | `conversation:manage` | 200 |
| `DELETE` | `/core/v1/conversation-comment/{conversation-comment-id}` | `conversation:manage` | 204 |

***

## Tipos e status

### `type`

| Valor | Na interface |
| - | - |
| `ONE_ON_ONE` | 1:1 |
| `CHECK_IN` | Check-in |
| `FEEDBACK` | Feedback |
| `REVERSAL_PLAN` | Plano de reversão |
| `CULTURE_REVIEW` | Review de cultura |

### `status`

Único valor aceito hoje: `NO_ACTION`. Obrigatório no create e no update.

***

## Campos da conversa

| Campo | Tipo | Obrigatório | Notas |
| - | - | - | - |
| `conversationId` | uuid | no PUT | Gerado na criação |
| `companyId` | uuid | sim | Empresa |
| `type` | enum | sim | ver tabela acima |
| `title` | string | sim | Máximo 255 caracteres |
| `status` | enum | sim | `NO_ACTION` |
| `description` | string | sim | Pode ser string vazia; `null` é recusado |
| `conversationDate` | datetime | sim | ISO-8601 (`2026-09-18T14:00:00`) |
| `reviewDate` | datetime | não | Se enviada, **não** pode ser anterior a `conversationDate` |
| `createdById` / `createdByName` | uuid / string | leitura | Preenchidos pelo token na criação |
| `conversationParticipants` | array | leitura | Presente no GET; não substitui o recurso de participantes |
| `createdAt` | datetime | leitura | |

***

## Criar uma conversa

O `POST` exige identificar o usuário criador (claim do JWT). Sem isso: `"User identification is required, verify!"`.

```bash theme={null}
curl -s -X POST "https://api.deumboom.com/core/v1/conversation" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
    "type": "ONE_ON_ONE",
    "title": "1:1 de setembro — Mariana Costa",
    "status": "NO_ACTION",
    "description": "Acompanhamento de metas e acordos da quinzena.",
    "conversationDate": "2026-09-18T14:00:00",
    "reviewDate": "2026-10-18T14:00:00"
  }'
```

```json theme={null}
{
  "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "type": "ONE_ON_ONE",
  "title": "1:1 de setembro — Mariana Costa",
  "status": "NO_ACTION",
  "createdById": "019e0253-1111-7b31-8500-c7c061778fa9",
  "createdByName": "ana.lider",
  "description": "Acompanhamento de metas e acordos da quinzena.",
  "conversationDate": "2026-09-18T14:00:00",
  "reviewDate": "2026-10-18T14:00:00",
  "conversationParticipants": [],
  "createdAt": "2026-09-18T14:32:01.123456"
}
```

Validações frequentes:

| Mensagem | Causa |
| - | - |
| `Conversation type is required, verify!` | Faltou `type` |
| `Invalid conversation type, verify!` | Valor fora do enum |
| `Conversation status is required, verify!` | Faltou `status` |
| `Invalid Conversation Status, verify!` | Valor diferente de `NO_ACTION` |
| `Conversation title is required, verify!` | Faltou `title` |
| `Conversation title exceeds maximum length of 255 characters, verify!` | Título longo demais |
| `Conversation description is required, verify!` | `description` nulo |
| `Conversation date is required, verify!` | Faltou `conversationDate` |
| `Review date cannot be before conversation date, verify!` | `reviewDate` anterior à data da conversa |
| `User not found, verify!` | Usuário do token inexistente |
| `Company not found, verify!` | `companyId` inválido |

Em seguida vincule os participantes:

```http theme={null}
POST /core/v1/conversation-participant/bulk
Content-Type: application/json

[
  {
    "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
    "employeeId": "019e9c85-e6b7-7638-b475-7b5fb36f1785"
  }
]
```

Lista vazia → `"Conversation Participant list is empty. Verify input."`\
Conversa ou colaborador inexistente → `"Conversation not found, verify!"` / `"Employee not found, verify!"`.

Resposta de um participante:

```json theme={null}
{
  "conversationParticipantId": "019e9d01-0000-7000-8000-000000000001",
  "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "conversationName": "1:1 de setembro — Mariana Costa",
  "employeeId": "019e9c85-e6b7-7638-b475-7b5fb36f1785",
  "employeeName": "Mariana Costa",
  "createdAt": "2026-09-18T14:33:00"
}
```

***

## Consultar

### Por ID

```http theme={null}
GET /core/v1/conversation/{conversation-id}
```

Liderança / RH BP fora do recorte → `403` `"Access denied: conversation outside of your scope"`.\
Empresa diferente da do usuário → `403` `"Access denied: conversation belongs to a different company"`.\
ID inválido → `"Conversation ID is invalid, verify!"`.\
Inexistente → `"Conversation not found, verify!"`.

### Por empresa

```http theme={null}
GET /core/v1/conversation/read-all/company/{company-id}
```

Admin Cliente e RH Estratégico recebem todas as conversas da empresa. Liderança e RH BP recebem só as da **árvore de clusters acessível** (Unidade, Diretoria, Departamento, Alocação e White Labels). Sem cluster acessível, a lista vem vazia.

`GET /core/v1/conversation/read-all` lista registros ativos **sem filtro de empresa** — uso interno, não use em integração de cliente.

### Filtro paginado

```http theme={null}
POST /core/v1/conversation/read-filter
Content-Type: application/json

{
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "title": "1:1",
  "typeList": ["ONE_ON_ONE", "FEEDBACK"],
  "createdByUserIds": ["019e0253-1111-7b31-8500-c7c061778fa9"],
  "participantEmployeeIds": ["019e9c85-e6b7-7638-b475-7b5fb36f1785"],
  "conversationDateStart": "2026-09-01T00:00:00",
  "conversationDateEnd": "2026-09-30T23:59:59",
  "reviewDateStart": null,
  "reviewDateEnd": null,
  "page": 0,
  "size": 50
}
```

| Campo | Tipo |
| - | - |
| `title` | string (contém, case-insensitive no SQL) |
| `companyId` | uuid |
| `typeList` | string\[] |
| `createdByUserIds` | uuid\[] |
| `participantEmployeeIds` | uuid\[] |
| `conversationDateStart` / `conversationDateEnd` | datetime |
| `reviewDateStart` / `reviewDateEnd` | datetime |
| `page` | int (0-based) |
| `size` | int (≥ 1) |

`size` \< 1 → `"Size is less than 1, verify!"`.\
`page` \< 0 → `"Page is less than 0, verify!"`.\
Tipo inválido no filtro → `"Conversation type is invalid, verify!"`.

Envelope:

```json theme={null}
{
  "page": 0,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1,
  "data": [ { } ]
}
```

O mesmo recorte de liderança do `read-all/company` vale neste filtro.

***

## Atualizar e excluir

O `PUT` exige `conversationId` e os mesmos campos obrigatórios da criação. `createdBy` e `createdAt` são preservados.

```http theme={null}
PUT /core/v1/conversation
Content-Type: application/json

{
  "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "type": "ONE_ON_ONE",
  "title": "1:1 de setembro — Mariana Costa (revisado)",
  "status": "NO_ACTION",
  "description": "Acordos atualizados após a revisão.",
  "conversationDate": "2026-09-18T14:00:00",
  "reviewDate": "2026-10-25T14:00:00"
}
```

```http theme={null}
DELETE /core/v1/conversation/{conversation-id}
DELETE /core/v1/conversation-participant/{conversation-participant-id}
```

***

## Comentários e anexos

Create e update: `Content-Type: multipart/form-data`.

| Part | Conteúdo |
| - | - |
| `data` | JSON do comentário |
| `file`, `file_0`, `file_1`, … | Anexos |

O comentário precisa de **texto ou pelo menos um anexo**. Sem os dois: `"Comment must contain text or at least one attachment!"`.

Formatos aceitos: `jpg`, `jpeg`, `png`, `webp`, `pdf`, `docx`, `xlsx`, `pptx`, `csv`, `txt`, `md`. Tamanho máximo: **25 MB** por arquivo.

```bash theme={null}
curl -s -X POST "https://api.deumboom.com/core/v1/conversation-comment" \
  -H "Authorization: Bearer ${JWT}" \
  -F 'data={"conversationId":"019e9cbd-19ba-79f1-b9de-17c5658f3600","comment":"Follow-up da quinzena."};type=application/json' \
  -F "file=@anexo.pdf"
```

Resposta (campos principais):

```json theme={null}
{
  "conversationCommentId": "019e9d10-0000-7000-8000-000000000002",
  "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "userId": "019e0253-1111-7b31-8500-c7c061778fa9",
  "userName": "ana.lider",
  "comment": "Follow-up da quinzena.",
  "createdAt": "2026-09-18T15:00:00",
  "updatedAt": "2026-09-18T15:00:00",
  "attachments": [
    {
      "conversationCommentAttachmentId": "…",
      "fileName": "stored-name.pdf",
      "originalName": "anexo.pdf",
      "fileUrl": "https://…",
      "contentType": "application/pdf",
      "size": 120411
    }
  ]
}
```

No `PUT`, envie `conversationCommentId`, `conversationId` e, se for o caso, `removeAttachmentIds` (uuids dos anexos a remover). Só o **autor** edita o próprio comentário (`403` `"Access denied: you can only edit your own comments"`). Exclusão: autor, **ou** Admin Cliente / RH Estratégico da empresa.

***

## Permissões e isolamento

| Perfil | Cria / edita | Visualiza |
| - | - | - |
| Admin Cliente, RH Estratégico | sim (empresa) | todas as conversas da empresa |
| RH Business Partner, Liderança | sim, no recorte de clusters | só a árvore de atuação |
| GPS Admin Cliente | não | não (`conversation:*` ausente da policy) |
| Colaborador (participante) | não | não — o registro é ferramenta de gestão |

O colaborador em `employeeId` **não** recebe convite e **não** acessa o registro. Detalhe do produto: [Conversas no Core](/core/sensores/conversas).

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Qual a diferença entre a V1 e a V2?">
    A V1 é o CRUD da plataforma (três recursos, multipart nos comentários). A [V2](/api/conversas-v2) é o contrato estável para integração e MCP: um recurso `/v2/conversas`, participantes no mesmo POST e recorte explícito de perfil.
  </Accordion>

  <Accordion title="Posso criar conversa e participantes no mesmo POST?">
    Não nesta versão. Use `POST /core/v1/conversation` e depois `POST /core/v1/conversation-participant` (ou `/bulk`). Na V2 os participantes entram no body da criação.
  </Accordion>

  <Accordion title="O token bvt_ funciona aqui?">
    Não. Estas rotas exigem JWT de um usuário com `conversation:read` / `conversation:manage`.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.