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

# Conversas e mensagens

> Listar conversas, ler o histórico em ordem, responder com citação e como saber o que mudou.

Uma conversa (ticket) reúne as mensagens trocadas com um contato numa conexão. Este guia cobre leitura e resposta; para criar conversas do zero, veja [Enviar mensagens](/pt/guias/enviar-mensagens).

<Steps>
  <Step title="Liste conversas abertas">
    [`GET /v1/conversations`](/pt/referencia/conversas/listar-conversas) filtra por `status` (CSV), `whatsappId` (conexão) e `searchParam` (nome/número/última mensagem). Requer escopo `conversations:read`.

    ```bash theme={null}
    curl "https://sua-instancia.whatix.cloud/wapi/v1/conversations?status=open&pageSize=50" \
      -H "Authorization: Bearer wtx_live_SEU_TOKEN"
    ```

    <Note>Não existe filtro de fila (`queueId`) nesse endpoint. Cada conversa traz `queue` no objeto de resposta — filtre pelo lado do seu código se precisar restringir a uma fila específica.</Note>
  </Step>

  <Step title="Leia as mensagens em ordem">
    [`GET /v1/conversations/{ticketId}/messages`](/pt/referencia/mensagens/listar-mensagens-de-uma-conversa) devolve **as mais recentes primeiro**: a página 1 traz as últimas N mensagens da conversa (já em ordem cronológica dentro da própria página), a página 2 traz as N anteriores a essas, e assim por diante. Requer escopo `messages:read`. Diferente dos outros endpoints, o `pageSize` aqui tem default `100` e máximo `200` — conversas costumam ter muito mais mensagens do que outras listas têm registros.

    ```bash theme={null}
    curl "https://sua-instancia.whatix.cloud/wapi/v1/conversations/482/messages?pageSize=100" \
      -H "Authorization: Bearer wtx_live_SEU_TOKEN"
    ```

    <Note>Pra reconstruir o histórico completo em ordem cronológica, pagine até `hasMore: false` (veja [Paginação e filtros](/pt/paginacao-e-filtros)) e depois **inverta** a ordem das páginas — a página mais alta é a mais antiga. Se só precisa das últimas mensagens (ex.: preview de conversa), a página 1 já resolve sem inverter nada.</Note>
  </Step>

  <Step title="Responda citando a mensagem original">
    [`POST /v1/conversations/{ticketId}/messages`](/pt/referencia/mensagens/enviar-mensagem-numa-conversa-existente) envia texto, mídia (multipart) ou template numa conversa já existente. Use `quotedMsgId` para responder citando uma mensagem específica:

    ```bash theme={null}
    curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/conversations/482/messages \
      -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "body": "Já verifiquei, segue a resposta.", "quotedMsgId": "wamid.HBg...ABC" }'
    ```
  </Step>
</Steps>

## Como saber o que mudou

Ainda não existem webhooks de saída na API do Chat — o Whatix não notifica seu sistema quando chega mensagem nova ou o status de entrega muda. Enquanto isso não existe, a estratégia é polling:

* Consulte `GET /v1/conversations?status=open` periodicamente (a cada 15–30s para algo perto de tempo real, a cada alguns minutos para um painel).
* Para uma conversa específica que você já acompanha, releia `GET /v1/conversations/{ticketId}/messages` e compare pelo `id`/`createdAt` da última mensagem que você já processou — não existe parâmetro `updatedAfter` para filtrar só o que mudou, então a comparação é feita no seu lado.
* Respeite o rate limit de 120 req/min por token: se você faz polling de muitas conversas, distribua as chamadas no tempo em vez de disparar tudo de uma vez. Veja [Erros e limites](/pt/erros-e-limites).

```js theme={null}
let ultimoIdVisto = null;

async function verificarNovasMensagens(ticketId) {
  const r = await fetch(
    `https://sua-instancia.whatix.cloud/wapi/v1/conversations/${ticketId}/messages?pageSize=20`,
    { headers: { Authorization: "Bearer wtx_live_SEU_TOKEN" } }
  );
  const { messages } = await r.json();
  const novas = ultimoIdVisto
    ? messages.slice(messages.findIndex((m) => m.id === ultimoIdVisto) + 1)
    : messages;

  if (messages.length) ultimoIdVisto = messages[messages.length - 1].id;
  return novas;
}

setInterval(() => verificarNovasMensagens(482).then(console.log), 20_000);
```

<Note>Webhooks de saída (notificação push de mensagem recebida/status alterado) estão no radar, mas não fazem parte da API pública hoje. Se sua integração depende de latência baixa, prefira o [FlowBuilder](/pt/guias/disparar-flows) ou fale com o time Whatix sobre alternativas.</Note>

## Erros comuns

| Código | HTTP | Causa |
| - | - | - |
| `ERR_NO_TICKET_FOUND` | 404 | Conversa inexistente ou de outra conta. |
| `ERR_MESSAGE_NOT_FOUND` | 404 | Mensagem inexistente ou de outra conta. |
| `ERR_SCOPE_MISSING` | 403 | Token sem `conversations:read`/`messages:read`/`messages:send`. |

Veja o [catálogo completo de erros](/pt/erros-e-limites) e [paginação e filtros](/pt/paginacao-e-filtros) para o formato de `count`/`hasMore`.