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

# Conversas

> Endpoints para atribuir operadores, mudar status de atendimento e adicionar notas internas.

# Conversas

API dedicada para gerenciar atendimentos. Todos os endpoints **criam o contato automaticamente** se o telefone não existir.

<Note>
  Todos os endpoints requerem o header `X-Client-Token`. Veja [Autenticação](/api/autenticacao).
</Note>

## Base URL

```
https://wapi.stegia.com.br/functions/v1/conversations-api
```

***

## Atribuir Operador

```
POST /conversations-api/assign
```

Atribui uma conversa a um operador específico. Detecta transferências automaticamente e registra no histórico.

### Parâmetros

| Campo          | Tipo    | Obrigatório | Descrição                                                        |
| -------------- | ------- | ----------- | ---------------------------------------------------------------- |
| `instanceId`   | string  | ✅           | ID da instância                                                  |
| `phone`        | string  | ✅           | Número do contato                                                |
| `assignTo`     | string  | ✅           | E-mail ou UUID do operador                                       |
| `portfolio`    | boolean | ❌           | Se `true`, adiciona à carteira do operador (prioridade absoluta) |
| `departmentId` | string  | ❌           | UUID do departamento (preserva o atual se omitido)               |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/assign" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "assignTo": "joao@empresa.com",
    "portfolio": true
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "contactId": "uuid",
  "assignedTo": "user-uuid",
  "previousAssignedTo": null,
  "portfolio": true,
  "transferred": false,
  "departmentId": null
}
```

<Info>
  * O operador recebe **e-mail de notificação** automaticamente com link direto para a conversa.
  * Transferências (quando havia outro operador) são registradas em `chat_transfer_log` e geram nota interna na conversa.
  * Com `portfolio: true`, o contato passa a ser exclusivo do operador na fila.
</Info>

***

## Mudar Status

```
POST /conversations-api/status
```

Altera o status do atendimento (open / closed / pending). Útil para integrar fechamento de tickets em CRMs externos.

### Parâmetros

| Campo          | Tipo   | Obrigatório | Descrição                                   |
| -------------- | ------ | ----------- | ------------------------------------------- |
| `instanceId`   | string | ✅           | ID da instância                             |
| `phone`        | string | ✅           | Número do contato                           |
| `status`       | string | ✅           | `open`, `closed` ou `pending`               |
| `internalNote` | string | ❌           | Nota interna registrada junto com a mudança |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/status" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "status": "closed",
    "internalNote": "Ticket resolvido via CRM externo"
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "contactId": "uuid",
  "status": "closed",
  "noteAdded": true
}
```

***

## Adicionar Nota Interna

```
POST /conversations-api/note
```

Adiciona uma nota interna na conversa (não enviada ao cliente, visível apenas para operadores).

### Parâmetros

| Campo        | Tipo   | Obrigatório | Descrição         |
| ------------ | ------ | ----------- | ----------------- |
| `instanceId` | string | ✅           | ID da instância   |
| `phone`      | string | ✅           | Número do contato |
| `note`       | string | ✅           | Conteúdo da nota  |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/note" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "note": "Cliente solicitou retorno em 3 dias úteis."
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "contactId": "uuid",
  "noteId": "uuid-da-nota"
}
```

***

## Buscar Mensagens (Histórico)

```
GET /messages-context
```

Retorna o histórico de mensagens de **um contato** (telefone) dentro de um intervalo de datas. Útil para exportar conversas, alimentar dashboards externos ou montar contexto para LLMs.

<Note>
  Este endpoint usa a base `https://wapi.stegia.com.br/functions/v1/messages-context` (não pertence ao grupo `conversations-api`).
</Note>

### Parâmetros (query string)

| Campo            | Tipo    | Obrigatório | Descrição                                                                        |
| ---------------- | ------- | ----------- | -------------------------------------------------------------------------------- |
| `phone`          | string  | ✅           | Número do contato (somente dígitos, com DDI)                                     |
| `start`          | string  | ✅           | Data inicial no formato `YYYY-MM-DD`                                             |
| `end`            | string  | ✅           | Data final no formato `YYYY-MM-DD`                                               |
| `instanceId`     | string  | ✅\*         | UUID da instância, `instance_id` do WhatsApp Business ou `embed_key` (`emb_...`) |
| `connectedPhone` | string  | ✅\*         | Alternativa a `instanceId`: número conectado da instância                        |
| `limit`          | number  | ❌           | Máximo de mensagens retornadas (padrão `100`)                                    |
| `fromMe`         | boolean | ❌           | `true` = só enviadas, `false` = só recebidas, omitido = ambas                    |
| `attachments`    | boolean | ❌           | `false` oculta URLs de mídia (padrão `true`)                                     |
| `format`         | string  | ❌           | `conversation` (padrão, formatado para LLM) ou `raw` (linhas brutas)             |
| `includeMeta`    | boolean | ❌           | Inclui `messageId`, `messageType`, `chatName`, etc. (padrão `true`)              |

<Info>
  `*` Informe **um dos dois**: `instanceId` **ou** `connectedPhone`.
</Info>

### Exemplo

```bash theme={null}
curl -X GET "https://wapi.stegia.com.br/functions/v1/messages-context?phone=5511999999999&start=2026-06-01&end=2026-06-15&instanceId=SUA_INSTANCIA&limit=200" \
  -H "X-Client-Token: SEU_TOKEN"
```

### Resposta (`format=conversation`)

```json theme={null}
{
  "phone": "5511999999999",
  "period": { "start": "2026-06-01", "end": "2026-06-15" },
  "totalMessages": 42,
  "conversation": [
    {
      "role": "user",
      "sender": "João Silva",
      "content": "Olá, gostaria de saber mais sobre o plano.",
      "timestamp": 1718524800,
      "status": "received",
      "messageId": "uuid",
      "messageType": "text",
      "isGroup": false,
      "chatName": null,
      "cardId": null
    },
    {
      "role": "assistant",
      "sender": "Você",
      "content": "Claro! Posso te enviar os detalhes agora.",
      "timestamp": 1718524860,
      "status": "sent"
    }
  ],
  "instanceInfo": {
    "instanceId": "...",
    "zapiInstanceId": "uuid"
  }
}
```

Use `format=raw` para receber as mensagens cruas (sem agrupamento `role`/`sender`), úteis para data warehouse.

***

## Comportamentos Automáticos

<AccordionGroup>
  <Accordion title="Auto-criação de Contato">
    Se o `phone` não existir, o contato é criado com `origin: "api"` antes de aplicar a operação.
  </Accordion>

  <Accordion title="Detecção de Transferência">
    Quando `assign` é chamado e a conversa já tem outro operador atribuído, o sistema:

    1. Atualiza para o novo operador
    2. Registra a transferência em `chat_transfer_log`
    3. Cria nota interna automática com nomes dos operadores envolvidos
    4. Notifica o novo operador por e-mail
  </Accordion>

  <Accordion title="Notificação por E-mail">
    A atribuição via API dispara o mesmo e-mail de notificação enviado quando um operador é atribuído pelo painel — garantindo consistência em qualquer fluxo.
  </Accordion>
</AccordionGroup>