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.
| 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.
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.
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.
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>.
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.