# Consultar e enviar conversas pela API

A API de conversas permite ler o inbox e enviar mensagens pelo PipeFácil.

Todas as rotas deste grupo exigem o recurso `ADVANCED_API`. As rotas de leitura também exigem a permissão `whatsapp.view_conversations`.

## Rotas disponíveis

| Ação             | Método e rota                                          | Uso                                               |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------- |
| Listar conversas | `GET /api/v1/conversations`                            | Retorna as conversas visíveis ao membro da chave. |
| Listar mensagens | `GET /api/v1/conversations/{conversationKey}/messages` | Retorna o histórico de uma conversa.              |
| Enviar mensagem  | `POST /api/v1/conversations/messages`                  | Envia uma mensagem pelo canal escolhido.          |

Em `GET /api/v1/conversations`, use `filter`, `responsibleId`, `pipelineId`, `stageId`, `source` ou `channelIds` para restringir o resultado. A busca por texto aceita o contato e o telefone.

## Ler o histórico continuamente

Sem `since`, a listagem de mensagens começa pelas mais recentes e pagina para trás. Com `since`, a API pagina para frente a partir do instante informado.

O parâmetro `since` é inclusivo. Ao consultar novamente, remova mensagens repetidas pelo identificador da mensagem. Ao continuar uma página para frente, envie `since` junto com `cursor`.

Uma conversa fora da visibilidade da chave responde `404`. A visibilidade segue o membro que emitiu a chave, incluindo o acesso somente aos próprios registros.

## Enviar uma mensagem

Em `POST /api/v1/conversations/messages`, `type` assume `text` quando omitido. Informe `channelId` ou `senderPhoneNumberId` para escolher o canal. Sem esses campos, a API usa o canal padrão do workspace.

A mensagem é atribuída ao membro que emitiu a chave. O caminho legado `POST /api/v1/messages` continua disponível para clientes antigos, mas novas integrações devem usar a rota de conversas.

## Filtros e ordenação

`filter` aceita `all`, `unread`, `returned`, `internal` e `closed`. Os quatro primeiros consultam conversas abertas; `closed` consulta as fechadas. `sort` aceita `recent` ou `oldest`; mantenha o valor enquanto percorre o cursor.

Use `conversationKey` retornada pelo servidor para consultar mensagens. Para Instagram, o destino técnico pode vir em `contactInstagramId`, no formato `ig:<IGSID>`.

## Janela de envio e alterações de mensagens

Na Cloud API, a janela de atendimento pertence ao par contato/canal. `lastInboundAt` da conversa é agregado entre canais e não comprova uma janela aberta no canal que você pretende usar.

As mensagens incluem `editedAt` e `deletedAt` quando aplicáveis. O corpo de uma mensagem apagada pode continuar disponível para auditoria; a integração deve decidir como ocultá-lo na interface. Não confunda consulta do histórico com uma API de edição ou exclusão de mensagens: essas operações não estão expostas neste contrato público.

## Próximos passos

- [Autenticar na API pública](/developers/authentication/)
- [Referência completa da API](/api/)